\chapter{\protect\program{plastex} --- The Command-Line Interface}
\label{sec:command-line}

While \plasTeX\ makes it possible to parse \LaTeX\ directly from Python
code, most people will simply use the supplied command-line interface,
\program{plastex}.  \program{plastex} will invoke the parsing processes
and apply a specified renderer.  By default, \program{plastex} will
convert to HTML, although this can be changed in the \program{plastex}
configuration.

Invoking \program{plastex} is very simple.  To convert a \LaTeX\ document
to HTML using all of the defaults, simply type the following at shell prompt.

\begin{verbatim}
plastex mylatex.tex
\end{verbatim}

where \file{mylatex.tex} is the name of your \LaTeX\ file.  The
\LaTeX\ source will be parsed, all packages will be loaded and macros
expanded, and converted to HTML.  Hopefully, at this point you will have
a lovely set of HTML files that accurately reflect the \LaTeX\ source
document.  Unfortunately, converting \LaTeX\ to other formats can be
tricky, and there are many pitfalls.  If you are getting warnings or
errors while converting your document, you may want to check the FAQ
in the appendix to see if your problem is addressed.

Running \program{plastex} with the default options may not give you output
exactly the way you had envisioned.  Luckily, there are many options
that allow you to change the rendering behavior.  These options are
described in the following section.


\section{Command-Line and Configuration Options}

There are many options to \program{plastex} that allow you to control
things input and output file encodings, where files are generated and
what the filenames look like, rendering parameters, etc.  While
\program{plastex} is the interface where the options are specified, for
the most part these options are simply passed to the parser and renderers
for their use.  It is even possible to create your own options for use
in your own Python-based macros and renderers (see in particular
Section~\ref{subsec:renderer-from-script}).
The following options are currently available
on the \program{plastex} command. They are categorized for convenience.

Note that some commands such as \longprogramopt{link} and
\longprogramopt{lang-terms} take in a list of arguments. If this is the last
option supplied, you would have to separate the filename from the list of
arguments, e.g.
\begin{verbatim}
plastex --lang-terms foo bar -- input.tex
\end{verbatim}

The \program{plasTeX} command line and configuration supports interpolation.
That is, in options whose value is a string (or a list of strings), we replace
all instances of \code{\%(foo)s} with the value of the option \code{foo}. The
formatting is done with pythons \%-formatting and all \%-formatting features
are supported. Note that we only specify the name of the option, and not the
section it belongs to.

Interpolation is performed each time a configuration option is accessed.

\subsection{General Options}\label{sec:general-options}

\begin{configuration}{Configuration files}
\options{\longprogramopt{config=\optval{config-file}} or
         \programopt{-c \optval{config-file}}}
\config{general}{config}
specifies a configuration file to load.  This should be the first option
specified on the command-line. Below is a sample configuration file:
\begin{verbatim}
[general]
renderer=HTML5
copy-theme-extras=yes

[document]
lang-terms=lang.xml

[files]
split-level=1
\end{verbatim}
\end{configuration}

\begin{configuration}{Kpsewhich}
\options{\longprogramopt{kpsewhich=\optval{program}}}
\config{general}{kpsewhich}
\default{kpsewhich}
specifies the \program{kpsewhich} program to use to locate \LaTeX\
files and packages.
\end{configuration}

\begin{configuration}{Plugins}
\options{\longprogramopt{plugins=\optval{plugins}}}
\config{general}{plugins}
\default{[]}
specifies a list of plugins to be used. Each element should be package
name that python can import. See Section~\ref{sec:plugins} for more
details.
\end{configuration}

\begin{configuration}{Load \LaTeX packages}
\options{\longprogramopt{load-tex-packages} or \longprogramopt{no-load-tex-packages}}
\config{general}{load-tex-packages}
\default{True}
specifies whether to attempt loading \LaTeX implementations of packages
when no python implementation exists.
\end{configuration}

