1How to build the manual from source.
2====================================
3
4There are two scripts:
5
6 mkpdf.sh   -- creates a PDF file using pdflatex
7 mkhtml.sh  -- creates a HTML version using TeX4ht
8
9Prerequisites are:
10 1. a TeX installation, including pdflatex and makeindex (ie a standard TeX)
11 2. TeX4ht (see http://www.cse.ohio-state.edu/~gurari/TeX4ht/mn.html)
12
13The file reduce.cfg contains the necessary configuration lines for TeX4ht.
14
15
16LaTeX that works with TeX4ht HTML + MathJax output. FJW, March 2021
17
18Avoid tabbing environments, which don't translate well to HTML.  For
19columns consider a tabular environment.  For indentation of text
20consider a list environment, such as a description environment or if
21necessary a custom list.  For indentation of algorithms or program
22code consider using an appropriate number of ~ characters.
23
24To get correct alignment in tabular environments when using
25\multicolumn it may help to use @{~} as the first column specifier.
26
27New commands and environments that are used in math mode must be
28defined in math mode for use by MathJax (see the MathJax
29documentation), and they must be defined on every page that uses them.
30Any parameters *must* be enclosed in braces and definitions involving
31parameters must be within braces and preceded by \makehashletter,
32otherwise the # characters will be doubled and the definitions will
33fail.  (Thanks to Michal Hoftich <michal.h21@gmail.com> for suggesting
34changing the catcode of #.)  Definitions intended for MathJax cannot
35clash with any others, so \newcommand and \newenvironment are always
36appropriate.  See e.g. guardian.tex, near the top of the file, for an
37example.
38
39Avoid unnecessary use of math mode, and nesting of math mode within
40text mode within math mode within... .  For example, an array
41environment containing a lot of text might work better as a tabular
42environment.  Math-mode facilities that need information from the
43non-math environment, such as \lefteqn, \intertext and gather
44environments, do not work in MathJax and need to be implemented
45differently.  Align environments work but split environments may not.
46Commands related to page breaking, such as \\*, do not work, although
47\\ is fine.
48
49Headings below \subsubsection level should be avoided because they
50disappear in HTML.
51
52Nested tabular-type environments need to be handled specially, such as
53by implementing the inner environment as a new command that is called
54in the output environment; see specfn.tex, towards the end.
55
56Excessively convoluted LaTeX is best avoided and is often unnecessary,
57even if it works in normal LaTeX.
58
59MathJax supports \ref{} and \eqref{}, which must appear verbatim as
60text within the HTML.  The \eqref macro can easily be redefined to
61output itself verbatim, but \ref should only be output verbatim when
62it refers to an equation.  I therefore define a macro \eqnref in
63manual.tex, which outputs \ref{} verbatim when generating MathJax
64output and calls \ref otherwise.  Uses of \ref that relate to
65equations must be changed to \eqnref for this mechanism to work.
66