From f0182e1cb57ca1e7f0b60781b83e387675c4e611 Mon Sep 17 00:00:00 2001
From: Mauro Bieg <mb21@users.noreply.github.com>
Date: Tue, 7 Nov 2017 21:43:36 +0100
Subject: [PATCH] MANUAL: consolidate math documentation (#4049)
---
MANUAL.txt | 151 +++++++++++++++++++++++------------------------------
1 file changed, 66 insertions(+), 85 deletions(-)
diff --git a/MANUAL.txt b/MANUAL.txt
index 688d8f74a..fc461847c 100644
--- a/MANUAL.txt
+++ b/MANUAL.txt
@@ -1075,53 +1075,37 @@ Citation rendering
Math rendering in HTML
----------------------
-`-m` [*URL*], `--latexmathml`[`=`*URL*]
-
-: Use the [LaTeXMathML] script to display embedded TeX math in HTML output.
- To insert a link to a local copy of the `LaTeXMathML.js` script,
- provide a *URL*. If no *URL* is provided, the contents of the
- script will be inserted directly into the HTML header, preserving
- portability at the price of efficiency. If you plan to use math on
- several pages, it is much better to link to a copy of the script,
- so it can be cached.
-
-`--mathml`
-
-: Convert TeX math to [MathML] (in `docbook4`, `docbook5`, `jats`,
- `html4` and `html5`). This is the default in `odt` output.
-
-`--jsmath`[`=`*URL*]
-
-: Use [jsMath] to display embedded TeX math in HTML output.
- The *URL* should point to the jsMath load script (e.g.
- `jsMath/easy/load.js`); if provided, it will be linked to in
- the header of standalone HTML documents. If a *URL* is not provided,
- no link to the jsMath load script will be inserted; it is then
- up to the author to provide such a link in the HTML template.
+The default is to render TeX math as far as possible using Unicode characters.
+Formulas are put inside a `span` with `class="math"`, so that they may be styled
+differently from the surrounding text if needed. However, this gives acceptable
+results only for basic math, usually you will want to use `--mathjax` or another
+of the following options.
`--mathjax`[`=`*URL*]
: Use [MathJax] to display embedded TeX math in HTML output.
+ TeX math will be put between `\(...\)` (for inline math)
+ or `\[...\]` (for display math) and wrapped in `<span>` tags
+ with class `math`. Then the MathJax JavaScript will render it.
The *URL* should point to the `MathJax.js` load script.
- If a *URL* is not provided, a link to the MathJax CDN will
+ If a *URL* is not provided, a link to the Cloudflare CDN will
be inserted.
+
+`--mathml`
-`--gladtex`
-
-: Enclose TeX math in `<eq>` tags in HTML output. These can then
- be processed by [gladTeX] to produce links to images of the typeset
- formulas.
-
-`--mimetex`[`=`*URL*]
-
-: Render TeX math using the [mimeTeX] CGI script. If *URL* is not
- specified, it is assumed that the script is at `/cgi-bin/mimetex.cgi`.
+: Convert TeX math to [MathML] (in `epub3`, `docbook4`, `docbook5`, `jats`,
+ `html4` and `html5`). This is the default in `odt` output. Note that
+ currently only Firefox and Safari (and select e-book readers) natively
+ support MathML.
`--webtex`[`=`*URL*]
-: Render TeX formulas using an external script that converts TeX
- formulas to images. The formula will be concatenated with the URL
- provided. If *URL* is not specified, the CodeCogs will be used.
+: Convert TeX formulas to `<img>` tags that link to an external script
+ that converts formulas to images. The formula will be URL-encoded
+ and concatenated with the URL provided. For SVG images you can for
+ example use `--webtex https://latex.codecogs.com/svg.latex?`.
+ If no URL is specified, the CodeCogs URL generating PNGs
+ will be used (`https://latex.codecogs.com/png.latex?`).
Note: the `--webtex` option will affect Markdown output
as well as HTML, which is useful if you're targeting a
version of Markdown without native math support.
@@ -1131,7 +1115,6 @@ Math rendering in HTML
: Use [KaTeX] to display embedded TeX math in HTML output.
The *URL* is the base URL for the KaTeX library. If a *URL* is
not provided, a link to the KaTeX CDN will be inserted.
- Note: [KaTeX] seems to work best with `html5` output.
`--katex-stylesheet=`*URL*
@@ -1139,6 +1122,49 @@ Math rendering in HTML
not specified, a link to the KaTeX CDN will be inserted. Note that this
option does not imply `--katex`.
+`-m` [*URL*], `--latexmathml`[`=`*URL*]
+
+: Use the [LaTeXMathML] script to display embedded TeX math in HTML output.
+ TeX math will be displayed between `$` or `$$` characters and put in
+ `<span>` tags with class `LaTeX`. The LaTeXMathML JavaScript will then
+ change it to MathML. Note that currently only Firefox and Safari
+ (and select e-book readers) natively support MathML.
+ To insert a link to a local copy of the `LaTeXMathML.js` script,
+ provide a *URL*. If no *URL* is provided, the contents of the
+ script will be inserted directly into the HTML header, preserving
+ portability at the price of efficiency. If you plan to use math on
+ several pages, it is much better to link to a copy of the script,
+ so it can be cached.
+
+`--jsmath`[`=`*URL*]
+
+: Use [jsMath] (the predecessor of MathJax) to display embedded TeX
+ math in HTML output. TeX math will be put inside `<span>` tags
+ (for inline math) or `<div>` tags (for display math) with class
+ `math` and rendered by the jsMath script. The *URL* should point to
+ the script (e.g. `jsMath/easy/load.js`); if provided, it will be linked
+ to in the header of standalone HTML documents. If a *URL* is not provided,
+ no link to the jsMath load script will be inserted; it is then
+ up to the author to provide such a link in the HTML template.
+
+`--gladtex`
+
+: Enclose TeX math in `<eq>` tags in HTML output. The resulting HTML
+ can then be processed by [gladTeX] to produce images of the typeset
+ formulas and an HTML file with links to these images.
+ So, the procedure is:
+
+ pandoc -s --gladtex input.md -o myfile.htex
+ gladtex -d myfile-images myfile.htex
+ # produces myfile.html and images in myfile-images
+
+`--mimetex`[`=`*URL*]
+
+: Render TeX math using the [mimeTeX] CGI script, which generates an
+ image for each TeX formula. This should work in all browsers. If
+ *URL* is not specified, it is assumed that the script is at
+ `/cgi-bin/mimetex.cgi`.
+
[MathML]: http://www.w3.org/Math/
[LaTeXMathML]: http://math.etsu.edu/LaTeXMathML/
[jsMath]: http://www.math.union.edu/~dpvc/jsmath/
@@ -2970,53 +2996,8 @@ FictionBook2
HTML, Slidy, DZSlides, S5, EPUB
~ The way math is rendered in HTML will depend on the
- command-line options selected:
-
- 1. The default is to render TeX math as far as possible using Unicode
- characters, as with RTF, DocBook, and OpenDocument output. Formulas
- are put inside a `span` with `class="math"`, so that they may be
- styled differently from the surrounding text if needed.
-
- 2. If the `--latexmathml` option is used, TeX math will be displayed
- between `$` or `$$` characters and put in `<span>` tags with class `LaTeX`.
- The [LaTeXMathML] script will be used to render it as formulas.
- (This trick does not work in all browsers, but it works in Firefox.
- In browsers that do not support LaTeXMathML, TeX math will appear
- verbatim between `$` characters.)
-
- 3. If the `--jsmath` option is used, TeX math will be put inside
- `<span>` tags (for inline math) or `<div>` tags (for display math)
- with class `math`. The [jsMath] script will be used to render
- it.
-
- 4. If the `--mimetex` option is used, the [mimeTeX] CGI script will
- be called to generate images for each TeX formula. This should
- work in all browsers. The `--mimetex` option takes an optional URL
- as argument. If no URL is specified, it will be assumed that the
- mimeTeX CGI script is at `/cgi-bin/mimetex.cgi`.
-
- 5. If the `--gladtex` option is used, TeX formulas will be enclosed
- in `<eq>` tags in the HTML output. The resulting `htex` file may then
- be processed by [gladTeX], which will produce image files for each
- formula and an HTML file with links to these images. So, the
- procedure is:
-
- pandoc -s --gladtex myfile.txt -o myfile.htex
- gladtex -d myfile-images myfile.htex
- # produces myfile.html and images in myfile-images
-
- 6. If the `--webtex` option is used, TeX formulas will be converted
- to `<img>` tags that link to an external script that converts
- formulas to images. The formula will be URL-encoded and concatenated
- with the URL provided. For SVG images you can for example use
- `--webtex https://latex.codecogs.com/svg.latex?`.
- If no URL is specified, the CodeCogs URL generating PNGs
- will be used (`https://latex.codecogs.com/png.latex?`).
-
- 7. If the `--mathjax` option is used, TeX math will be displayed
- between `\(...\)` (for inline math) or `\[...\]` (for display
- math) and put in `<span>` tags with class `math`.
- The [MathJax] script will be used to render it as formulas.
+ command-line options selected. Therefore see [Math rendering in HTML]
+ above.
[interpreted text role `:math:`]: http://docutils.sourceforge.net/docs/ref/rst/roles.html#math