4 Tool Customization

The standard Scrivener/MultiMarkdown installation was modified to suit the needs of this web site. Several changes were driven by the fact that some of the LaTeX styles and classes that MultiMarkdown uses by default are not supported by LaTeXML. Other changes were related to missing features (from our perspective) in MultiMarkdown. Additionally, minor incompatibilities in MultiMarkdown’s support libraries were encountered (and repaired). Brief descriptions of the modifications follow.

4.1 MultiMarkdown to Latex Transformation

The first category of revisions involves changes to the default MultiMarkdown to LaTeX transformation. MultiMarkdown implements much of this transformation through XSL. The following items were implemented through changes to MultiMarkdown’s XSL transforms.

  1. MultiMarkdown bases its document format on the LaTeX memoir class. LaTeXML does not support this class. It supports the older article and book classes. Rather than write memoir support for LaTeXML, MultiMarkdown’s XSLT files were modified to use the LaTeXML compatible classes.

  2. MultiMarkdown table support is problematic, for our purposes, in two ways:

    • MultiMarkdown bases its table support on the LaTeX tabulary class. LaTeXML does not support this class. It supports the older tabularx and tabular classes. Rather than write tabulary support for LaTeXML, MultiMarkdown’s XSLT files were modified to use LaTeXML compatible classes.

    • MultiMarkdown tables do not support table notes (i.e. footnotes associated with a specific table) well. To overcome this limitation, we introduce the LaTeX threeparttable class into the XSL transform. To take advantage of this feature, tables must be coded as LaTeX and passed on directly to the LaTeX processor. Raw LaTeX is included in MultiMarkdown source by enclosing it in HTML (SGML) comment delimiters. In other words, the contents of HTML comments are not processed by MultiMarkdown.

  3. MultiMarkdown disables the table of contents, the list of figures, etc. in its article class. MultiMarkdown’s XSLT files were modified to produce documents containing the required entities.

  4. We modified MultiMarkdown’s hyperref processing instructions to suit our tastes.

  5. MultiMarkdown does not support the LaTeX listings style, references to listings, or generating a “list of listings” in its article class. Among other things, we use the listings style to implement algorithmic displays. MultiMarkdown’s XSLT files were modified to enable this support.

  6. Our documents are generated using the LaTeX derivative XeLaTeX (XeLaTeX provides unicode support and native font support for LaTeX). MultiMarkdown is not, by default, set up to support XeLaTeX. Its most obvious omissions on this front are as follows.

    • The default MultiMarkdown transformation does not invoke some of the base packages recommended for use with XeLaTeX (e.g. xunicode and xltxtra).

    • The default MultiMarkdown transformation does not initialize the XeLaTeX font system. To this end, we use the mathspec and fontspec packages.

  7. MultiMarkdown does not, by default, include support for the amsmath package which provides enhanced support for typesetting mathematics. MultiMarkdown’s XSLT files were modified to provide amsmath support..

We have posted an example that illustrates these modifications to the default MultiMarkdown article configuration. You can find the modified XSLT files in the MMD revisions folder of our public download area. It consists of two files: article_aft.xslt and article_aft_xhtml2latex.xslt. These files transform a MultiMarkdown document into a LaTeX “article” (one-sided) that contains a table of contents, a list of figures, a list of tables, and a list of algorithms. If you are interested in the details of the changes, browse the files and search for the string vismor.

4.2 LaTeXML Bindings

MultiMarkdown (and our permutations of it) use several additional LaTeX styles that are not directly supported by LaTeXML. We were, however, unable to discern any significant impact of their omission on the quality of LaTeXML output. Often their functionality was provided to the XHTML output through css (e.g. xcolor.sty). We created stub LaTeXML bindings (ltxml files) for these styles — to quiet down the LaTeXML processing errors. We have posted these files to the LaTeXML bindings folder of our public download area. Only one of these files, booktabs.sty.ltxml, contains any functional code. It attempts to implement some of the more critical horizontal rules of the LaTeX booktabs style.

4.3 MultiMarkdown Libraries

We encountered a couple of problems in the MultiMarkdown to Latex transformation that we attributed to MultiMarkdown’s support libraries:

  1. MultiMarkdown uses the ASCIIMathML Perl module to generate MathML from MMD text. Its handling of bold math fonts is slightly incompatible with the XSLT MathML library. Changes were made to the ASCIIMathML library to work around this difficulty and accommodate our needs. We have posted these modifications to the MMD revisions folder of our public download area. If you are interested in the details of the changes, browse the file and search for the string vismor.

  2. MultiMarkdown uses the XSLT MathML library to generate LaTeX math code from MathML. Problems were encountered using mathvariant font operations with XSLT MathML (specifically, bold math fonts). Changes were made to the XSLT MathML library to work around this bug? and accommodate our needs. We have also posted these modifications to the MMD revisions folder of our public download area. If you are interested in the nature of the changes, browse the file and search for the string vismor.

4.4 Other Observations

Revisions were also made to the native LaTeXML XSLT code to support inserting PHP processing instructions required by this web site into generated code. These changes are so esoteric and site specific that they are not publicly posted.

Some enhancements to the core.css file generated by LaTeXML were also required to prevent the algorithms displayed by the listings package from wrapping inappropriately — at seemingly random locations. Obviously, css modifications were also required so the markup generated by LaTeXML conforms to the conventions and visual style of this site. These adjustments were generally made in site specific stylesheets (document.css and docprint.css) that are loaded after (hence supersede) the native LaTeXML stylesheet.