Writing Documentation for ArtiSynth

3 LaTeX usage and conventions

3.1 LaTeXML restrictions

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:

  do things in a conventional way that LaTeXML can deal with
  \fancydancy{use some LaTeX package that LaTeXML cant handle}

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


    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

      ... verbatim listing ...
  • 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).

3.2 Font conventions

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

3.3 Code blocks

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:

// Here is a longer code example
interface Property
   Object get();
   void set (Object value);
   Range getRange ();
   HasProperties getHost();
   PropertyInfo getInfo();

3.4 Side blocks

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

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

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.

3.5 Inserting Images

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

\caption{The viewer toolbar.}%

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:

\caption{The viewer toolbar.}%

3.6 Javadoc References

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


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.

3.6.1 Class references

The command \javaclass will create a Javadoc reference to a class from the class name itself. The LaTeX source

\javaclass{maspack.matrix.MatrixNd}, and \javaclass[maspack]{matrix.MatrixNd}, and

will produce the output

The name in the optional argument (between square brackets []) is prepended to the main argument to create a fully qualified class name, with only the main argument being used as the anchor text.

The names provided by the optional argument and the main argument are concatenated (with an intervening ’.’ character) to create a fully qualified class name that is used to produce the appropriate hyperlink to the Javadoc.

When referencing an inner class or enumerated type, one should separate the subclass name from the main class name with an escaped dollar sign $ instead of a . character. This allows \javaclass to distinguish class name separators from package name separators (which need to be converted to file separators). The hash tags will be converted to dot characters on output.

For example, the LaTeX source

Use the \javaclass[maspack.matrix]{Matrix\$WriteFormat} to control formatting.

will produce the output:

Use the Matrix.WriteFormat to control formatting.

Complete control over the anchor test can be achieved using the \javaclassAlt macro, which takes two arguments: the class reference, and the visible text. So for example, the LaTeX source

Use the \javaclassAlt{maspack.matrix.Matrix\$WriteFormat}{WriteFormat}
to control formatting.

will produce the output:

Use the WriteFormat to control formatting.

\javaclassAlt is also useful in cases where one needs to embed a # tag in the class reference, such as when referring to fields of an enumerated type. The # tag can be placed in the first argument, as in this example,

\javaclassAlt{maspack.matrix.Matrix\$WriteFormat\#CRS}{WriteFormat.CRS} causes
the matrix to be written using the compressed row storage format.

which produces the output:

WriteFormat.CRS causes the matrix to be written using the compressed row storage format.

3.6.2 Method references

Methods can be referenced in a similar way using the command \javamethod, which takes a class name plus the name of a method and a (possibly abbreviated) argument signature. LaTeX source of the form


will produce output of the form

The argument signature does not need to contain the fully qualified type names of the arguments. In fact, if the method name is unique to the class, no argument list is needed at all; a simple () will suffice. Otherwise, if the method is overloaded, the argument signature should be composed of comma-separated entries, each of which partly matches the fully qualified type name of each argument.

For example,


will all produce references to the same method. In fact, if the method name and argument count is unique, then a set of commas indicating the number of arguments will be sufficient, as in \javamethodMatrixNd.mul(,).

To omit the argument signature from the anchor text, one can use the alternate command \javamethod* instead, so that

Method reference with argument signature:
\javamethod[maspack.matrix]{MatrixNd.mul(MatrixNd,MatrixNd)}, and without:

will produce the output

Method reference with argument signature: MatrixNd.mul(MatrixNd,MatrixNd), and without: MatrixNd.mul().

Finally, one may sometimes want complete control over the visible text associated with a method reference. For example, instead of MatrixNd.mul(MatrixNd,MatrixNd), one may wish to use MatrixNd.mul(M1,M2). One can do this using the command javamethodAlt, which requires two arguments (and does not take an optional argument):


The first argument specifies the class, method and arguments in enough detail to locate the link, and the second specifies the visible text.

3.6.3 How it works

\javaclass and \javamethod both work by creating a call to \href with a placeholder link of the form


This propagates to the output HTML or PostScript file, which is then processed by the Perl script setJavadocLinks, as described in Section 8.1, to set the correct URL.

3.7 References to other ArtiSynth documents

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:

  \artisynthManual{maspack}{Maspack Reference Manual}

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.