\begin{configuration}{\LaTeX packages white-list}
\options{\longprogramopt{tex-packages=\optval{packages}}}
\config{general}{tex-packages}
\default{[]}
specifies a list of packages whose \LaTeX implementation should be loaded
if there is no python implementations, even if \longprogramopt{no-load-tex-packages}
is set.
\end{configuration}

\begin{configuration}{Renderer}
\options{\longprogramopt{renderer=\optval{renderer-name}}}
\config{general}{renderer}
\default{HTML5}
specifies which renderer to use. This is either one of the built in renderers,
a renderer defined by a plugin, or a path to the directory of a renderer.
A plugin can provide a renderer \verb+my_renderer+ by having a
\module{Renderers} submodule containing a \module{my_renderer} submodule exporting
a \class{Renderer} class.
\end{configuration}

\begin{configuration}{Packages directories}
\options{\longprogramopt{packages-dir=\optval{directories}}}
\config{general}{packages-dirs}
\default{[]}
specifies a list of directories where python implementations
of packages should be searched.
\end{configuration}

\begin{configuration}{Themes}
\options{\longprogramopt{theme=\optval{theme-name}}}
\config{general}{theme}
\default{default}
specifies which theme to use.
\end{configuration}

\begin{configuration}{Extra theme files}
\options{\longprogramopt{copy-theme-extras} or
         \longprogramopt{ignore-theme-extras}}
\config{general}{copy-theme-extras}
\default{yes}
indicates whether or not extra files that belong to a theme (if there are
any) should be copied to the output directory.
\end{configuration}

\begin{configuration}{Extra templates directories}
\options{\longprogramopt{extra-templates=\optval{directories}}}
\config{general}{extra-templates}
\default{[]}
specifies a list of directories where extra templates
should be searched. Paths are relative to the current directory.
\end{configuration}

\begin{configuration}{Dump XML output}
\options{\longprogramopt{xml}}
\config{general}{xml}
\default{False}
dumps a XML representation of the document (for debugging).
\end{configuration}

\begin{configuration}{Debug parsing}
\options{\longprogramopt{debug}}
\config{general}{debug}
\default{False}
parses the document and drops into a debugger.
\end{configuration}

\subsection{Document Properties\label{sec:config-document}}

\begin{configuration}{Base URL}
\options{\longprogramopt{base-url=\optval{url}}}
\config{document}{base-url}
specifies a base URL to prepend to the path of all links.
\end{configuration}

\begin{configuration}{Number of Columns in the Index}
\options{\longprogramopt{index-columns=\optval{integer}}}
\config{document}{index-columns}
specifies the number of columns to group the index into.
\end{configuration}

\begin{configuration}{Language terms}
\options{\longprogramopt{lang-terms \optval{string1 string2 \ldots}}}
\config{document}{lang-terms}
specifies a list of files that contain language terms
\end{configuration}

\begin{configuration}{Section number depth}
\options{\longprogramopt{sec-num-depth=\optval{integer}}}
\config{document}{sec-num-depth}
\default{6}
specifies the section level depth that should appear in section numbers.
This value overrides the value of the secnumdepth counter in the document.
\end{configuration}

\begin{configuration}{Title for the document}
\options{\longprogramopt{title=\optval{string}}}
\config{document}{title}
specifies a title to use for the document instead of the title given
in the \LaTeX\ source document
\end{configuration}

\begin{configuration}{Table of contents depth}
\options{\longprogramopt{toc-depth=\optval{integer}}}
\config{document}{toc-depth}
specifies the number of levels to include in each table of contents.
\end{configuration}

\begin{configuration}{Display sections in the table of contents that do not create files}
\options{\longprogramopt{toc-non-files}}
\config{document}{toc-non-files}
specifies that sections that do not create files should still appear in the
table of contents.  By default, only sections that create files will show
up in the table of contents.
\end{configuration}

