1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 10.0.0a1" />
<title>LaTeX Filter</title>
<link rel="stylesheet" href="./asciidoc.css" type="text/css" />
<link rel="stylesheet" href="./layout2.css" type="text/css" />
<script type="text/javascript" src="./asciidoc.js"></script>
<script type="text/javascript">
/*<![CDATA[*/
asciidoc.install();
/*]]>*/
</script>
</head>
<body style="max-width:70em">
<div id="layout-menu-box">
<div id="layout-menu">
<div>»<a href="index.html">Home</a></div>
<div>»<a href="userguide.html">User Guide</a></div>
<div>»<a href="INSTALL.html">Installation</a></div>
<div>»<a href="faq.html">FAQ</a></div>
<div>»<a href="manpage.html">asciidoc(1)</a></div>
<div>»<a href="a2x.1.html">a2x(1)</a></div>
<div>»<a href="asciidocapi.html">API</a></div>
<div>»<a href="plugins.html">Plugins</a></div>
<div>»<a href="http://powerman.name/doc/asciidoc">Cheatsheet</a></div>
<div>»<a href="testasciidoc.html">Tests</a></div>
<div>»<a href="CHANGELOG.html">ChangeLog</a></div>
<div>»<a href="support.html">Support</a></div>
<div id="page-source">»<a href="latex-filter.txt">Page Source</a></div>
</div>
</div>
<div id="layout-content-box">
<div id="layout-banner">
<div id="layout-title">AsciiDoc</div>
<div id="layout-description">Text based document generation</div>
</div>
<div id="layout-content">
<div id="header">
<h1>LaTeX Filter</h1>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph"><p>The AsciiDoc distribution includes a LaTeX filter that translates LaTeX source
to an 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
<em>latex</em> Listing block and Paragraph styles.</p></div>
<div class="paragraph"><p>Two image formats are supported; PNG and SVG. PNG is the default since that
was the first format that this filter supported. However, SVG is a better
format since it’s scalable. Using SVG make formulas look good in both PDFs
and on web pages. SVG will also scale well when zooming in on a web page for
example. It is recommended to always use the SVG format. This can be done by
setting the <em>imgfmt</em> parameter to <em>svg</em>, as is done below. An even better way
is to set the global attribute <em>latex-imgfmt</em> to <em>svg</em>. Then SVG will be used
for all formulas.</p></div>
<div class="paragraph"><p>This LaTeX paragraph:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>["latex", imgfmt="svg"]
---------------------------------------------------------------------
\begin{equation*}
y = \int_0^\infty \gamma^2 \cos(x) dx
\end{equation*}
---------------------------------------------------------------------</code></pre>
</div></div>
<div class="paragraph"><p>Renders:</p></div>
<div class="imageblock latex">
<div class="content">
<img src="latex-filter__1.svg" alt="latex-filter__1.svg" />
</div>
</div>
<div class="paragraph"><p>Compare the formula above, which is rendered as an SVG image, to the formula
below which has been rendered as a PNG image. The difference will be most
notable if zooming in on a web page, printing the web page or when rendering
the document as a PDF.</p></div>
<div class="listingblock">
<div class="content">
<pre><code>["latex", "latex2.png", 140, imgfmt="png"]
---------------------------------------------------------------------
\begin{equation*}
y = \int_0^\infty \gamma^2 \cos(x) dx
\end{equation*}
---------------------------------------------------------------------</code></pre>
</div></div>
<div class="paragraph"><p>Renders:</p></div>
<div class="imageblock latex">
<div class="content">
<img src="latex2.png" alt="latex2.png" />
</div>
</div>
<div class="paragraph"><p>This LaTeX block:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>["latex","latex1.svg",imgfmt="svg",align="center"]
---------------------------------------------------------------------
\begin{equation*}
\displaystyle{ V_i = C_0 - C_3
\frac{C_1\cos(\theta_i+C_3)}{C_4+C_1\cos(\theta_i+C_2)} }
\end{equation*}
---------------------------------------------------------------------</code></pre>
</div></div>
<div class="paragraph"><p>Renders:</p></div>
<div class="imageblock latex" style="text-align:center;">
<div class="content">
<img src="latex1.svg" alt="latex1.svg" />
</div>
</div>
<div class="paragraph"><p>This LaTeX block:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>.LaTeX filter example
[latex]
["latex","latex3.svg",imgfmt="svg"]
---------------------------------------------------------------------
\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}
---------------------------------------------------------------------</code></pre>
</div></div>
<div class="paragraph"><p>Renders:</p></div>
<div class="imageblock latex">
<div class="content">
<img src="latex3.svg" alt="latex3.svg" />
</div>
<div class="title">Figure 1. LaTeX filter example</div>
</div>
<div class="paragraph"><p>This LaTeX paragraph:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>.A LaTeX table
["latex",imgfmt="svg"]
\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}</code></pre>
</div></div>
<div class="paragraph"><p>Renders:</p></div>
<div class="imageblock latex">
<div class="content">
<img src="latex-filter__2.svg" alt="latex-filter__2.svg" />
</div>
<div class="title">Figure 2. A LaTeX table</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_using_the_filter">Using the Filter</h2>
<div class="sectionbody">
<div class="ulist"><ul>
<li>
<p>
The LaTeX filter is invoked by setting the Listing block or
Paragraph style (the first positional block attribute) to <em>latex</em>.
</p>
</li>
<li>
<p>
The second positional attribute (named <em>target</em> is optional, it sets
the name of the generated image file. If this is not supplied a
file name like <code>{docname}__{target-number}.{imgfmt}</code> is synthesised
(where <code>{docname}</code> is the document file name, <code>{target-number}</code>
is an integer number and <code>{imgfmt}</code> is the image format (png or svg).
</p>
</li>
<li>
<p>
The third positional attribute, named <em>dpi</em>, is also optional; it is
an integer number that sets the output resolution in dots per inch
for a PNG image. It is ignored for an SVG image.
</p>
</li>
<li>
<p>
The image format to use can be selected by setting the <em>imgfmt</em>
parameter or by globally setting the <em>latex-imgfmt</em> attribute.
Setting it to <em>svg</em> will render SVG images and setting it to <em>png</em>
will render PNG images. The default is <em>png</em>.
</p>
</li>
</ul></div>
<div class="paragraph"><p>Because the LaTeX images are rendered using the image block templates
you can also use the optional named image block attributes (see
<a href="userguide.html#X55">Image macro attributes</a> in the AsciiDoc User
Guide).</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/tip.png" alt="Tip" />
</td>
<td class="content">
<div class="paragraph"><p>You can also change the image size using the following LaTeX commands:</p></div>
<div class="literalblock">
<div class="content">
<pre><code>\tiny
\scriptsize
\footnotesize
\small
\normalsize
\large
\Large
\LARGE
\huge</code></pre>
</div></div>
<div class="paragraph"><p>For example:</p></div>
<div class="literalblock">
<div class="content">
<pre><code>[latex]
\Large $y = \int_0^\infty \gamma^2 \cos(x) dx$</code></pre>
</div></div>
<div class="paragraph"><p>The <code>\Large</code> command is outside the <code>$</code> math delimiters.</p></div>
</td>
</tr></table>
</div>
<div class="paragraph"><p>The filter (<code>./filters/latex/latex2img.py</code>) can be used outside
AsciiDoc to convert LaTeX source to images.</p></div>
<div class="paragraph"><p>Execute the following command to see how to use it:</p></div>
<div class="literalblock">
<div class="content">
<pre><code>$ ./filters/latex/latex2img.py --help</code></pre>
</div></div>
</div>
</div>
<div class="sect1">
<h2 id="_limitations">Limitations</h2>
<div class="sectionbody">
<div class="ulist"><ul>
<li>
<p>
The <code>asciidoc(1)</code> input and output files cannot both be <code>-</code> (stdin
and stdout), either the input or output files (or both) must be a
named file.
</p>
</li>
</ul></div>
</div>
</div>
<div class="sect1">
<h2 id="_installation">Installation</h2>
<div class="sectionbody">
<div class="paragraph"><p>In addition to AsciiDoc you will need to have <code>latex(1)</code>,
<code>dvipng(1)</code> (for PNG) and/or <code>dvisvgm(1)</code> (for SVG) installed.</p></div>
</div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Version 9.0.5<br />
Last updated 2021-01-29 15:28:37 UTC<br />
AsciiDoc is a trademark of the Eclipse Foundation, Inc.
</div>
<div id="footer-badges">
<a href="https://validator.w3.org/check?uri=referer">
<img style="border:0;width:88px;height:31px"
src="https://www.w3.org/Icons/valid-xhtml11-blue"
alt="Valid XHTML 1.1" height="31" width="88" />
</a>
<a href="https://jigsaw.w3.org/css-validator/">
<img style="border:0;width:88px;height:31px"
src="https://jigsaw.w3.org/css-validator/images/vcss-blue"
alt="Valid CSS!" />
</a>
</div>
</div>
</div>
</div>
</body>
</html>
|
