Writing Documentation for ArtiSynth

The sources for the various books and articles that make up the documentation are located in subdirectories in $ARTISYNTH_HOME/doc. For example, the sources for this document are located in $ARTISYNTH_HOME/doc/documentation, and the source file itself is called documentation.tex. By convention, if a document contains images, then its image files are stored in a sub-directory called images.

Additional subdirectories of doc include:

misc/

Contains miscellaneous and older documentation in formats, including text files.

javadocs/

Contains the Javadoc API documentation.

html/

Contains the HTML output produced by LaTeXML.

texinputs/

Contains input and style files used by LaTeX.

style/

Contains CSS style sheets.

Each documentation source directory contains a Makefile, which implements a few basic commands to create PDF and/or HTML output files from the LaTeX source files. To use the Makefile commands, you need to be on a system that supports GNU make. This includes Linux, MacOS, and Windows with Cygwin installed.

To create HTML output for a particular source document, run the command

  > make html

within that document’s source directory. This will create the HTML output and place it in a subdirectory under $ARTISYNTH_HOME/doc/html. It will also copy over any required image files.

To create PDF output for a document, you can use the command

  > make pdf

The resulting PDF file is copied into the directory $ARTISYNTH_HOME/doc/pdf.

By way the make operates, output will usually only be generated when the output file does not exist or when it’s older than the corresponding .tex source file. To ensure execution of a particular make command, you can precede it with

  > make clean

which will remove all extraneous and output files.

There is also a Makefile in $ARTISYNTH_HOME/doc that provides global make commands for working on all the documents. Within $ARTISYNTH_HOME/doc, the command

  > make HTML

(note the capitalization) will produce HTML output for all the documents. Likewise, make PDF will create all PDF output, and

  > make CLEAN

will clean all the subdirectories. To copy the documentation into a web-accessible directory, you can use

  > make webinstall

which assumes that the variable WEBINSTALL_DIR is properly set in the Makefile.

To create the Javadocs, you can use

  > make javadocs

which will use javadoc to build the API documentation from the system sources and place this in the javadoc subdirectory.

All documentation is written in LaTeX, and conversion to HTML is done via LaTeXML. The latter is a Perl-based application which translates a .tex file into an XML schema, which is then translated to HTML using XSLT. Currently, version 0.8.0 or higher of LaTeXML is required; see Section 7.

LaTeXML is an ongoing project which was originally developed to provide reliable conversion of LaTeX-based mathematical documents into HTML and XHTML. It supports a large number of the more commonly used LaTeX packages but does not support them all. 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 (May 2012) include:

• •

  When specifying a font inside a list item, it is sometimes necessary to include an extra space after the right closing brace, as in

    \item[{\tt labelForItem} ]
  

  in order to prevent the font from spilling over into the body of the item.

• •

  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.

• •

  Blank lines are not properly handled in the lstlisting environment. This is fixed by post-processing the HTML output, as described in Section 8.

• •

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

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.

Any type of image file can be used that is acceptable to pdflatex (e.g., .png, .pdf, and .jpg). When creating HTML output, LaTeXML automatically copies the image files into the HTML target directory, converting them if necessary into a format acceptable for web display (typically .png or .jpg). This conversion is done using the ImageMagic application suite.

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 alieviate these problems, several LaTeX macros are provided that build Javadoc references automatically from simple class and method descriptions.

Sometimes one may wish to provide a link to a complete ArtiSynth document, such as the Maspack Reference Manual. This requires knowing the base URL for the ArtiSynth documents, which can be expressed using the macro \artisynthDocBase. Using this, the above reference to the Maspack manual was coded as follows:

Internally, \artisynthDocBase simply expands to

../..

This propagates to the output HTML or PostScript file, after which it is set to the approproate URL by the Perl script setJavadocLinks described above.

You should also create a Makefile in the new directory. This is most easily done by copying an existing Makefile from a similar document, and replacing the names of the source files. Note that many of the commands and variables are predefined in the file Makedefs, included from $ARTISYNTH_HOME/doc.

You should also update the Makefile in $ARTISYNTH_HOME/doc, so that it is aware of the new document subdirectory. Most likely this will just require adding the name of the new source directory to the variable SUBDIRS.

Detailed instructions on installing LaTeXML are available at dlmf.nist.gov/LaTeXML. For the ArtiSynth documentation, version 0.8.0 or higher is required (note that some prebuilt releases may not provide versions this recent). The installation instructions also describe the required prerequisite software, which includes Perl, ImageMagick, and a few support packages for Perl.

Although the prebuilt releases may not provide the required 0.8.0 version, it may be useful to first install a prebuilt release anyway, in order to ensure installation of the prerequisite software (such as the Perl packages and ImageMagick). Then the prebuilt release can be uninstalled, leaving the prerequisites in place, and a more recent version can be installed, perhaps from a source tarball or GitHub. For example, on MacOS, if you have MacPorts installed, you can install a prebuilt release using

This may take a while, but it will install all necessary prerequisites including Perl, LaTeX, and ImageMagick. You can then uninstall LaTeXML itself, and install directly from GitHub, using a command sequence like this: