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, including text files.

javadocs/

Contains the Javadoc API documentation.

html/

Contains the HTML output produced by LaTeXML.

pdf/

Contains the PDF files.

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

A single HTML file for a document is built using LaTeXML (Section 7.1), plus some additional post-processing. For a document file document.tex, located in the source directory <ARTISYNTH_HOME>/doc/document, a typical command sequence executed from within the source directory would look like this:

latexml and latexmlpost are both commands supplied with LaTeXML. The former converts LaTeX input into an XML file, which the latter then converts into HTML, with the result being placed into <ARTISYNTH_HOME>/doc/html/document/document.html.

The command postprocessLatexml is a script defined in <ARTISYNTH_HOME>/bin which does further post-processing on the HTML file. It does this by invoking two Perl scripts, setJavadocLinks and fixLatexmlOuput, described in detail in Section 8, which correctly set URL links to other parts of the documentation and fix some minor issues with the HTML produced by LaTeXML. The arguments --jdocDir, --jdocUrl and --docBase are passed directly to setJavadocLinks.

For use with InfoCenter (Section 6), the HTML output for a document needs to be split into multiple files corresponding to different chapters and sections. This is done with LaTeXML, using a command sequence similar to that described in Section 2.3:

The main differences are the --splitat=section option to latexmlpost, causing the HTML to be split into multiple files at the section level, and, for postprocessLatexml, the specification of --docBase as
https://www.artisynth.org/doc/info, which will cause references to other manuals to be routed through the InfoCenter URL.

InfoCenter also requires an XML file describing the document’s table contents. This is generated from the file documentToc.html (produced by latexmlpost), using the standalone Java program

  artisynth.core.util.BuildInfoCenterToc

A PDF file for a document is built using latex, dvips, some PostScript post-processing, and ps2pdf. For a document file document.tex, located in the source directory <ARTISYNTH_HOME>/doc/document, a typical command sequence executed from within the source directory would look like this:

latex is called twice to resolve references, and then dvips converts the DVI file into PostScript. The -j0 option is passed to dvips because partial font loading sometimes causes missing letters in fonts embedded image files. After the PostScript is produced, it is postprocessed by the Perl script setJavadocLinks (Section 8.1) to correctly set URL links to other parts of the documentation. The modified PostScript is then converted to PDF using ps2pdf.

The reason for converting LaTeX to PostScript, instead of PDF directly, is because setJavadocLinks does not work on PDF files.

Once you have built the documentation, you may wish to install it on the ArtiSynth webserver. In order to do this, you need

1. 1.

   An account on the ArtiSynth webserver (which is currently www.artisynth.org). To ensure proper file access, this account should be a member of the group www-data.

2. 2.

   The environment variable ARTISYNTH_WEB_ACCOUNT set to your username on that server, if that username is different from the username on your local machine.

3. 3.

   ssh and rsync installed on your local machine.

Then, from within a given documentation subdirectory, the make command

  > make install_html

will build all the HTML output associated with that directory and install it on the ArtiSynth webserver. Likewise, the command

  > make install_pdf

will build and install the PDF output, and

  > make install

will install both HTML and PDF.

From the main documentation directory <ARTISYNTH_HOME>/doc, you can build and install all the HTML and PDF documentation with the command

  > make install

HTML and PDF can also be built and installed separately with the individual commands

  > make install_html
  > make install_pdf

Also, from within <ARTISYNTH_HOME>/doc, the command

  > make install_javadocs

will install the Javadocs. Note that install_javadocs assumes you have already built the Javadocs, which as described above you can do using the command

  > make javadocs

All of these installation commands work by using rsync to copy the files and ssh to then correctly set the permissions of the copied files. If you don’t have an SSH key arranged between your local machine and the webserver, this will generally require you to enter a password twice.

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.

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.

Adding a new document will also require updating the configuration for the InfoCenter (Section 6), so that the InfoCenter knows about it and can add it to its table of contents. See the section “Adding a New Document” in the file

  <ARTISYNTH_HOME>/doc/INFOCENTER_README

The ArtiSynth website provides links to the various manuals and guides (including PDF, HTML, and InfoCenter). These should be updated to provide links to any new documentation, particularly on the main documentation page at www.artisynth.org/doc.

LaTeXML (dlmf.nist.gov/LaTeXML) is a program developed at the US National Bureau of Standards, originally to provide reliable conversion of LaTeX-based mathematical documents into HTML and XHTML. Written in Perl, it translates a .tex file into an XML schema, which is then translated to HTML or XHTML using XSLT. LaTeXML supports a large number of the more commonly used LaTeX packages but does not support them all.

Detailed instructions on installing LaTeXML are available on the website. For the ArtiSynth documentation, version 0.8.0 or higher is required (note that some pre-built releases may not provide versions this recent); at the time of this writing, the latest version is 0.8.2. The installation instructions also describe the required prerequisite software, which includes Perl, ImageMagick, and a few support packages for Perl.

Although the pre-built releases may not provide the required 0.8.0 version, it may be useful to first install a rebuild release anyway, in order to ensure installation of the prerequisite software (such as the Perl packages and ImageMagick). Then the pre-built 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 pre-built 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:

setJavadocLinks is a Perl script located in <ARTISYNTH_HOME>/bin that postprocesses either PostScript or HTML files to correctly set the URLs for Javadoc links specified by the \javaclass and \javamethod commands (Section 3.6.1). These commands insert a place holder link in the PostScript or HTML output of the form

@JDOCBEGIN/<classOrMethodName>@JDOCEND

This is then processed by setJavadocLinks, which is typically invoked as follows:

  > setJavadocLinks --jdocDir <jdir> --jdocUrl <jurl> --docBase <dbase> <input>

For each placeholder link, the script parses the corresponding Javadoc HTML file (located relative to the directory specified by --jdocDir <jdir>) to determine how to transform it into a correct URL. This includes: converting ’.’ characters to ’/’ characters, prepending the appropriate root link for the Javadocs (such as
http://www.artisynth.org/doc/javadocs, as specified by the --jdocUrl <jurl> option), and, in the case of methods, finding and appending the appropriate suffix to locate the method within the class’s Javadoc file.

setJavadocLinks also sets the correct URL for other ArtiSynth manuals specified using the \artisynthManual command. This command inserts a placeholder link in the PostScript or HTML output of the form

@ARTISYNTHDOCBASE/docpath/docname.html

for HTML files, and

https://www.artisynth.org/@ARTISYNTHDOCBASE/docname.pdf

for PDF files. setJavadocLinks then sets the correct URL by replacing @ARTISYNTHDOCBASE with the base URL specified by --docBase <dbase>.

setJavadocLinks is a Perl script located in <ARTISYNTH_HOME>/bin that postprocesses the HTML output produced by LaTeXML to fix some minor problems. These may include:

• •

  Allowing blank lines to appear in lstlisting output.

• •

  Replacing certain unicode characters that may not render properly in browsers, such as ellipsis, double quotes and backslashes.

• •

  Preventing blank lines from appearing at the beginning of certain text blocks.