summaryrefslogtreecommitdiff
path: root/support/gladtex/manpage.md
blob: f4127db1f76af3cdfe0bfad180158bfad519a257 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
% GLADTEX(1)
% Sebastian Humenda
% 8th of September 2018

# NAME

**GladTeX** - generate HTML with LaTeX formulas embedded as images

# SYNOPSIS

**gladtex** [OPTIONS] <INPUT  FILE NAME>


# DESCRIPTION

**GladTeX** is a formula preprocessor for HTML files. It recognizes a special tag
(`<eq>...</eq>`) 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.\
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.

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.

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 `-P`.

See [FILE FORMAT](#file-format) for an explanation of the file format and
[EXAMPLES](#examples) for examples on how to use GladTeX on its own or with
Pandoc.

# OPTIONS

**INPUT FILE NAME**
:   Input .htex file with LaTeX formulas (if omitted or -, stdin will be read).

**-h** **--help**
:   Show this help message and exit.

**-a**
:   Save text alternatives for images which are too long for the alt attribute
    into a single separate file and link images to it.

**-b** _BACKGROUND_COLOR_
:   Set background color for resulting images (default transparent). GladTeX
    understands colors as provided by the `dvips` option  of the xcolor LaTeX
    package. Alternatively, a 6-digit hexadecimal value can be provided (as used
    e.g. in HTML/CSS).

**-c** _`FOREGROUND_COLOR`_
:   Set foreground color for resulting images. See the option above for a more
in-depth explanation.

**-d** _DIRECTORY_
:   Directory in which to store the generated images in (relative path).\
    The given path is interpreted relatively to the input file. For instance,:

        gladtex -d img dir/file.htex

    will create a `dir/img` directory and link accordingly in `x/file.htex`.

**-e** _`LATEX_MATHS_ENV`_
:   Set custom maths environment to surround the formula (e.g. flalign).

**-E** _ENCODING_
:   Overwrite encoding to use (default UTF-8).

**-f** _FONTSIZE_
:   Overwrite the default font size of 12pt. 12pt is the default in most
    browsers and hence changing this might lead to less-portable documents.

**-i** _CLASS_
:   CSS class to assign to inline math (default: 'inlinemath').

**-K**
:   keep LaTeX file(s) when converting formulas

    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't successful, it is sometimes helpful to look
    at the complete document. This option will keep the file.

**-l** _CLASS_
:   CSS class to assign to block-level math (default: 'displaymath').

**-n**
:   Purge unreadable caches along with all eqn*.png files.

    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.

**-m**
:     Print error output in machine-readable format (less concise, better parseable).

    Each line will start with a key, followed by a colon, followed by the value,
    i.e. `line: 5`.

**-o** _FILENAME_
:   Set output file name. '-' will print text to stdout. Bydefault, input file
    name is used and the `.htex` extension is replaced by `.html`.

**-p** _`LATEX_STATEMENT`_
:   Add given LaTeX code to preamble of document. That'll affect the conversion
    of every image.

**-P**
:   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 `-` as the input file for
    this option.

**--png**
:   Switch from SVG to PNG as image output. This image has several known issues,
    one of them being that images won't resize when zooming into the document.
    It is also harder to work with for visually impaired users.

**-r** _DPI_
:   Set resolution (size of images) to 'dpi' (115 by default). This is only
    available with the `--png` option. Also see the `-f` option.

**-R**
:   Replace non-ascii (unicode) characters by LaTeX commands.

    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'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.

    For instance, the formula \$\\text{für alle} a\$, would be compiled as
    \$\\text{f\\ddot{u}r alle} a\$ and displayed as "\\text{für alle} a" in the alt
    attribute.


**-u** _URL_
:   Base URL to image files (relative links are default).

# FILE FORMAT

A .htex file is essentially a HTML file containing LaTeX formulas. The formulas
have to be surrounded by `<eq>` and `</eq>`.

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. `<eq env="displaymath">...</eq>`.

# ENVIRONMENT VARIABLES

GladTeX can be customised by environment variables:

`DEBUG`
:   If this is set to 1, a full Python traceback, instead of a human-readable
    error message, will be displayed.
`GLADTEX_ARGS`:
:   When this environment variable is set, GladTeX switches into
    **pandoc filter** mode: input is read from standard input, output written to
    standard output and the `-P` switch is assumed. The contents of this
    variable parsed as command-line switches.
    See an example in [Output As EPUB]#output-asepub).

# EXAMPLES

## Sample HTEX document

A sample HTEX document could look like this:

~~~~
<html><head><!-- meta information like charset --></head>
<body>
<h1>Some text</h1>
<p>Circumference of a circle: <eq>u = \pi\cdot d</eq><p>
<p>A useful matrix: <eq env="displaymath">\begin{pmatrix}
1 &2 &3 &4\\
5 &6 &7 &8\\
9 &10&11&12
\end{pmatrix}</eq></p>
</body></html>
~~~~

This can be converted using 

    gladtex file.htex

and the result will be a HTML document called `file.html` along with two files
`eqn0000.png` and `eqn0001.png` in the same directory.

## Markdown To HTML

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:

~~~~
Some text
=========

Circumference of a circle: $u = \pi\cdot d$

A useful matrix: $$\begin{pmatrix}
1 &2 &3 &4\\
5 &6 &7 &8\\
9 &10&11&12 \end{pmatrix}$$
~~~~

The conversion is as easy as typing on the command-line:

    pandoc -s -t html --gladtex file.md | gladtex -o file.html

## Output as EPUB

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:

    pandoc -t json FILE.ext | gladtex -d img -P - | pandoc -f json -o book.epub

Capitalised parameters should be replaced. This can be used with Markdown as
input format, see previous section.

If you want to call Pandoc as a filter without the pipes, you can use the
environment variable `GLADTEX_ARGS`:

    GLADTEX_ARGS='-d img' pandoc -o BOOK.EPUB -F gladtex FILE.ext


# KNOWN LIMITATIONS

LaTeX2E is ***not*** 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:

1.  Look up the symbol in one of the many LaTeX formula listings and replace the
    symbol with the appropriate command.
2.  Use the `-r` switch to let GladTeX replace the umlauts for you.

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.


# PROJECT HOME

The project home is at <http://humenda.github.io/GladTeX>. The source can be
found at <https://github.com/humenda/gladtex>.