Skip to content

doc: build the HTML manuals with LaTeXML #996

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jhenin wants to merge 1 commit into from
Open

doc: build the HTML manuals with LaTeXML #996

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,4 @@
*.tmp
*.xref
*-eps-converted-to.pdf
html-*/
35 changes: 34 additions & 1 deletion doc/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.PHONY: all pdf html doxygen webpage webpage-legacy images \
.PHONY: all pdf html latexml doxygen webpage webpage-legacy images \
install install-images clean clean-all \
update-code-refs update-cvscript-cmdline-doc updates update-version-list

Expand Down Expand Up @@ -78,6 +78,38 @@ HTLATEX_OPTS = "html5mjlatex.cfg, charset=utf-8" " -cunihtf -utf8"
$(HTLATEX) $(notdir $<) $(HTLATEX_OPTS); \
bash postprocess_html.sh $@

# Multi-page HTML built with LaTeXML (replacement for the htlatex build, in
# progress: see latexml/README.md). Output: html-<engine>/index.html
LATEXMLC = latexmlc
# Set LATEXML_MATHJAX to anything but "yes" to use the browser's native
# MathML rendering (no JavaScript)
LATEXML_MATHJAX = yes
MATHJAX_URL = https://cdn.jsdelivr.net/npm/mathjax@3/es5/mml-chtml.js
# One page per "section" or per "subsection" (the menu expands level by level)
LATEXML_SPLITAT = section
# "file": links include index.html, so pages can be browsed locally;
# "server": links to folders (e.g. sec_colvar/), only through a web server
LATEXML_URLSTYLE = file
LATEXML_OPTS = --path=latexml --preload=colvars-latexml.sty \
--css=latexml/colvars-refman.css \
$(if $(filter yes,$(LATEXML_MATHJAX)),--javascript=$(MATHJAX_URL)) \
--format=html5 --split --splitat=$(LATEXML_SPLITAT) \
--splitnaming=labelrelative --urlstyle=$(LATEXML_URLSTYLE) \
--navigationtoc=context
LATEXML_HTML = $(foreach _,${ENGINES},html-$_/index.html)

latexml: images $(LATEXML_HTML)

html-%/index.html: colvars-refman-%.tex colvars-refman-main.tex colvars-refman.tex \
$(BIBTEX) colvars-code-refs.bib $(IMAGES) $(wildcard latexml/*) Makefile
@echo "Building $@ with release label \"${COLVARS_RELEASE}\""
rm -rf html-$* ; mkdir -p html-$*
$(LATEXMLC) $(LATEXML_OPTS) --log=html-$*/latexml.log --destination=$@ $< \
> html-$*/latexml.out 2>&1 || (tail -20 html-$*/latexml.out; false)
python3 latexml/fix_index.py html-$*/idx.html
@echo "$@: $$(grep -cE '^(Error|Fatal):' html-$*/latexml.log) errors," \
"$$(grep -cE '^Warning:' html-$*/latexml.log) warnings (see html-$*/latexml.log)"

spin-tilt-scheme-512px.png: spin-tilt-scheme.pdf
convert -flatten -resize 512x300 $^ $@

Expand All @@ -89,6 +121,7 @@ clean:

clean-all: clean
rm -f $(PDF) $(HTML) $(CSS)
rm -rf $(LATEXML_HTML:/index.html=)
rm -fr doxygen/html
@echo
@echo "Note: only removed files that this branch is set to build."
Expand Down
5 changes: 2 additions & 3 deletions doc/colvars-refman-main.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2647,7 +2647,7 @@
\end{itemize}
The schematic below, adapted from ref.\ \citealp{Fiorin2024}, illustrates the use of the two angles to model the rotations of a membrane protein:
\begin{center}
\ifdefined\HCode
\ifcvhtml
\includegraphics{spin-tilt-scheme-512px.png}
\else
\includegraphics[width=\textwidth]{spin-tilt-scheme.pdf}
Expand Down Expand Up @@ -2793,7 +2793,7 @@
\end{itemize}

\begin{center}
\ifdefined\HCode
\ifcvhtml
\includegraphics{eulerangles-512px.png}
\else
\includegraphics[width=0.5\textwidth]{eulerangles.pdf}
Expand Down Expand Up @@ -3784,7 +3784,6 @@
\end{cvexampleinput}

\cvsubsec{Dense neural network in CV space (MLCV)}{sec:cvc_neuralNetwork}
\labelkey{colvar|NeuralNetwork}

This colvar component computes a non-linear combination of other scalar colvar components, where the transformation is defined by a dense neural network.\cite{Chen2022}
The network can be optimized using any framework, and its parameters are provided to Colvars in plain text files, as detailed below.
Expand Down
87 changes: 55 additions & 32 deletions doc/colvars-refman.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,17 @@
% Colvars repository at GitHub.

\documentclass[11pt]{article}

% \iflatexml is true only when building HTML with LaTeXML, which preloads
% latexml/colvars-latexml.sty.ltxml (LaTeXML versions of the macros below)
\ifdefined\iflatexml\else
\expandafter\newif\csname iflatexml\endcsname
\fi

% \ifcvhtml is true for any HTML output (LaTeXML or tex4ht)
\newif\ifcvhtml
\iflatexml\cvhtmltrue\fi
\ifdefined\HCode\cvhtmltrue\fi
\usepackage[margin=1in]{geometry}

\usepackage[english]{babel}
Expand Down Expand Up @@ -36,6 +47,7 @@
\usepackage{xcolor} % Needed for HTML version
\usepackage{mdframed}

\iflatexml\else % Example environments: see colvars-latexml.sty.ltxml
\definecolor{cvexample-border-color}{rgb}{0.5,0.0,0.5}
\definecolor{cvexample-background-color}{rgb}{1.0,0.95,1.0}
\definecolor{cvkeyword-background-color}{rgb}{0.95,0.8,0.95}
Expand Down Expand Up @@ -70,6 +82,7 @@
\ifdefined\HCode\HCode{</pre>}\else\end{ttfamily}\fi
\end{mdframed}
}
\fi % \iflatexml

