Writing Documentation for ArtiSynth

2 How Documents Are Created

ArtiSynth documentation is written using LaTeX, and converted into either PDF files, single HTML files for direct browser viewing, or sectioned HTML files for viewing within an Eclipse InfoCenter (Section 6). PDF files are built using latex, dvips and eps2pdf as described in Section 2.5. Single and sectioned HTML files are built using LaTeXML (dlmf.nist.gov/LaTeXML), as described in Sections 2.3 and 2.4.

Makefiles are used to organize the commands and options needed to build these different outputs. As such, documentation is most easily built on systems that support GNU make, such as Linux, MacOS, or Windows running Cygwin or some other Unix-like shell.

The format for PDF output is based on that used by the DocBook project, while the style for HTML files is based on that used by AsciiDoc.

The usual workflow when editing or changing an ArtiSynth document is:
- Edit the .tex file in a text editor
- Run make html and/or make pdf to build HTML or PDF files (Section 2.2)
- If appropriate, run make install to install the files on the ArtiSynth webserver (Section 2.6)
- Examine the output using a browser or PDF reader

2.1 Document Source Code Organization

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.

2.2 Makefile commands to build documents

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.

2.2.1 Javadocs

Java API documentation is built in the directory <ARTISYNTH_HOME>/doc/javadocs by running the command

  > make javadocs

from within the directory <ARTISYNTH_HOME>/doc.

2.2.2 HTML files

To build a single HTML file for a particular source document, run the command

  > make html

within that document’s source directory. This will build the HTML file, as described in Section 2.3, and place it in a subdirectory under <ARTISYNTH_HOME>/doc/html. It will also copy over any required image files.

If the documentation contains Javadoc API references, using the \javaclass or \javamethod commands described in Section 3.6, then it is necessary to ensure that the Javadocs are built and up-to-date (Section 2.2.1). Otherwise, links to the specified Javadocs may not be found, resulting in warning messages that look like

...
WARNING: class maspack.properties.HasProperties not found
Can’t open ../javadocs/maspack/properties/HasProperties.html: No such file or directory
WARNING: class maspack.properties.HasProperties not found for method getProperty
WARNING: class maspack.properties.Property not found
...

To build subsectioned HTML files for a viewing a source document within an Eclipse InfoCenter, run the command

  > make infocenter

This will build HTML files for the document subsections, along with a table of contents for use by InfoCenter, as described in Section 2.4, and place them in a subdirectory under <ARTISYNTH_HOME>/doc/html. The table of contents file is an XML file and will generally have the name <document>Toc.xml, where <document> is the base name of the source document.

To build single or sectioned HTML files for all the documentation, you can run the commands

  > make HTML

or

  > make INFOCENTER

from within the documentation root directory <ARTISYNTH_HOME>/doc.

2.2.3 PDF files

To build a PDF file for a document, you can use the command 

  > make pdf

within that document’s source directory. This will build a PDF file, as described in Section 2.5, and copy it into the directory <ARTISYNTH_HOME>/doc/pdf.

To build PDF files for all the documentation, you can run the command

  > make PDF

from within the documentation root directory <ARTISYNTH_HOME>/doc.

2.2.4 Other Commands

Within a document’s directory, the simple command

  > make

will build both HTML and PDF output files.

By way the make operates, output will usually only be built 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 within a document’s source directory, you can precede it with

  > make clean

which will remove all extraneous and output files. Likewise, to clean all documents, you can run

  > make CLEAN

from within the documentation root directory <ARTISYNTH_HOME>/doc.

Finally, the command 

  > make all

from within the documentation root directory, is equivalent to

  > make javadocs PDF HTML INFOCENTER

2.3 Building single HTML files

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 document.tex > document.xml
  latexmlpost –mathimages –format=html4 –css=../style/artisynth.css \
     –destinatiom=../html/document/document.html
  postprocessLatexml –jdocDir ../javadocs –jdocUrl ../../javadocs \
     –docBase .. ../html/document/document.html

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.

2.4 Building sectioned HTML files

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:

⬇
  latexml document.tex > document.xml
  latexmlpost –mathimages –format=html4 –css=../style/artisynth.css \
     –splitat=section –destinatiom=../html/document/document.html
  postprocessLatexml –jdocDir ../javadocs –jdocUrl ../../javadocs \
     –docBase https://www.artisynth.org/doc/info ../html/document/*.html

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

2.5 Building PDF files

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 document.tex
  latex document.tex
  dvips -j0 document
  setJavadocLinks –postscript –out tmpfile.ps –jdocDir ../javadocs \
     –jdocUrl https://www.artisynth.org/doc/javadocs –docBase doc/pdf document.ps
  mv tmpfile.ps document.ps
  ps2pdf document.ps

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.

2.6 Installing Documents on the Webserver

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.