3 LaTeX usage and conventions

All documentation is written in LaTeX, and conversion to HTML is done using LaTeXML (Section 7.1). Currently, version 0.8.0 or higher of LaTeXML is required; see Section 7.

LaTeXML supports many, but not all, of the commonly used LaTeX packages. Therefore, in some circumstance, it may be useful to conditionalize the LaTeX source to use different input depending on whether HTML or PDF output is being produced. Producing HTML implies the use of LaTeXML, which can be detected using the \iflatexml conditional, as in:

Some specific problems with LaTeXML at the time of this writing include:

• •

  For item entries within a description list ( \begin{description} ... \end{description}), it may sometimes be necessary to add a \mbox{} macro after the item label, as in

    \item[labelForItem]\mbox{}
  

  in order to ensure that the text following the label starts on a new line.

• •

  LaTeXML does not place the title page date (specified using \date{}) on the titlepage. Instead, it is placed in the footer at the page bottom. As a work-around, we use \iflatex to leave \date empty and then place an explicit date at the top of the page.

• •

  In some earlier versions of LaTeXML, blank lines were not properly handled in the lstlisting environment. This was fixed by post-processing the HTML output, as described in Section 8.2.

• •

  In some cases, the first line in a lstlisting environment may not appear, unless a [] is appended to the opening
  \begin{lstlisting}, as in

    \begin{lstlisting}[]
    ... verbatim listing ...
    \end{lstlisting}
  

• •

  Some characters and character sequences (such as quotes, and the sequence ...) are converted into special unicode characters. This actually reduces the readability of code blocks, and so post-processing is used to replace the unicode characters with the originals (Section 8.2).

Programmatic literals, such as class and method names, file names, command sequences, and environment variables are typeset in monospace, using {\tt monospace}. User interface literals, such as menu items, are typeset in sans-serif, using {\sf sans-serif}.

Small code blocks (typically one-line) are usually typeset using the verbatim environment, which produces output like this:

  > short one line code or command line example

Longer code examples are typeset using the lstlisting environment (from the listings package), which surrounds the output in a colored box:

A special environment called sideblock is used to create admonition sections that contain special notes, warnings, or side information. The LaTeX source

will produce output that looks like this:

Note: when producing PDF, the sideblock environment is implemented using commands from the color and framed packages. When producing HTML output, side blocks are implemented internally using the regular quote environment, with the final appearance arranged using the CSS stylesheet.

Image files are input using \includegraphics from the graphics package, using code fragments of the form

When specifying the image file (e.g., images/viewerToolbar in the above example), the file extension is typically omitted, allowing the processing application (LaTeXML for HTML and latex for PDF) to determine the appropriate file type. LaTeXML generally requires .png, .jpg, .pdf or .eps (encapsulated PostScript) files, whereas latex, because we are using it to first create PostScript, is constrained to encapsulated PostScript (.eps). The Makefiles provide default rules for creating .eps files; see Section 5 for details.

Our convention is to store image files in a subdirectory images of the documentation source directory. When building HTML output, these are copied automatically into the appropriate HTML target directory.

In some cases, good image appearance may require different image scalings, depending on whether HTML or PDF output is being produced. This is often true in particular for .png files, where for HTML one may not want any scaling at all (in order to get pixel-for-pixel reproduction). This can be achieved using \iflatexml:

ArtiSynth is implemented in Java, and so much of the documentation refers to various Java classes and methods. It is therefore useful to include hyperlinks from the documentation to the actual Javadoc pages. Unfortunately, creating such a hyperlink can be rather tedious: If the Javadocs are rooted at http://www.artisynth.org/doc/javadocs, then a hyperlink to the class definition for maspack.matrix.MatrixNd must take the lengthy form

  \href{http://www.artisynth.org/doc/javadocs/maspack/matrix/MatrixNd.html}{MatrixNd}

Method references are even worse, particularly if they contain arguments:

  \href{http:// ... MatrixNd.html#mul(maspack.matrix.MatrixNd)}{MatrixNd.mul()}

To alleviate these problems, several LaTeX commands are provided that build Javadoc references automatically from simple class and method descriptions.

Within a given document, one may sometimes wish to provide a link to another ArtiSynth document, such as the Maspack Reference Manual. This can be done using the macro \artisynthManual, for which the above reference to the Maspack manual was encoded as follows:

More generally, the macro takes the form

where docname is the root name of the document (e.g., maspack for maspack.tex), docpath is an optional argument giving the name of the directory containing the document, relative to <ARTISYNTH_HOME>/doc, and text is the text associated with the hyperlink. If omitted, docpath is assumed to be the same as docname.

Internally, \artisynthManual works by creating a placeholder link containing the symbol @ARTISYNTHDOCBASE. This propagates to the output HTML or PostScript file, which is then processed by setJavadocLinks as described in Section 8.1.