3 Document Publication

The creation or update of “web documents” in Scrivener has a slightly different workflow:

  1. Enter the content into Scrivener as MultiMarkdown.

  2. Compile a draft of the monograph as a LaTeX document.

  3. Convert the LaTeX document to XHTML using LaTeXML.

LaTeXML is used in the workflow since many of the documents have extensive mathematical content, which is handled quite nicely by LaTeXML. LaTeXML also has the ability to break longer documents and books into an interlinked series of files (e.g. chapters or sections) with a global table of contents, links, references, etc. This feature is used frequently — in this document for example — and allows (in combination with Scrivener) an almost complete separation of form and content in complex technical documents, which is no small feat.

LaTeXML was developed by Bruce Miller at NIST (the U. S. National Institute of Standards and Technology) for publishing the NIST Digital Library of Mathematical Functions (DLMF). It is distributed as public domain software by NIST.

3.1 Simple Documents

Getting back to the topic at hand, the specific procedure for publishing a simple “web document” (i.e. a document is published as a single XHTML file) follows:

  1. Compile a draft of the document selecting the MultiMarkdown ->> LaTeX option. Typically, each document is maintained as a separate Scrivener project.

  2. Edit the generated tex file with TexShop.

  3. Move the abstract of the document to its proper location in the tex file, i.e. between the \maketitle and \thispagestyle{empty} LaTeX commands.

  4. Save the tex file.

  5. Typeset the document twice to generate a PDF file with a complete table of contents, list of figures, etc. The second typeset operation is necessary to resolve complex cross references.

  6. Run the bash shell script that executes LaTeXML for the current document. This generates a PHP file that contains a XHTML version of the LaTeX document.

  7. Copy the generated XHTML to the appropriate directory of the development web site. The markup is in one file with a php suffix and one or more png files (x1, x2, … xn) — if the document has figures.

  8. Edit the PHP file with Coda. Delete the first line of the file (the xml prolog). We provide this through the PHP infrastructure when appropriate.

  9. Delete the lines containing the <<html>> tag and the <<head>> tag (lines 11 and 12 after step 8) of the XHTML file.

  10. Move the copyright paragraph to the end of the abstract <<div>>.

  11. Test the page locally.

  12. If everything is good, publish the updated page to the production site. Otherwise, go back to Scrivener and correct the document, then repeat this procedure.

  13. Copy the PDF file generated in step 5 to the appropriate location in the site’s public download area.

One detail of this process was glossed over in step 6 of the document publication procedure. To avoid unnecessary typing for hunt-and-peck typists, a short bash shell script is maintained for each document. It calls two LaTexML command line operations (latexml and latexmlpost) with the appropriate parameters for the document in question.

3.2 Complex Documents

The procedure for publishing a complex “web document” (i.e. a document that is published as multiple interconnected files with a table of contents) is slightly more complicated in that each generated file is touched manually. Follow steps 1 - 6 from the simple document procedure, then continue as follows:

  1. Copy the generated XHTML to the appropriate directory of the development web site. The markup is in several files with php suffixes (doc_name, S1, S2, … , Sn) and one or more png files (x1, x2, … xn) — if the document has figures.

  2. Edit each PHP file with Coda.

    1. Delete the first line of the file (the xml prolog).

    2. Delete the lines containing the <<html>> tag and the <<head>> tag (lines 11 and 12 after step 2a) of the markup file.

  3. While editing the abstract/table of contents file (doc_name.php), move the copyright paragraph to the end of the abstract <<div>>.

Complete the task by following steps 11 - 13 from the simple document procedure.

After you’ve made modifications to document in Scrivener, it takes 5–10 minutes to generate a complex document with 10 sections, publish it on the web, and publish it as as a typeset, cross referenced, PDF document with a table of contents, bibliography, list of figures, etc. While not exactly automatic, it’s not too shabby.