5 Latex Code Customization

MultiMarkdown is quite good at generating LaTeX documents from MultiMarkdown formatted documents. However, for our purposes, it has a few shortcomings that require modification of LaTeX documents generated by Scrivener’s Compile Draft operation. The required changes fall into eight categories:

  1. Manual markup of table notes. MultiMarkdown’s table parsing facilities do not take into account that some tables have footnotes associated with them.

  2. Manual markup of multiline equations. MultiMarkdown’s math parsing facilities do not take into account that some equations do not fit (or are not typically displayed) on a single line.

  3. Manual markup of “case” equations. MultiMarkdown’s math parsing facilities do not take into account that some equations are piecewise — do not have the same form for all elements in their domain. These are often referred to as case equations (i.e. the equations take on different forms for different conditions or cases).

  4. Manual markup of “split” equations. MultiMarkdown’s math parsing facilities do not take into account that, in some instances, multiple equations should be aligned and considered as a single equation for numbering purposes (e.g. systems of equations in linear algebra). Among other constructs, LaTeX provides a split operation to handle this situation.

  5. Manual markup of square brackets in math expressions. MultiMarkdown’s math parsing facilities use square brackets in its link/reference syntax. It has problems disambiguating their dual uses in equations — even if they are escaped as literals.

  6. Manual markup of limits in math expressions. MultiMarkdown’s math parsing facilities had some problems interpreting limit expressions in nontraditional locations. Occasionally, manual intervention was required.

  7. Manual markup of algorithms. MultiMarkdown’s intrinsic verbatim processing does not come close to being compatible with the more sophisticated listings or algorithms styles available in LaTeX for documenting algorithms.

  8. Manual markup of references to equations in lists. This is just a bug. If you create a reference to an equation in an item in an ordered (or unordered) list, it prints as plain text, not as a reference. If you replace the MultiMarkdown reference with the appropriate LaTeX \autoref command, it resolves correctly.

Table 1 documents specific instances of these issues on this site.

Table 1: Manual Markup Requirements
Document Manual Operation Location
Graph Algorithms Algorithms All algorithms
Case equation Adjacency Matrix - Eq 1
Matrix Algorithms Algorithms All algorithms
Split equation Linear system - Eq 1
Case equation Multiplicative identity
Square brackets Symmetric data stuctures
Limits Sparse pivoting
Equation reference Solving linear equations
Factor update
Transformers Table notes Ybus maintenance - Tbl 4
Case equation Tnew - Eq 68
Transmission Lines Table notes Constant kk - Tbl 1
Z constants - Tbl 2
Equation splitting P expansion - Eq 13
Q expansion - Eq 14
Case equation Impedance Matrix - Eq 19
Potential Matrix - Eq 23

5.1 Table Notes

As mentioned above, we ultimately enter tables with footnotes into MultiMarkdown as raw LaTeX. However, we initially create these tables in MultiMarkdown using its native syntax. We then use MultiMarkdown to generate a LaTeX skeleton of the table which we modify appropriately. Our convention for entering table notes via MMD is to create one row at the bottom of the table for each note. Each of these “note rows” contains a table note in its first column.

After the tex file is generated, it is edited with TeXShop and the note rows are moved out of the tablular block to their new position following the \medskip LaTeX commands. This will cause the table notes to be centered beneath that table and included on the same page as the table (which is good enough for now).

For example, the LaTeX code for the final rows of a “table with notes” that was entered into MMD using these conventions appears as:

CDU - Conductor diameter unit \\
CRU - Conductor radius unit \\
CSU - Conductor separation unit \\
LLU - Line length unit \\
        \bottomrule
    \end{tabular}
\\\medskip\medskip
\end{minipage}
\end{table}

The manual fix describe in this section results in the following LaTeX markup:

        \bottomrule
    \end{tabular}
\\\medskip\medskip
CDU - Conductor diameter unit \\
CRU - Conductor radius unit \\
CSU - Conductor separation unit \\
LLU - Line length unit \\
\end{minipage}
\end{table}

5.2 Split Equations

When an equation is too long to fit on a single line, the math processing intrinsic to the MultiMarkdown bundle ignores the problem and continues on its merry way. To correct this oversight we augment the equation environment generated by MMD with the AMS split environment.

More specifically, edit the generated tex file with TeXShop and look for the equation of interest.

\begin{equation}
…
\end{equation}

Add a split clause around the miscreant formula.

\begin{equation}
\begin{split}
…
\end{split}
\end{equation}

Replace the equal sign in the equation with the text

= &

This defines the character immediately following the equal sign as an alignment point. Finally, add the the markup

\\
&

at each point that you want to break the equation. It splits the equation and aligns the remaining part of the formula to the right of the equal sign. For a practical example consider the following LaTeX equation markup generated by MultiMarkdown math support.

