[jhenin]

Depends on #995 (this PR targets its branch, and GitHub will retarget it to master once #995 is merged).

Adds a make latexml target that builds a multi-page HTML version of each engine's manual with LaTeXML, in doc/html-<engine>/. The existing tex4ht build (make html) and the website install targets are left unchanged for now.

Output

• One page per section, named after the section labels (e.g. sec_colvarbias/index.html); LATEXML_SPLITAT=subsection gives shorter pages. The navigation menu is a sidebar on the left that expands the current page's sub-items; on narrow screens it moves above the content.
• MathML, typeset by MathJax (from the jsDelivr CDN) by default; LATEXML_MATHJAX=no uses the browsers' native MathML rendering and no JavaScript.
• A stylesheet with the colors of the PDF: section boxes, keyword names, and the three kinds of example blocks. Example blocks copy as valid input: $<$...$>$ placeholders become literal <...>, and quotes stay ASCII.
• Index entries link directly to the keywords instead of "12nd item" (latexml/fix_index.py).
• Links between the manuals of different engines, and to the PDF, are relative (../html-<engine>/index.html).

Source changes

• doc/latexml/: LaTeXML bindings of the manual's macros (\cvsec, \key, \keydef, example environments, ...), stubs for packages LaTeXML can't process (babel, mdframed, catchfile), the stylesheet, and a README with the design, the LaTeXML pitfalls found, and the remaining work.
• colvars-refman.tex: \iflatexml skips the LaTeX definitions of the macros reimplemented for LaTeXML; \ifcvhtml is true for any HTML build (LaTeXML or tex4ht) and selects PNG figures. The title page and the links to the other manuals were factored into macros shared by all builds.
• colvars-refman-main.tex: \ifcvhtml for the two PNG figures; removed an unused \labelkey on a section heading, which LaTeXML would use as the page name.

Testing

• make -j5 latexml (about 90 s): all five engines build with 0 errors and 2 warnings (one multi-line aligned equation that LaTeXML's math parser doesn't fully understand; it still displays). A link checker over all pages found no broken internal links.
• The NAMD and Tinker-HP PDFs still build without errors or undefined references.
• Not tested: the tex4ht build. Run without a terminal, it stops at a natbib prompt ("Bibliography not compatible with author-year citations"), on master as well.

Not in this PR (see doc/latexml/README.md)

• Installing the new HTML on the website, and switching the PDF's "HTML version" link to it.
• Keeping old URLs such as colvars-refman-vmd.html#sec:dashboard working, e.g. with a redirect page. Keyword anchors already use the original labels (#abf|fullSamples).
• Citations are author-year in the HTML but numeric in the PDF.

Requires LaTeXML ≥ 0.8.8 (installation notes in the README).

🤖 Generated with Claude Code

[HanatoK]

If you use Claude to directly open new PRs, maybe you need to ask Claude to follow the PR template proposed in #963.

[giacomofiorin]

I tried this offline using our current container, and I got:

$ make latexml
convert -flatten -resize 512x576 eulerangles.pdf eulerangles-512px.png
WARNING: The convert command is deprecated in IMv7, use "magick" instead of "convert" or "magick convert"

Building html-gromacs/index.html with release label "doc_latexml"
rm -rf html-gromacs ; mkdir -p html-gromacs
latexmlc --path=latexml --preload=colvars-latexml.sty --css=latexml/colvars-refman.css --javascript=https://cdn.jsdelivr.net/npm/mathjax@3/es5/mml-chtml.js --format=html5 --split --splitat=section --splitnaming=labelrelative --urlstyle=file --navigationtoc=context --log=html-gromacs/latexml.log --destination=html-gromacs/index.html colvars-refman-gromacs.tex \
	> html-gromacs/latexml.out 2>&1 || (tail -20 html-gromacs/latexml.out; false)
/bin/sh: line 1: latexmlc: command not found
make: *** [Makefile:107: html-gromacs/index.html] Error 1

Can you please create a new container with the necessary toolkit and use it for the CI tests (which also need updating to run make latexml)?

Once everything works and the switch is made we can delete the Fedora container that we are using currently (and to which I don't think anyone is particularly attached)

[Copilot]

🟡 Changes recommended

The HTML build rule omits required TeX input dependencies, causing incremental builds to silently retain stale version and command-reference content.

1 open issue

• Add omitted \input files to the LaTeXML prerequisites · New

What changed in this PR

Adds an optional LaTeXML build for multi-page, engine-specific HTML manuals alongside the existing PDF and tex4ht builds.

Changes:

• Adds make latexml with configurable page splitting, MathJax rendering, and URL styles.
• Introduces macro bindings, responsive styling, and index-link post-processing.
• Adapts shared manual sources for LaTeXML and documents setup and remaining migration work.

File	Description
doc/​Makefile	Adds LaTeXML build options, targets, and cleanup.
doc/​latexml/​README.md	Documents design, installation, usage, and limitations.
doc/​latexml/​mdframed.sty.ltxml	Provides a lightweight framed-block binding.
doc/​latexml/​fix_index.py	Rewrites index links with meaningful labels.
doc/​latexml/​colvars-refman.css	Styles navigation, headings, keywords, and examples.
doc/​latexml/​colvars-latexml.sty.ltxml	Implements manual macros and copyable example blocks.
doc/​latexml/​catchfile.sty.ltxml	Supports release-label and file-content loading.
doc/​latexml/​babel.sty.ltxml	Provides an English-only babel compatibility stub.
doc/​colvars-refman.tex	Adds HTML conditionals and shared title-page macros.
doc/​colvars-refman-main.tex	Selects HTML-friendly figures and removes an unused heading label.
doc/​.gitignore	Ignores generated LaTeXML output directories.

_{Review effort: Balanced}