.\" Automatically generated by Pandoc 2.5
.\"
.TH "GLADTEX" "1" "8th of September 2018" "" ""
.hy
.SH NAME
.PP
\f[B]GladTeX\f[R] \- generate HTML with LaTeX formulas embedded as
images
.SH SYNOPSIS
.PP
\f[B]gladtex\f[R] OPTIONS
.SH DESCRIPTION
.PP
\f[B]GladTeX\f[R] is a formula preprocessor for HTML files.
It recognizes a special tag (\f[C]...\f[R]) marking formulas
for conversion.
The converted vector images are integrated into the output HTML
document.
This eases the process of creating HTML documents (or web sites)
containing formulas.
.PD 0
.P
.PD
The generated images are saved in a cache to not render the same image
over and over again.
This speeds up the process when formulas occur multiple times or when a
document is extended gradually.
.PP
The LaTeX formulas are preserved in the alt attribute of the embedded
images, hence screen reader users benefit from an accessible HTML
version of the document.
.PP
Furthermore it can be used with Pandoc to convert Markdown documents and
other formats with LaTeX formulas to HTML, EPUB and in fact to any
HTML\-based format, see the option \f[C]\-P\f[R].
.PP
See FILE FORMAT for an explanation of the file format and EXAMPLES for
examples on how to use GladTeX on its own or with Pandoc.
.SH OPTIONS
.TP
.B \f[B]INPUT FILE NAME\f[R]
Input .htex file with LaTeX formulas (if omitted or \-, stdin will be
read).
.TP
.B \f[B]\-h\f[R] \f[B]\[en]help\f[R]
Show this help message and exit.
.TP
.B \f[B]\-a\f[R]
Save text alternatives for images which are too long for the alt
attribute into a single separate file and link images to it.
.TP
.B \f[B]\-b\f[R] \f[I]BACKGROUND_COLOR\f[R]
Set background color for resulting images (default transparent).
GladTeX understands colors as provided by the \f[C]dvips\f[R] option of
the xcolor LaTeX package.
Alternatively, a 6\-digit hexadecimal value can be provided (as used
e.g.\ in HTML/CSS).
.TP
.B \f[B]\-c\f[R] \f[I]\f[CI]FOREGROUND_COLOR\f[I]\f[R]
Set foreground color for resulting images.
See the option above for a more in\-depth explanation.
.TP
.B \f[B]\-d\f[R] \f[I]DIRECTORY\f[R]
Directory in which to store the generated images in (relative path).
.PD 0
.P
.PD
The given path is interpreted relatively to the input file.
For instance,:
.RS
.IP
.nf
\f[C]
gladtex \-d img dir/file.htex
\f[R]
.fi
.PP
will create a \f[C]dir/img\f[R] directory and link accordingly in
\f[C]x/file.htex\f[R].
.RE
.TP
.B \f[B]\-e\f[R] \f[I]\f[CI]LATEX_MATHS_ENV\f[I]\f[R]
Set custom maths environment to surround the formula (e.g.\ flalign).
.TP
.B \f[B]\-E\f[R] \f[I]ENCODING\f[R]
Overwrite encoding to use (default UTF\-8).
.TP
.B \f[B]\-f\f[R] \f[I]FONTSIZE\f[R]
Overwrite the default font size of 12pt.
12pt is the default in most browsers and hence changing this might lead
to less\-portable documents.
.TP
.B \f[B]\-i\f[R] \f[I]CLASS\f[R]
CSS class to assign to inline math (default: `inlinemath').
.TP
.B \f[B]\-K\f[R]
keep LaTeX file(s) when converting formulas
.RS
.PP
By default, the generated LaTeX document, containing the formula to be
converted, are removed after the conversion (no matter whether it was
successful or not).
If it wasn\[cq]t successful, it is sometimes helpful to look at the
complete document.
This option will keep the file.
.RE
.TP
.B \f[B]\-l\f[R] \f[I]CLASS\f[R]
CSS class to assign to block\-level math (default: `displaymath').
.TP
.B \f[B]\-n\f[R]
Purge unreadable caches along with all eqn*.png files.
.RS
.PP
Caches can be unreadable if the used GladTeX version is incompatible.
If this option is unset, GladTeX will simply fail when the cache is
unreadable.
.RE
.TP
.B \f[B]\-m\f[R]
Print error output in machine\-readable format (less concise, better
parseable).
.RS
.PP
Each line will start with a key, followed by a colon, followed by the
value, i.e.\ \f[C]line: 5\f[R].
.RE
.TP
.B \f[B]\-o\f[R] \f[I]FILENAME\f[R]
Set output file name.
`\-' will print text to stdout.
Bydefault, input file name is used and the \f[C].htex\f[R] extension is
replaced by \f[C].html\f[R].
.TP
.B \f[B]\-p\f[R] \f[I]\f[CI]LATEX_STATEMENT\f[I]\f[R]
Add given LaTeX code to preamble of document.
That\[cq]ll affect the conversion of every image.
.TP
.B \f[B]\-P\f[R]
Act as a pandoc filter.
In this mode, input is expected to be a Pandoc JSON AST and the output
will be a modified AST, with all formulas replaced through HTML image
tags.
It makes sense to use \f[C]\-\f[R] as the input file for this option.
.TP
.B \f[B]\[en]png\f[R]
Switch from SVG to PNG as image output.
This image has several known issues, one of them being that images
won\[cq]t resize when zooming into the document.
It is also harder to work with for visually impaired users.
.TP
.B \f[B]\-r\f[R] \f[I]DPI\f[R]
Set resolution (size of images) to `dpi' (115 by default).
This is only available with the \f[C]\-\-png\f[R] option.
Also see the \f[C]\-f\f[R] option.
.TP
.B \f[B]\-R\f[R]
Replace non\-ascii (unicode) characters by LaTeX commands.
.RS
.PP
GladTeX can automatically detect non\-ascii characters in formulas and
replace them through their appropriate LaTeX commands.
In the alt attribute of the resulting image, alphabetical characters
won\[cq]t be replaced.
That means that the alt text from the image is not exactly the same than
the code used for generating the image, but it is far more readable.
.PP
For instance, the formula $\[rs]text{f\[:u]r alle} a$, would be compiled
as $\[rs]text{f\[rs]ddot{u}r alle} a$ and displayed as
\[lq]\[rs]text{f\[:u]r alle} a\[rq] in the alt attribute.
.RE
.TP
.B \f[B]\-u\f[R] \f[I]URL\f[R]
Base URL to image files (relative links are default).
.SH FILE FORMAT
.PP
A .htex file is essentially a HTML file containing LaTeX formulas.
The formulas have to be surrounded by \f[C]\f[R] and
\f[C]\f[R].
.PP
By default, formulas are rendered as inline maths, so they are squeezed
to the height of the line.
It is possible to render a formula as display maths by setting the env
attribute to displaymath,
i.e.\ \f[C]...\f[R].
.SH ENVIRONMENT VARIABLES
.PP
GladTeX can be customised by environment variables:
.TP
.B \f[C]DEBUG\f[R]
If this is set to 1, a full Python traceback, instead of a
human\-readable error message, will be displayed.
\f[C]GLADTEX_ARGS\f[R]:
When this environment variable is set, GladTeX switches into \f[B]pandoc
filter\f[R] mode: input is read from standard input, output written to
standard output and the \f[C]\-P\f[R] switch is assumed.
The contents of this variable parsed as command\-line switches.
See an example in Output As EPUB#output\-asepub).
.SH EXAMPLES
.SS Sample HTEX document
.PP
A sample HTEX document could look like this:
.IP
.nf
\f[C]
Some text
Circumference of a circle: u = \[rs]pi\[rs]cdot d
A useful matrix: \[rs]begin{pmatrix}
1 &2 &3 &4\[rs]\[rs]
5 &6 &7 &8\[rs]\[rs]
9 &10&11&12
\[rs]end{pmatrix}
\f[R]
.fi
.PP
This can be converted using
.IP
.nf
\f[C]
gladtex file.htex
\f[R]
.fi
.PP
and the result will be a HTML document called \f[C]file.html\f[R] along
with two files \f[C]eqn0000.png\f[R] and \f[C]eqn0001.png\f[R] in the
same directory.
.SS Markdown To HTML
.PP
GladTeX can be used together with Pandoc.
That can be handy to create an online version of a scientific paper
written in Markdown.
The MarkDown document would look like this:
.IP
.nf
\f[C]
Some text
=========
Circumference of a circle: $u = \[rs]pi\[rs]cdot d$
A useful matrix: $$\[rs]begin{pmatrix}
1 &2 &3 &4\[rs]\[rs]
5 &6 &7 &8\[rs]\[rs]
9 &10&11&12 \[rs]end{pmatrix}$$
\f[R]
.fi
.PP
The conversion is as easy as typing on the command\-line:
.IP
.nf
\f[C]
pandoc \-s \-t html \-\-gladtex file.md | gladtex \-o file.html \-
\f[R]
.fi
.SS Output as EPUB
.PP
It is beyond of the scope of this document to introduce Pandoc, but with
any input format, converting to EPUB with GladTeX replacing the images
is as easy as:
.IP
.nf
\f[C]
pandoc \-t json FILE.ext | gladtex \-d img \-P \- | pandoc \-f json \-o book.epub
\f[R]
.fi
.PP
Capitalised parameters should be replaced.
This can be used with Markdown as input format, see previous section.
.PP
If you want to call Pandoc as a filter without the pipes, you can use
the environment variable \f[C]GLADTEX_ARGS\f[R]:
.IP
.nf
\f[C]
GLADTEX_ARGS=\[aq]\-d img\[aq] pandoc \-o BOOK.EPUB \-F gladtex FILE.ext
\f[R]
.fi
.SH KNOWN LIMITATIONS
.PP
LaTeX2E is \f[B]\f[BI]not\f[B]\f[R] unicode aware.
if you have any unicode (more precisely, non\-ascii characters) signs in
your documents, you have the choice to do one of the following:
.IP "1." 3
Look up the symbol in one of the many LaTeX formula listings and replace
the symbol with the appropriate command.
.IP "2." 3
Use the \f[C]\-r\f[R] switch to let GladTeX replace the umlauts for you.
.PP
PLEASE NOTE: It is impossible to use GladTeX with LuaLaTeX.
At the time of writing, dvipng does not support the extended font
features of the lualatex engine.
.SH PROJECT HOME
.PP
The project home is at .
The source can be found at .
.SH AUTHORS
Sebastian Humenda.