% Note: the Python version is currently not built yet
\newcommand{\cvscriptexampleinputcv}[2]{%
Expand Down Expand Up @@ -138,6 +151,37 @@
}
\fi

% Links to the manuals for all engines. LaTeXML: relative links between
% the html-<engine>/ folders, which sit next to the PDFs (both in doc/ and in
% the release folder of the website)
\iflatexml
\newcommand{\cvmanualurl}[1]{../html-#1/index.html}
\newcommand{\cvmanualpdfurl}{../colvars-refman-\mdengine.pdf}
\else
\ifcvhtml\def\cvmanualext{html}\else\def\cvmanualext{pdf}\fi
\newcommand{\cvmanualurl}[1]{%
https://colvars.github.io/\cvreleaselabel/colvars-refman-#1.\cvmanualext}
\fi
\newcommand{\cvmanuallinks}{%
Updated versions of this manual:
[\href{\cvmanualurl{gromacs}}{GROMACS}]
[\href{\cvmanualurl{lammps}}{LAMMPS}]
[\href{\cvmanualurl{namd}}{NAMD}]
[\href{\cvmanualurl{tinkerhp}}{Tinker-HP}]
[\href{\cvmanualurl{vmd}}{VMD}]}
\newcommand{\cvmanualauthors}{Alejandro Bernardin, Haochuan Chen, Jeffrey R.{} Comer, Giacomo Fiorin, Haohao Fu, J\'er\^ome H\'enin, Axel Kohlmeyer, Fabrizio Marinelli, Hubert Santuz, Joshua V.{} Vermaas, Andrew D.{} White, Wei Zhang}

\iflatexml
\title{Collective Variables Module\\Reference manual for \MDENGINE{}}
\author{\cvmanualauthors}
\date{Code version: \cvversion}
\maketitle
\begin{center}
\includegraphics{cover-512px.jpg}
\end{center}
\noindent\cvmanuallinks\\
(\href{\cvmanualpdfurl}{PDF version})
\else
\begin{titlepage}

\noindent\colorbox{background-color}{
Expand All @@ -151,33 +195,7 @@

\noindent\textsf{\\Code version: \cvversion\\}

\noindent\textsf{Updated versions of this manual:
\ifdefined\HCode
[\href{https://colvars.github.io/\cvreleaselabel/colvars-refman-gromacs.html}{GROMACS}]
\else
[\href{https://colvars.github.io/\cvreleaselabel/colvars-refman-gromacs.pdf}{GROMACS}]
\fi
\ifdefined\HCode
[\href{https://colvars.github.io/\cvreleaselabel/colvars-refman-lammps.html}{LAMMPS}]
\else
[\href{https://colvars.github.io/\cvreleaselabel/colvars-refman-lammps.pdf}{LAMMPS}]
\fi
\ifdefined\HCode
[\href{https://colvars.github.io/\cvreleaselabel/colvars-refman-namd.html}{NAMD}]
\else
[\href{https://colvars.github.io/\cvreleaselabel/colvars-refman-namd.pdf}{NAMD}]
\fi
\ifdefined\HCode
[\href{https://colvars.github.io/\cvreleaselabel/colvars-refman-tinkerhp.html}{Tinker-HP}]
\else
[\href{https://colvars.github.io/\cvreleaselabel/colvars-refman-tinkerhp.pdf}{Tinker-HP}]
\fi
\ifdefined\HCode
[\href{https://colvars.github.io/\cvreleaselabel/colvars-refman-vmd.html}{VMD}]
\else
[\href{https://colvars.github.io/\cvreleaselabel/colvars-refman-vmd.pdf}{VMD}]
\fi
}
\noindent\textsf{\cvmanuallinks}

\end{minipage}}
% \noindent\rule{\textwidth}{2pt}
Expand All @@ -188,7 +206,7 @@
\else
\includegraphics[width=0.9\textwidth]{cover.jpg}\\
\fi
\textsf{\large Alejandro Bernardin, Haochuan Chen, Jeffrey R.{} Comer, Giacomo Fiorin, Haohao Fu, J\'er\^ome H\'enin, Axel Kohlmeyer, Fabrizio Marinelli, Hubert Santuz, Joshua V.{} Vermaas, Andrew D.{} White, Wei Zhang}
\textsf{\large \cvmanualauthors}

\ifdefined\HCode
\noindent{}(\href{https://colvars.github.io/\cvreleaselabel/colvars-refman-\mdengine.pdf}{PDF version})
Expand All @@ -200,16 +218,22 @@


\end{titlepage}
\fi % \iflatexml


\newpage
\label{sec:toc}%
\iflatexml\else\label{sec:toc}\fi%
\ifdefined\HCode\HCode{<selfref>}\ref{sec:toc}\HCode{</selfref>}\fi%
\tableofcontents
\newpage

% compiling the standalone reference manual

\newcommand{\gradx}{\mbox{\boldmath$\nabla_{\!\!x}\,$}}
\newcommand{\vx}{{\mbox{\boldmath{$x$}}}}
\newcommand{\bm}[1]{{\mbox{\boldmath{$#1$}}}}

\iflatexml\else % Keyword and sectioning macros: see colvars-latexml.sty.ltxml
% use macros with context field to document keywords
\newcommand{\key}[5]{%
\colorbox{cvkeyword-background-color}{\index{#2!\texttt{#1}}\texttt{#1}} --- \emph{#3}\vspace{1ex}\\%
Expand All @@ -230,9 +254,6 @@
\colorbox{cvkeyword-background-color}{\index{#2!\texttt{#1}}\texttt{#1}} --- analogous to \texttt{#3}%
}

\newcommand{\gradx}{\mbox{\boldmath$\nabla_{\!\!x}\,$}}
\newcommand{\vx}{{\mbox{\boldmath{$x$}}}}
\newcommand{\bm}[1]{{\mbox{\boldmath{$#1$}}}}

\newenvironment{cvcoptions}{%
\noindent\textbf{List of keywords} (see also \ref{sec:cvc_pbcs}, \ref{sec:cvc_common}, \ref{sec:cvc_periodic} and \ref{sec:cvc_superp} for additional options):
Expand Down Expand Up @@ -299,6 +320,8 @@
\fi
}


\fi % \iflatexml
\input{colvars-engine-flags}

\input{colvars-refman-main}
Expand Down
Loading
Loading