LaTeX Filter
============

:blogpost-status: published
:blogpost-doctype: article
:blogpost-posttype: page
:blogpost-categories: AsciiDoc,LaTeX,python

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:

[listing]
.....................................................................
[latex]
$y = \int_0^\infty \gamma^2 \cos(x) dx$
.....................................................................

Renders:

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

This LaTeX block:

[listing]
.....................................................................
["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:

["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)} }$
---------------------------------------------------------------------

This LaTeX block:

[listing]
.....................................................................
.LaTeX filter example
[latex]
["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:

.LaTeX filter example
[latex]
---------------------------------------------------------------------
\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}
---------------------------------------------------------------------

This LaTeX paragraph:

[listing]
.....................................................................
.A LaTeX table
[latex]
\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:

.A LaTeX table
[latex]
\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}


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
link:userguide.html#X55[Image macro attributes] in the AsciiDoc User
Guide).

[TIP]
=====================================================================
You can also change the image size using the following LaTeX commands:

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

For example:

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

The `\Large` command is outside the `$` math delimiters.

=====================================================================

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.