diff options
Diffstat (limited to 'doc/asciidoc/doc/latex-filter.txt')
| -rw-r--r-- | doc/asciidoc/doc/latex-filter.txt | 196 |
1 files changed, 196 insertions, 0 deletions
diff --git a/doc/asciidoc/doc/latex-filter.txt b/doc/asciidoc/doc/latex-filter.txt new file mode 100644 index 0000000..9af9d28 --- /dev/null +++ b/doc/asciidoc/doc/latex-filter.txt @@ -0,0 +1,196 @@ +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. |