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

\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}{Renderer}
\options{\longprogramopt{renderer=\optval{renderer-name}}}
\config{general}{renderer}
\default{XHTML}
specifies which renderer to use.
\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}


\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{string}}}
\config{document}{lang-terms}
Specifies a list of files that contain language terms, delimited by the
OS path separator (such as : for POSIX and ; for Windows).
\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}


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

\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}

These option names are split on the dash (-) to create a key, before the dash,
and a member, after the dash.  A dictionary is inserted into the navigation
object with the name of the key, and the members are added to that dictionary.
The configuration above would create the following Python dictionary.
\begin{verbatim}
{
    'next':
        {
            'url':'http://myhost.com/glossary',
            '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{links=\optval{[ key optional-url title ]}}}
specifies links to be included in the navigation object.  Since at
least two values are needed in the links (key and title, with an optional
URL), the values are grouped in square brackets on the command-line ([~]).
\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}


\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.
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.
\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{dvipng dvi2bitmap gsdvipng gspdfpng 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{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}

\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.
\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{green}
specifies when CSS theme to use. Possible values are currently blue or
green.
\end{configuration}

\begin{configuration}{Extra CSS file}
\options{\longprogramopt{extra-css=\optval{filename1, ...}}}
\config{html5}{extra-css}
\default{''}
specifies a comma separated 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, ...}}}
\config{html5}{extra-css}
\default{''}
specifies a comma separated 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 are used as math delimiters instead of
\verb+\(+ and \verb+\)+. This information is used by MathJax.
\end{configuration}


\begin{configuration}{Filters applied on output}
\options{\longprogramopt{filters=\optval{filter1, \ldots}}}
\config{html5}{filters}
\default{''}
specifies a comma separated 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}

\begin{configuration}{TikZ compiler}
\options{\longprogramopt{tikz-compiler=\optval{compiler}}}
\config{html5}{tikz-compiler}
\default{'pdflatex'}
specifies which program to use for compiling tikz pictures before
conversion to svg and inclusion in the html file. See
Section~\ref{sec:tikz}.
\end{configuration}

\begin{configuration}{TikZ converter}
\options{\longprogramopt{tikz-converter=\optval{converter}}}
\config{html5}{tikz-converter}
\default{'pdf2svg'}
specifies which program to use for converting tikz pictures pdf files
to svg before inclusion in the html file. See
Section~\ref{sec:tikz}.
\end{configuration}

\begin{configuration}{TikZ template}
\options{\longprogramopt{tikz-template=\optval{template_file}}}
\config{html5}{tikz-template}
\default{''}
specifies a file containing a tex template for tikz pictures
compilation. See Section~\ref{sec:tikz}.
\end{configuration}

\begin{configuration}{TikZ-CD template}
\options{\longprogramopt{tikz-cd-template=\optval{template_file}}}
\config{html5}{tikz-cd-template}
\default{''}
specifies a file containing a tex template for tikz-cd diagrams
compilation. See Section~\ref{sec:tikz}.
\end{configuration}
