Stuart's Notes

The AsciiDoc distribution includes a LaTeX filter that translates LaTeX source to PNG image which is automatically inserted into the AsciiDoc output document. Although it can accept any LaTeX source, the primary use is to render mathematical formulae (see the examples below). The filter implements the latex Listing block and Paragraph styles.

This LaTeX paragraph:

$y = \int_0^\infty \gamma^2 \cos(x) dx$

Renders:

This LaTeX block:

["latex","latex1.png",align="center"]
---------------------------------------------------------------------
$\displaystyle{ V_i = C_0 - C_3
\frac{C_1\cos(\theta_i+C_3)}{C_4+C_1\cos(\theta_i+C_2)} }$
---------------------------------------------------------------------

Renders:

This LaTeX block:

.LaTeX filter example

["latex","latex3.png"]
---------------------------------------------------------------------
\begin{equation}
\Re{z} =\frac{n\pi \dfrac{\theta +\psi}{2}}{
\left(\dfrac{\theta +\psi}{2}\right)^2 + \left( \dfrac{1}{2}
\log \left\lvert\dfrac{B}{A}\right\rvert\right)^2}.
\end{equation}

\begin{equation}
\boxed{\eta \leq C(\delta(\eta) +\Lambda_M(0,\delta))}
\end{equation}

\begin{equation}\label{first}
a=b+c
\end{equation}

\begin{subequations}\label{grp}
\begin{align}
a&=b+c\label{second}\\
d&=e+f+g\label{third}\\
h&=i+j\label{fourth}
\end{align}
\end{subequations}
---------------------------------------------------------------------

Renders:

Figure 1. LaTeX filter example

This LaTeX paragraph:

.A LaTeX table

\begin{tabular}{c r @{.} l}
Pi expression &
\multicolumn{2}{c}{Value} \\
\hline
$\pi$ & 3&1416 \\
$\pi^{\pi}$ & 36&46 \\
$(\pi^{\pi})^{\pi}$ & 80662&7 \\
\end{tabular}

Renders:

Figure 2. A LaTeX table

Using the Filter

• The LaTeX filter is invoked by setting the Listing block or Paragraph style (the first positional block attribute) to latex.
• The second positional attribute (named target is optional, it sets the name of the generated PNG image file. If this is not supplied a file name like {docname}__{target-number}.png is synthesised (where {docname} is the document file name and {target-number} is an integer number.
• The third positional attribute, named dpi, is also optional; it is an integer number that sets the output resolution in dots per inch.

Because the LaTeX images are rendered using the image block templates you can also use the optional named image block attributes (see Image macro attributes in the AsciiDoc User Guide).

\tiny
\scriptsize
\footnotesize
\small
\normalsize
\large
\Large
\LARGE
\huge

\Large $y = \int_0^\infty \gamma^2 \cos(x) dx$

The filter (./filters/latex/latex2png.py) can be used outside AsciiDoc to convert LaTeX source to PNG images.

Execute the following command to see how to use it:

$ ./filters/latex/latex2png.py --help

Limitations

• The asciidoc(1) input and output files cannot both be - (stdin and stdout), either the input or output files (or both) must be a named file.

Installation

In addition to AsciiDoc you will need to have latex(1) and dvipng(1) installed.