\begin{equation}
P=\frac{\pi }{8}-k\frac{cos\theta }{3\sqrt{2}}+{k}^{2}\frac{cos
\left(2\theta \right)(0.6728+ln\left(\frac{2}{k}\right))}{16}+{k}^{2}
\frac{\theta sin\left(2\theta \right)}{16}+{k}^{3}\frac{cos\left(3\theta
\right)}{45\sqrt{2}}-{k}^{4}\frac{\pi cos\left(4\theta \right)}{1536}
\end{equation}

To split this equation at the third order term, edit the LaTeX markup as follows. The markup changes in the equation are highlighted by enclosing them in —->> <<— indicators. They would not appear in the actual document.

\begin{equation}
\begin{split}
P= —-> &<— \frac{\pi }{8}-k\frac{cos\theta }{3\sqrt{2}}+{k}^{2}\frac{cos
\left(2\theta \right)(0.6728+ln\left(\frac{2}{k}\right))}{16}+{k}^{2}
\frac{\theta sin\left(2\theta \right)}{16} —>\\
& <— +{k}^{3}\frac{cos\left(3\theta \right)}{45\sqrt{2}}-{k}^{4}\frac{\pi
cos\left(4\theta\right)}{1536}
\end{split}
\end{equation}

This split operation is provided by the amsmath LaTeX package, which is automatically included in all documents generated for this site.

5.3 Case Equations

When an equation is piecewise — does not have the same form for all elements in its domain, it is referred to as a “case equation”. That is, an equation that has different forms for different conditions or cases. MultiMarkdown does not provide direct conventions for properly formatting case equations. To correct this oversight, we must insert native LaTeX markup for the case equation directly into the the MultiMarkdown text.

We usually generate properly formatted output by running MMD generated LaTeX through TeXShop and cleaning up the result. Our convention for entering case equations into MMD is

  1. Separate the condition definition of a case from its mathematical formula with an ampersand (\&).

  2. Separate each case with double backslashes (\\).

To correct the case equation, edit the generated tex file with TeXShop and look for the equation of interest. Next, locate the equal sign.

\begin{equation}
   … = …
\end{equation}

Add a begin{cases} clause immediately after the equal sign and an end{cases} before the end of the equation

\begin{equation}
   …  =\begin{cases}
   …
\end{cases}
\end{equation}

Now remove the \ from each \& and replace each \\ with \\ followed by a newline.

Consider the following example. A simple equation with two cases (adhering to our case markup conventions) generates the following LaTeX code when processed by MultiMarkdown.

\begin{equation}
\mathbf{{z}_{ij}}={R}_{ii-g}+j{X}_{ii-g}\&i=j\\{R}_{ij-g}+
     j{X}_{ij-g}\&i\ne j
\end{equation}

We modify the generated LaTeX code as follows to create a pair of equations.

\begin{equation}
\mathbf{{z}_{ij}}=\begin{cases}
{R}_{ii-g}+j{X}_{ii-g} & i=j\\
{R}_{ij-g}+j{X}_{ij-g} & i\ne j
\end{cases}
\end{equation}

This cases environment is provided by the amsmath LaTeX package, which is automatically included in all documents generated for this site.

5.4 Algorithms

Since we required captions, labels, and references to algorithms as well as keyword processing in algorithmic text, we were unable to use the intrinsic verbatim processing supported by MultiMarkdown. After looking into the issue, we concluded that both the Latex algorithms and listings packages would suit our needs. Since native LaTeXML only supports the listings package, our decision tree was simplified. It was decided that we would markup all algorithms using raw LaTeX taking advantage of the listings style.

This was possible because MultiMarkdown allows you to pass raw LaTeX to the TeX engine by enclosing the text in html style comments, i.e.

<!—  Raw LaTeX text stream —>

The string “Raw LaTeX text stream” gets passed to the LaTeX engine without MMD intervention. A typical example of algorithmic text entry in Scrivener follows.

<!—
\lstset{emph={first,insert,next}, emphstyle=\itshape}
\begin{lstlisting}[float,mathescape,caption={Adjacency List},label={adjlist}]

i = first( V )
while k $\ne$ eol
    insert( A,v,header )
    k = next( k )
k = first( E )
while k $\ne$ eol
    insert( A,e.v,e.w )
    insert( A,e.w,e.v )
    k = next( k )

\end{lstlisting}
—>

Since MultiMarkdown does not manage the labels of algorithms coded in this manner. You must enter all references to these entities as native LaTeX. For example, you would reference the preceding algorithm in a MultiMarkdown document as follows:

in Algorithm <!—\ref{adjlist}—> which updates

5.5 Equation References in Lists

The workaround for MultiMarkdown’s failure to resolve equation references in lists (ordered or unordered), is similar to the technique for referencing algorithms described in the previous section. For example, the following snippet illustrates references to equations labeled forward_sub and back_sub in an ordered MultiMarkdown list.

In summary, the preferred algorithm for solving for a nonsingular n x n
system of linear equations is:

1. Compute an LU decomposition of bA.
2. Solve <!—\autoref{forward_sub}—> for c by forward substitution.
3. Solve <!—\autoref{back_sub}—> for x by back substitution.