Writing Documentation for ArtiSynth

8 Local Customizations

Customization of the LaTeX/LaTeXML environment is limited to the following:

  • •

    Providing an Artisynth-specific CSS style sheet for the HTML output. This is called artisynth.css and is located in doc/style.

  • •

    Providing a .tex input file, artisynthDoc.tex, that imports the necessary packages, sets up the page layout, and defines the \javaclass and \javamethod commands (Section 3.6.1) and the sideblock environment (Section 3.4). This file is located in doc/texinputs, along with other input files that are not likely to be part of a standard LaTeX installation.

  • •

    Postprocessing the HTML produced by LaTeXML to both fill in Javadoc links, and fix a few things, including malformed blank lines in the lstlisting environment, and the presence of certain unicode characters. This is accomplished using the Perl scripts setJavadocLinks and fixLatexmlOutput located in <ARTISYNTH_HOME>/bin and described in detail below.

8.1 setJavadocLinks script

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

8.2 fixLatexmlOutput script

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.