\begin{configuration}{Disable character substitutions}
\options{\longprogramopt{disable-charsub}}
\config{document}{disable-charsub}
specifies a list of characters not to perform character substitutions on.
Character substitutions replace certain characters or groups of characters with
typographically superior unicode versions, e.g.\ \code{`} with `. This may be
unsuitable for certain use cases. For example, it may make search harder.
\end{configuration}


\subsection{Counters}

It is possible to set the initial value of a counter from the
command-line using the \longprogramopt{counter} option or the
``counters'' section in a configuration file.  The configuration
file format for setting counters is very simple.  The option name
in the configuration file corresponds to the counter name, and the
value is the value to set the counter to.
\begin{verbatim}
[counters]
chapter=4
part=2
\end{verbatim}

The sample configuration above sets the chapter counter to 4, and the
part counter to 2.

The \longprogramopt{counter} can also set counters.  It accepts multiple
arguments which must be surrounded by square brackets ([~]).
Each counter set in the \longprogramopt{counter}
option requires two values: the name of the counter and the value to
set the counter to.  An example of \longprogramopt{counter} is shown below.
\begin{verbatim}
plastex --counter part 2 --counter chapter 4 file.tex
\end{verbatim}

Just as in the configuration example, this command-line sets the
part counter to 2, and the chapter counter to 4.

Note that our notion of ``setting'' a counter to `n` is equivalent to
the \LaTeX{} command \verb!\setcounter{counter}{n - 1}!. This is so that, for
example, in the above configuration, when we first encounter
\verb!\section{Foo}!, we get Section 2 instead of Section 3 (since
\verb!\section! first increments the counter then uses the counter value).

\begin{configuration}{Set initial counter values}
\options{\longprogramopt{counter=\optval{counter-name initial-value}}}
specifies the initial counter values.
\end{configuration}


\subsection{Document Links\label{sec:config-links}}

The links section of the configuration is a little different than the
others.  The options in the links section are not preconfigured, they
are all user-specified.  The links section includes information
to be included in the navigation object available on all sections in
a document.  By default, the section's navigation object includes things
like the previous and next objects in the document, the child nodes,
the sibling nodes, etc.  The table below lists all of the navigation
objects that are already defined.  The names for these items came from
the link types defined at \url{http://fantasai.tripod.com/qref/Appendix/LinkTypes/ltdef.html}.  Of course, it is up to the renderer to actually make use
of them.

\begin{tableii}{l|l}{var}{Name}{Description}
\lineii{home}{the first section in the document}
\lineii{start}{same as \var{home}}
\lineii{begin}{same as \var{home}}
\lineii{first}{same as \var{home}}
\lineii{end}{the last section in the document}
\lineii{last}{same as \var{end}}
\lineii{next}{the next section in the document}
\lineii{prev}{the previous section in the document}
\lineii{previous}{same as \var{prev}}
\lineii{up}{the parent section}
\lineii{top}{the top section in the document}
\lineii{origin}{same as \var{top}}
\lineii{parent}{the parent section}
\lineii{child}{a list of the subsections}
\lineii{siblings}{a list of the sibling sections}
\lineii{document}{the document object}
\lineii{part}{the current part object}
\lineii{chapter}{the current chapter object}
\lineii{section}{the current section object}
\lineii{subsection}{the current subsection object}
\lineii{navigator}{the top node in the document object}
\lineii{toc}{the node containing the table of contents}
\lineii{contents}{same as \var{toc}}
\lineii{breadcrumbs}{a list of the parent objects of the current node}
\end{tableii}

Since each of these items references an object that is expected to have
a URL and a title, any user-defined fields should contain these as well
(although the URL is optional in some items).  To create a user-defined
field in this object, you need to use two options: one for the title
and one for the URL, if one exists.  They are specified in the config
file as follows:
\begin{verbatim}
[links]
next-url=http://myhost.com/glossary
next-title=The Next Document
mylink-title=Another Title
\end{verbatim}

While you can not override a field that is populated by the document,
there are times when a field isn't populated.  This occurs, for example,
in the \var{prev} field at the beginning of the document, or the
\var{next} field at the end of the document.  If you specify a \var{prev}
or \var{next} field in your configuration, those fields will be used
when no \var{prev} or \var{next} is available.  This allows you to link
to external documents at those points.

\begin{configuration}{Set document links}
\options{\longprogramopt{link=\optval{key optional-url title}}}
specifies links to be included in the navigation object.
\end{configuration}


\subsection{Input and Output Files\label{sec:config-files}}

If you have a renderer that only generates one file, specifying the output
filename is simple: use the \longprogramopt{filename} option to specify
the name.  However, if the renderer you are using generates multiple
files, things get more complicated.  The \longprogramopt{filename} option
is also capable of handling multiple names, as well as giving you a
templating way to build filenames.

Below is a list of all of the options that affect filename generation.

\begin{configuration}{Characters that shouldn't be used in a filename}
\options{\longprogramopt{bad-filename-chars=\optval{string}}}
\config{files}{bad-chars}
\default{:~\#\$\%\textasciicircum\&*!\textasciitilde`"'=?/{}[]()|<>;\textbackslash,.}
specifies all characters that should not be allowed in a filename.
These characters will be replaced by the value in
\longprogramopt{bad-filename-chars-sub}.
\end{configuration}

\begin{configuration}{String to use in place of invalid characters}
\options{\longprogramopt{bad-filename-chars-sub}=\optval{string}}
\config{files}{bad-chars-sub}
\default{-}
specifies a string to use in place of invalid filename characters (
specified by the \longprogramopt{bad-chars-sub} option)
\end{configuration}

\begin{configuration}{Output Directory}
\options{\longprogramopt{dir=\optval{directory}}  or \programopt{-d \optval{directory}}}
\config{files}{directory}
\default{\$jobname}
specifies a directory name to use as the output directory.
\end{configuration}

\begin{configuration}{Escaping characters higher than 7-bit}
\options{\longprogramopt{escape-high-chars}}
\config{files}{escape-high-chars}
\default{False}
some output types allow you to represent characters that are greater than
7-bits with an alternate representation to alleviate the issue of
file encoding.  This option indicates that these alternate representations
should be used.

\note{The renderer is responsible for doing the translation into the
alternate format.  This might not be supported by all output types.}
\end{configuration}

\begin{configuration}{Template to use for output filenames}
\options{\longprogramopt{filename=\optval{string}}}
\config{files}{filename}
specifies the templates to use for generating filenames.
The filename template is a list of space separated names.  Each name
in the list is returned once.  An example is shown below.

\begin{verbatim}
index.html toc.html file1.html file2.html
\end{verbatim}

If you don't know how many files you are going to be reproducing,
using static filenames like in the example above is not practical.
For this reason, these filenames can also contain variables as described in
Python's string Templates (e.g. \var{\$title}, \var{\${id}}).
Note that, if this option is configured on command line
rather than in a configuration file, the dollar characters probably need
to be protected. For instance bash would require single quote
protection, as in \verb+plastex --filename='$id'+.
These variables come from the namespace created in the renderer and
include:
\begin{itemize}
\item
\var{\$name}, the name of the item (e.g. part, chapter or section),
\item
\var{\$id}, the ID (i.e. label) of the item,
\item
\var{\$ref}, the counter associated to the item (if it exists),
\item
\var{\$title}, the title of the item,
\item
\var{\$jobname}, the basename of the \LaTeX\ file being processed.
\end{itemize}
One special variable is \var{\$num}.  This value in generated dynamically
whenever a filename with \var{\$num} is requested.  Each time a filename
with \var{\$num} is successfully generated, the value of \var{\$num}
is incremented.

The values of variables can also be modified by a format specified
in parentheses after the variable.  The format is simply an integer
that specifies how wide of a field to create for integers
(zero-padded), or, for strings, how many space separated words
to limit the name to.  The example below shows \var{\$num} being padded
to four places and \var{\$title} being limited to five words.

\begin{verbatim}
sect$num(4) $title(5)
\end{verbatim}

The list can also contain a wildcard filename (which should be
specified last).  Once a wildcard name is reached, it is
used from that point on to generate the remaining filenames.
The wildcard filename contains a list of alternatives to use as
part of the filename indicated by a comma separated list of
alternatives surrounded by a set of square brackets ([ ]).
Each of the alternatives specified is tried until a filename is
successfully created (i.e. all variables resolve).  For example,
the specification below creates three alternatives.

\begin{verbatim}
$jobname_[$id, $title, sect$num(4)]
\end{verbatim}

The code above is expanded to the following possibilities.

\begin{verbatim}
$jobname_$id
$jobname_$title
$jobname_sect$num(4)
\end{verbatim}

Each of the alternatives is attempted until one of them succeeds.
In order for an alternative to succeed, all of the variables referenced
in the template must be populated.  For example, the \var{\$id} variable
will not be populated unless the node had a \macro{\$label} macro
pointing to it.  The \var{\$title} variable would not be populated unless
the node had a title associated with it (e.g. such as section, subsection, etc.).
Generally, the last one should contain no variables except for
\var{\$num} as a fail-safe alternative.

The default value for this option is \verb+index [$id, sect$num(4)]+
which, assuming HTML output, will first generate a file
\var{index.html}. Then, for each node triggering a file creation, it
will try to use the node label. If no label exists, it will use
\var{sectN.html} where \var{N} is the next available number (starting
from one), padded to four digits. Of course the prefix \var{sect} is
chosen because the default value for \var{split-level} is $2$, which
means generating a new file or each section.

As last example, one could use \var{index \$name-[\$ref, sect\$num(4)]}.
Assuming our document contains two chapters which each contain two
sections (and using the \LaTeX default numbering scheme and default
\plasTeX split level), we would get filenames
\var{index.html}, \var{chapter-1.html}, \var{section-1-1.html},
\var{section-1-2.html}, \var{chapter-2.html}, \var{section-2-1.html},
\var{section-2-2.html}.

\end{configuration}

\begin{configuration}{Input Encoding}
\options{\longprogramopt{input-encoding=\optval{string}}}
\config{files}{input-encoding}
\default{utf-8}
specifies which encoding the \LaTeX\ source file is in
\end{configuration}

\begin{configuration}{Output Encoding}
\options{\longprogramopt{output-encoding=\optval{string}}}
\config{files}{output-encoding}
\default{utf-8}
specifies which encoding the output files should use.
\note{This depends on the output format as well.  While HTML and XML use
encodings, a binary format like MS Word, would not.}
\end{configuration}

\begin{configuration}{Splitting document into multiple files}
\options{\longprogramopt{split-level=\optval{integer}}}
\config{files}{split-level}
\default{2}
specifies the highest section level that generates a new file.  Each section
in a \LaTeX\ document has a number associated with its hierarchical level.
These levels are -2 for the document, -1 for parts, 0 for chapters,
1 for sections, 2 for subsections, 3 for subsubsections, 4 for paragraphs,
and 5 for subparagraphs.  A new file will be generated for every section
in the hierarchy with a value less than or equal to the value of this
option.  This means that for the value of 2, files will be generated for
the document, parts, chapters, sections, and subsections.
\end{configuration}

\begin{configuration}{Log messages to file}
\options{\longprogramopt{log}}
\config{files}{log}
\default{False}
specifies whether log messages should be put into a file instead of printed.
\end{configuration}


\subsection{Image Options\label{sec:config-images}}

Images are created by renderers when the output type in incapable of
rendering the content in any other way. This method was commonly used
to display equations in XHTML output. Nowadays, MathJax arguably
provides a better method, see Section~\ref{sec:config-html5} below.
But there are still pieces of mathematics they are not handled by MathJax, such
as commutative diagrams written using the \verb+tikz-cd+ package.
The following options control how images are generated.

\begin{configuration}{Base URL}
\options{\longprogramopt{image-base-url=\optval{url}}}
\config{images}{base-url}
specifies a base URL to prepend to the path of all images.
\end{configuration}

\begin{configuration}{\LaTeX\ program to use to compile image document}
\options{\longprogramopt{image-compiler=\optval{program}}}
\config{images}{compiler}
\default{latex}
specifies which program to use to compile the images \LaTeX\ document. If
unspecified, the default is specified by the imager. Note that not all imagers
are compatible with all compilers. Specifically, some imagers need compilers
that produces pdf's and others need dvi's.
\end{configuration}

\begin{configuration}{\LaTeX\ program to use to compile vector image document}
\options{\longprogramopt{vector-image-compiler=\optval{program}}}
\config{images}{vector-compiler}
\default{latex}
specifies which program to use to compile the vector images \LaTeX\ document. If
unspecified, this uses the value of \longprogramopt{image-compiler}.
\end{configuration}

\begin{configuration}{Enable or disable image generation}
\options{\longprogramopt{enable-images} or
         \longprogramopt{disable-images}}
\config{images}{enabled}
\default{yes}
indicates whether or not images should be generated.
\end{configuration}

\begin{configuration}{Enable or disable the image cache}
\options{\longprogramopt{enable-image-cache} or
         \longprogramopt{disable-image-cache}}
\config{images}{cache}
\default{yes}
indicates whether or not images should use a cache between runs.
\end{configuration}

\begin{configuration}{Convert \LaTeX\ output to images}
\options{\longprogramopt{imager=\optval{program}}}
\config{images}{imager}
\default{gspdfpng pdftoppm dvipng dvi2bitmap gsdvipng OSXCoreGraphics}
specifies which converter will be used to take the output from the
\LaTeX\ compiler and convert it to images.  You can specify a space
delimited list of names as well.  If a list of names is specified,
each one is verified in order to see if it works on the current machine.
The first one that succeeds is used.

You can use the value of ``none'' to turn the imager off.
\end{configuration}

\begin{configuration}{Image filenames}
\options{\longprogramopt{image-filenames=\optval{filename-template}}}
\config{images}{filenames}
\default{images/img-\$num(4).png}
specifies the image naming template to use to generate filenames.  This
template is the same as the templates used by the \longprogramopt{filename}
option.
\end{configuration}

\begin{configuration}{Convert \LaTeX\ output to vector images}
\options{\longprogramopt{vector-imager=\optval{program}}}
\config{images}{vector-imager}
\default{pdf2svg dvisvgm}
specifies which converter will be used to take the output from the
\LaTeX\ compiler and convert it to vector images.  You can specify a space
delimited list of names as well.  If a list of names is specified,
each one is verified in order to see if it works on the current machine.
The first one that succeeds is used.

You can use the value of ``none'' to turn the vector imager off.

\note{When using the vector imager, a bitmap image is also created
using the regular imager.  This bitmap is used to determine the
depth information about the vector image and can also be used as
a backup if the vector image is not supported by the viewer.}
\end{configuration}

\begin{configuration}{Save temporary files for debugging}
\options{\longprogramopt{save-image-file} or \longprogramopt{delete-image-file}}
\config{images}{save-file}
\default{no}
specifies whether the temporary images.tex file should be retained after
compilation. It can be useful to retain the images for debugging purposes.
\end{configuration}

\begin{configuration}{Scale factor of image}
\options{\longprogramopt{image-scale-factor}}
\config{images}{scale-factor}
\default{1.0}
the default scale factor to apply to images after compilation. Not all imagers respect
this option.
\end{configuration}

\begin{configuration}{Scale factor for given node type}
\options{\longprogramopt{scales=\optval{node-name scale_factor}}}
specifies the image scale factor for the specified type of node.
Not all imagers respect this option.
\end{configuration}

\subsection{HTML5 Renderer Options\label{sec:config-html5}}

Each renderer can define its own configuration options. This section
describes options from the HTML5 renderer. These options have no effect
if another renderer is used. Also these options may have no effect if
the default theme is not used.

The first three options give control on navigation helpers (tables of
contents and breadcrumbs links). Together with the extra-css option,
which allows to set css rules overriding the default ones, they allow
radical changes to the output style without modifying any template or
python code. See Section~\ref{sec:html5} for more information on the
HTML5 renderer and how to customize its output.

\begin{configuration}{Display table of contents on each page}
\options{\longprogramopt{display-toc} or \longprogramopt{no-display-toc}}
\config{html5}{display-toc}
\default{true}
specifies whether to display the table of contents on each page.
\end{configuration}


\begin{configuration}{Local table of contents level}
\options{\longprogramopt{localtoc-level=\optval{level}}}
\config{html5}{localtoc-level}
\default{Node.DOCUMENT_LEVEL-1}
specifies from which level one creates local table of contents. The
default value implies local table of contents are never created.
\end{configuration}


\begin{configuration}{Create breadcrumbs from this level}
\options{\longprogramopt{breadcrumbs-level=\optval{level}}}
\config{html5}{breadcrumbs-level}
\default{10}
specifies from which level one creates breadcrumbs navigation links.
The default value means no breadcrumb at all.
\end{configuration}

\begin{configuration}{Use theme CSS}
\options{\longprogramopt{use-theme-css} or \longprogramopt{no-theme-css}}
\config{html5}{use-theme-css}
\default{True}
specifies whether to use CSS files from the theme.
\end{configuration}

\begin{configuration}{Theme CSS file}
\options{\longprogramopt{theme-css=\optval{theme}}}
\config{html5}{theme-css}
\default{white}
specifies when CSS theme to use. Possible values are currently white, blue or
green.
\end{configuration}

\begin{configuration}{Extra CSS file}
  \options{\longprogramopt{extra-css \optval{filename1 filename2 ...}}}
\config{html5}{extra-css}
\default{[]}
specifies a list of css files to use in addition the
theme css. These files are copied to the output directory by the
renderer and loaded by the main layout template in the list order after
the theme css files (if any) and the packages css files (if any).
\end{configuration}

\begin{configuration}{Use theme javascript}
\options{\longprogramopt{use-theme-js} or \longprogramopt{no-theme-js}}
\config{html5}{use-theme-js}
\default{True}
specifies whether to use javascript files from the theme. The default
theme javascript is used to hide or show part of the table of contents
and proofs.
\end{configuration}

\begin{configuration}{Extra javascript}
  \options{\longprogramopt{extra-js \optval{filename1 filename2 ...}}}
\config{html5}{extra-css}
\default{[]}
specifies a list of javascript files to use (in addition
to those coming from the theme is the use-theme-js option is set to true).
These files are copied to the output directory by the
renderer and loaded by the main layout template in the list order after
the theme javascript files (if any) and the packages javascript files (if any).
\end{configuration}

\begin{configuration}{Use MathJax}
\options{\longprogramopt{use-mathjax} or \longprogramopt{no-mathjax}}
\config{html5}{use-mathjax}
\default{True}
specifies whether to use MathJax for mathematics rendering. Setting this
to False only makes sense if the document contains no mathematics or if
some filter is expected to handle mathematics (see
\longprogramopt{filters} option below).
\end{configuration}

\begin{configuration}{MathJax library url}
\options{\longprogramopt{mathjax-url=\optval{url}}}
\config{html5}{mathjax-url}
\default{http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_CHTML}
specifies where to find the MathJax javascript lib (including the config
information as in the default value).
\end{configuration}

\begin{configuration}{Use single dollars as math delimiter for MathJax}
	\options{\longprogramopt{dollars} or \longprogramopt{no-dollars}}
\config{html5}{mathjax-dollars}
\default{False}
specifies whether single dollars can be used as math delimiters instead of
\verb+\(+ and \verb+\)+. This information is used by MathJax.
\end{configuration}

\begin{configuration}{MathJax macros}
  \options{\longprogramopt{mj-macros \optval{name value}}}
\config{mathjax-macros}{macros}
\default{\{\}}
specifies a dictionary of macros for MathJax.
This can be used for common macros that are not implemented by MathJax, for instance
\macro{qedhere}. On the command line, the option can be provided several times
to define several macros. But this option is much more convenient to specify in a config file in
a \verb!mathjax-macros! section containing one line \verb!name=value! per macro.
\end{configuration}

\begin{configuration}{Filters applied on output}
  \options{\longprogramopt{filters \optval{filter1 filter2 \ldots}}}
\config{html5}{filters}
\default{[]}
specifies a list of commands to invoke on each output
page. Each command should expect one file to convert on stdin and output
the converted file on stdout.
\end{configuration}