« back to all changes in this revision
Viewing changes to examples/website/faq.html
- browse files at revision 15
- compare with another revision
- download diff
- download tarball
- view history from revision 15
- Committer: Bazaar Package Importer
- Author(s): Alexander Wirt
- Date: 2010-11-27 23:19:57 UTC
- mfrom: (1.1.12 upstream) (3.1.6 sid)
- Revision ID: james.westby@ubuntu.com-20101127231957-jxdmrk7z7lkcqy3l
Tags: 8.6.3-1
* New upstream version (Closes: #595324)
* Support asciidoc API (Closes: #526351)
* Depend on python >= 2.4 (Closes: #571303)
* Do not compress .txt files (Closes: #592423)
* Enhance asciidoc manpage (Closes: #499497)
* Move some of the Recommends (vim-addon-manager, source-highlight) to
Suggests (Closes: #564015)
* Bump standards version (No changes)
* Add README.Source file
* Support asciidoc API (Closes: #526351)
* Depend on python >= 2.4 (Closes: #571303)
* Do not compress .txt files (Closes: #592423)
* Enhance asciidoc manpage (Closes: #499497)
* Move some of the Recommends (vim-addon-manager, source-highlight) to
Suggests (Closes: #564015)
* Bump standards version (No changes)
* Add README.Source file
- files added:
- MANIFEST
- examples/website/epub-notes.txt
- examples/website/latex-filter.txt
- examples/website/publishing-ebooks-with-asciidoc.txt
- examples/website/slidy-example.txt
- examples/website/slidy.txt
- filters/latex
- stylesheets/volnitsky-quirks.css
- files removed:
- debian/patches/a2x-defaultdirs.patch
- files modified:
- BUGS
added
removed
examples/website/faq.html
1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4
<head>
5
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6
<meta name="generator" content="AsciiDoc 8.5.2" />
7
<link rel="stylesheet" href="./xhtml11.css" type="text/css" />
8
<link rel="stylesheet" href="./xhtml11-quirks.css" type="text/css" />
9
<link rel="stylesheet" href="./layout1.css" type="text/css" />
10
<script type="text/javascript">
11
/*<![CDATA[*/
12
window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}
13
/*]]>*/
14
</script>
15
<script type="text/javascript" src="./asciidoc-xhtml11.js"></script>
16
<title>AsciiDoc Frequently Asked Questions</title>
17
</head>
18
<body style="max-width:70em">
19
<div id="layout-banner">
20
<div id="layout-title">AsciiDoc</div>
21
<div id="layout-description">Text based document generation</div>
22
</div>
23
<table>
24
<tr valign="top">
25
<td id="layout-menu">
26
<div>»<a href="index.html">Home</a></div>
27
<div>»<a href="manpage.html">Man Page</a></div>
28
<div>»<a href="userguide.html">User Guide</a></div>
29
<div>»<a href="INSTALL.html">Installation</a></div>
30
<div>»<a href="faq.html">FAQ</a></div>
31
<div>»<a href="a2x.1.html">a2x</a></div>
32
<div>»<a href="asciidocapi.html">API</a></div>
33
<div>»<a href="http://powerman.name/doc/asciidoc">Cheatsheet</a></div>
34
<div>»<a href="testasciidoc.html">Tests</a></div>
35
<div>»<a href="CHANGELOG.html">ChangeLog</a></div>
36
<div>»<a href="support.html">Support</a></div>
37
<div id="page-source">»<a href="faq.txt">Page Source</a></div>
38
</td>
39
<td>
40
<div id="layout-content">
41
<div id="header">
42
<h1>AsciiDoc Frequently Asked Questions</h1>
43
<div id="toc">
44
<div id="toctitle">Table of Contents</div>
45
<noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
46
</div>
47
</div>
48
<div id="content">
49
<h2 id="_why_am_i_having_trouble_getting_nested_macros_to_work">1. Why am I having trouble getting nested macros to work?</h2>
50
<div class="sectionbody">
51
<div class="paragraph"><p>The following example expands the <em>image</em> inline macro, but the
52
expansion contains double-quote characters which confuses the ensuing
53
<em>footnoteref</em> macro epansion:</p></div>
54
<div class="literalblock">
55
<div class="content">
56
<pre><tt>footnoteref:["F1","A footnote, with an image image:smallnew.png[]"]</tt></pre>
57
</div></div>
58
<div class="paragraph"><p>The solution is to use unquoted attribute values, replacing embedded
59
commas with the comma character entity (<tt>&#44;</tt>):</p></div>
60
<div class="literalblock">
61
<div class="content">
62
<pre><tt>footnoteref:[F1,A footnote&#44; with an image image:smallnew.png[]]</tt></pre>
63
</div></div>
64
<div class="paragraph"><p>Similarly, you can embed double-quote characters in unquoted attribute
65
values using the <tt>&#34;</tt> character entity.</p></div>
66
</div>
67
<h2 id="_why_am_i_getting_docbook_validation_errors">2. Why am I getting DocBook validation errors?</h2>
68
<div class="sectionbody">
69
<div class="paragraph"><p>Not all valid AsciiDoc source generates valid DocBook, for example
70
<em>special sections</em> (abstract, preface, colophon, dedication,
71
bibliography, glossary, appendix, index, synopsis) have different
72
DocBook schemas to normal document sections. For example, a paragraph
73
is illegal in a bibliography.</p></div>
74
<div class="paragraph"><p>Don’t forget if your document is a book you need to specify the <tt>-d
75
book</tt>, if you don’t an article DocBook document will be generated,
76
possibly containing book specific sections, leading to validation
77
errors.</p></div>
78
</div>
79
<h2 id="_how_can_i_disable_special_section_titles">3. How can I disable special section titles?</h2>
80
<div class="sectionbody">
81
<div class="paragraph"><p>For example, you want to use <em>References</em> as a normal section name but
82
AsciiDoc is auto-magically generating a DocBook <em>bibliography</em>
83
section. All you need to do is explicitly specify the section template
84
name:</p></div>
85
<div class="literalblock">
86
<div class="content">
87
<pre><tt>[sect1]
88
References
89
----------</tt></pre>
90
</div></div>
91
</div>
92
<h2 id="_why_don_8217_t_tables_generated_by_dblatex_obey_the_width_attribute">4. Why don’t tables generated by dblatex obey the width attribute?</h2>
93
<div class="sectionbody">
94
<div class="paragraph"><p>Tables generated by dblatex will take 100% of the available space
95
unless you change the <em>pageunits</em> micellaneous parameter to <em>pt</em>. You
96
can do this:</p></div>
97
<div class="ulist"><ul>
98
<li>
99
<p>
100
From the command-line with the <tt>-a pageunits=pt</tt> option
101
</p>
102
</li>
103
<li>
104
<p>
105
Or by setting <tt>pageunits=pt</tt> in a configuration file
106
<tt>[miscellaneous]</tt> section.
107
</p>
108
</li>
109
<li>
110
<p>
111
Or by setting this AttributeEntry in your document:
112
</p>
113
<div class="literalblock">
114
<div class="content">
115
<pre><tt>:miscellaneous.pageunits: pt</tt></pre>
116
</div></div>
117
</li>
118
</ul></div>
119
<div class="paragraph"><p>See the
120
<a href="http://www.methods.co.nz/asciidoc/userguide.html#X89">DocBook table
121
widths</a> sidebar in the <em>AsciiDoc User Guide</em> for an explanation.</p></div>
122
</div>
123
<h2 id="_how_can_i_insert_xml_processing_instructions_into_output_documents">5. How can I insert XML processing instructions into output documents?</h2>
124
<div class="sectionbody">
125
<div class="paragraph"><p>Use an inline or block passthrough macros. This example inserts
126
<tt><?dblatex bgcolor="#cceeff"?></tt> into the DocBook output generated by
127
AsciiDoc:</p></div>
128
<div class="literalblock">
129
<div class="content">
130
<pre><tt>pass::[<?dblatex bgcolor="#cceeff"?>]</tt></pre>
131
</div></div>
132
<div class="admonitionblock">
133
<table><tr>
134
<td class="icon">
135
<img src="./images/icons/note.png" alt="Note" />
136
</td>
137
<td class="content">XML processing instructions are specific to the application that
138
processes the XML (the previous <tt>dblatex</tt> processing instruction is
139
recognized by <tt>dblatex(1)</tt> when it processes the DocBook XML generated
140
by Asciidoc).</td>
141
</tr></table>
142
</div>
143
</div>
144
<h2 id="_how_do_i_prevent_double_quoted_text_being_mistaken_for_an_inline_literal">6. How do I prevent double-quoted text being mistaken for an inline literal?</h2>
145
<div class="sectionbody">
146
<div class="paragraph"><p>Mixing doubled-quoted text with inline literal passthroughs can
147
produce undesired results, for example, all of the following line is
148
interpreted as an inline literal passthrough:</p></div>
149
<div class="literalblock">
150
<div class="content">
151
<pre><tt>``XXX'' `YYY`</tt></pre>
152
</div></div>
153
<div class="paragraph"><p>In this case the solution is to use monospace quoting instead of the
154
inline literal:</p></div>
155
<div class="literalblock">
156
<div class="content">
157
<pre><tt>``XXX'' +YYY+</tt></pre>
158
</div></div>
159
<div class="paragraph"><p>Use the <tt>pass:[]</tt> macro if it’s necessary to supress
160
substitutions in the monospaced text, for example:</p></div>
161
<div class="literalblock">
162
<div class="content">
163
<pre><tt>``XXX'' +pass:[don't `quote` me]+</tt></pre>
164
</div></div>
165
</div>
166
<h2 id="_how_can_i_generate_a_single_html_document_file_containing_images_and_css_styles">7. How can I generate a single HTML document file containing images and CSS styles?</h2>
167
<div class="sectionbody">
168
<div class="paragraph"><p>With the advent of Internet Explorer 8 all major web browsers now
169
support the
170
<a href="http://en.wikipedia.org/wiki/Data:_URI_scheme">data URI scheme</a> for
171
embedded images. The AsciiDoc <em>xhtml11</em> backend supports the data URI
172
scheme for embedded images and by default it embeds the CSS
173
stylesheet. For example the following command will generate a single
174
<tt>article.html</tt> file containing embedded images, admonition icons and the CSS
175
stylesheet:</p></div>
176
<div class="literalblock">
177
<div class="content">
178
<pre><tt>$ asciidoc -a data-uri -a icons article.txt</tt></pre>
179
</div></div>
180
</div>
181
<h2 id="_are_there_any_tools_to_help_me_understand_what_8217_s_going_on_inside_asciidoc">8. Are there any tools to help me understand what’s going on inside AsciiDoc?</h2>
182
<div class="sectionbody">
183
<div class="paragraph"><p>AsciiDoc has a built-in trace mechanism which is controlled by the
184
<em>trace</em> attribute; there is also the <tt>--verbose</tt> command-line option.
185
These features are detailed in
186
<a href="http://www.methods.co.nz/asciidoc/userguide.html#X82">Appendix G of the
187
User Guide</a>.</p></div>
188
</div>
189
<h2 id="_one_liner_ifdef_s_are_disproportionately_verbose_can_they_shortened">9. One-liner ifdef::[]'s are disproportionately verbose can they shortened?</h2>
190
<div class="sectionbody">
191
<div class="paragraph"><p>This is the response to a question posted on the AsciiDoc discussion
192
list, it illustrates a number of useful techniques. The question arose
193
because the source highlight filter language identifier for the C++
194
language is <tt>c++</tt> when generating PDF’s via dblatex (LaTeX listings
195
package) or <tt>cpp</tt> when generating HTML (GNU source-highlight).</p></div>
196
<div class="paragraph"><p>Using straight <tt>ifdef::[]</tt> block macros we have:</p></div>
197
<div class="listingblock">
198
<div class="content">
199
<pre><tt>ifdef::basebackend-docbook[]
200
[source,c++]
201
endif::basebackend-docbook[]
202
ifdef::basebackend-html[]
203
[source,cpp]
204
endif::basebackend-html[]
205
-----------------------------------------
206
class FooParser {
207
public:
208
virtual void startDocument() = 0;
209
virtual void endDocument() = 0;
210
};
211
-----------------------------------------</tt></pre>
212
</div></div>
213
<div class="paragraph"><p>This can be shortened using the short form of the <tt>ifdef::[]</tt> macro:</p></div>
214
<div class="listingblock">
215
<div class="content">
216
<pre><tt>ifdef::basebackend-docbook[[source,c++]]
217
ifdef::basebackend-html[[source,cpp]]
218
-----------------------------------------
219
class FooParser {
220
public:
221
virtual void startDocument() = 0;
222
virtual void endDocument() = 0;
223
};
224
-----------------------------------------</tt></pre>
225
</div></div>
226
<div class="paragraph"><p>Using a conditional attribute instead of the <tt>ifdef::[]</tt> macro is even
227
shorter:</p></div>
228
<div class="listingblock">
229
<div class="content">
230
<pre><tt>[source,{basebackend@docbook:c++:cpp}]
231
-----------------------------------------
232
class FooParser {
233
public:
234
virtual void startDocument() = 0;
235
virtual void endDocument() = 0;
236
};
237
-----------------------------------------</tt></pre>
238
</div></div>
239
<div class="paragraph"><p>If you have a number of listings it makes sense to factor the
240
conditional attribute to a normal attribute:</p></div>
241
<div class="listingblock">
242
<div class="content">
243
<pre><tt>:cpp: {basebackend@docbook:c++:cpp}
244
245
[source,{cpp}]
246
-----------------------------------------
247
class FooParser {
248
public:
249
virtual void startDocument() = 0;
250
virtual void endDocument() = 0;
251
};
252
-----------------------------------------</tt></pre>
253
</div></div>
254
<div class="paragraph"><p>Even shorter, set the default source highlight filter <tt>language</tt>
255
attribute so you don’t have to specify it every time:</p></div>
256
<div class="listingblock">
257
<div class="content">
258
<pre><tt>:language: {basebackend@docbook:c++:cpp}
259
260
[source]
261
-----------------------------------------
262
class FooParser {
263
public:
264
virtual void startDocument() = 0;
265
virtual void endDocument() = 0;
266
};
267
-----------------------------------------</tt></pre>
268
</div></div>
269
</div>
270
<h2 id="_some_of_my_inline_passthroughs_are_not_passed_through_why">10. Some of my inline passthroughs are not passed through, why?</h2>
271
<div class="sectionbody">
272
<div class="paragraph"><p>Most likely the passthrough encloses another passthrough with a higher
273
precedence. For example trying to render this <tt>pass:[]</tt> with this
274
<tt>`pass:[]`</tt> results in a blank string because the <tt>pass:[]</tt>
275
passthrough evaluates first, instead use monspaced quoting and escape
276
the passthrough i.e. <tt> +\pass:[]+ </tt></p></div>
277
</div>
278
<h2 id="_how_can_i_place_an_anchor_link_target_on_a_list_item">11. How can I place an anchor (link target) on a list item?</h2>
279
<div class="sectionbody">
280
<div class="paragraph"><p>You can’t use a <em>BlockId</em> block element inside a list but you can use
281
the syntactically identical <em>anchor</em> inline macro. For example:</p></div>
282
<div class="listingblock">
283
<div class="content">
284
<pre><tt>one:: Item one.
285
[[X2]]two:: Item two.
286
three:: Item three.</tt></pre>
287
</div></div>
288
<div class="paragraph"><p>This <strong>will not</strong> work:</p></div>
289
<div class="listingblock">
290
<div class="content">
291
<pre><tt>one:: Item one.
292
[[X2]]
293
two:: Item two.
294
three:: Item three.</tt></pre>
295
</div></div>
296
</div>
297
<h2 id="_how_can_i_stop_lists_from_nesting">12. How can I stop lists from nesting?</h2>
298
<div class="sectionbody">
299
<div class="paragraph"><p>If you place two lists with different syntax hard up against each
300
other then the second list will be nested in the first. If you don’t
301
want the second list to be nested separate them with a comment line
302
block macro. For example:</p></div>
303
<div class="listingblock">
304
<div class="content">
305
<pre><tt>1. List 1.
306
2. List 1.
307
308
//
309
a. List 2.
310
b. List 2.</tt></pre>
311
</div></div>
312
</div>
313
<h2 id="_is_it_possible_to_include_charts_in_asciidoc_documents">13. Is it possible to include charts in AsciiDoc documents?</h2>
314
<div class="sectionbody">
315
<div class="paragraph"><p>There are a number of programs available that generate presentation
316
charts from textual specification, for example
317
<a href="http://home.gna.org/pychart/">Pychart</a> is a library for writing chart
318
scripts in Python. Here’s an example from the <em>Pychart</em> documentation:</p></div>
319
<div class="listingblock">
320
<div class="title">barchart.py</div>
321
<div class="content">
322
<pre><tt>#
323
# Example bar chart (from Pychart documentation http://home.gna.org/pychart/).
324
#
325
from pychart import *
326
theme.get_options()
327
328
data = [(10, 20, 30, 5), (20, 65, 33, 5), (30, 55, 30, 5), (40, 45, 51, 7),
329
(50, 25, 27, 3), (60, 75, 30, 5), (70, 80, 42, 5), (80, 62, 32, 5),
330
(90, 42, 39, 5), (100, 32, 39, 4)]
331
332
# The attribute y_coord=... tells that the Y axis values
333
# should be taken from samples.
334
# In this example, Y values will be [40,50,60,70,80].
335
ar = area.T(y_coord = category_coord.T(data[3:8], 0),
336
x_grid_style=line_style.gray50_dash1,
337
x_grid_interval=20, x_range = (0,100),
338
x_axis=axis.X(label="X label"),
339
y_axis=axis.Y(label="Y label"),
340
bg_style = fill_style.gray90,
341
border_line_style = line_style.default,
342
legend = legend.T(loc=(80,10)))
343
344
# Below call sets the default attributes for all bar plots.
345
chart_object.set_defaults(bar_plot.T, direction="horizontal", data=data)
346
347
# Attribute cluster=(0,3) tells that you are going to draw three bar
348
# plots side by side. The plot labeled "foo" will the leftmost (i.e.,
349
# 0th out of 3). Attribute hcol tells the column from which to
350
# retrive sample values from. It defaults to one.
351
ar.add_plot(bar_plot.T(label="foo", cluster=(0,3)))
352
ar.add_plot(bar_plot.T(label="bar", hcol=2, cluster=(1,3)))
353
ar.add_plot(bar_plot.T(label="baz", hcol=3, cluster=(2,3)))
354
ar.draw()</tt></pre>
355
</div></div>
356
<div class="paragraph"><p>To execute the script and include the generated chart image in your
357
document add the following lines to the AsciiDoc source:</p></div>
358
<div class="listingblock">
359
<div class="content">
360
<pre><tt>// Generate chart image file.
361
sys2::[python "{indir}/barchart.py" --format=png --output="{outdir}/barchart.png" --scale=2]
362
363
// Display chart image file.
364
image::barchart.png[]</tt></pre>
365
</div></div>
366
<div class="admonitionblock">
367
<table><tr>
368
<td class="icon">
369
<img src="./images/icons/note.png" alt="Note" />
370
</td>
371
<td class="content">
372
<div class="ulist"><ul>
373
<li>
374
<p>
375
The <tt>barchart.py</tt> script is located in the same directory as the
376
AsciiDoc source file (<tt>{indir}</tt>).
377
</p>
378
</li>
379
<li>
380
<p>
381
The generated chart image file (<tt>barchart.png</tt>) is written to the
382
same directory as the output file (<tt>{outdir}</tt>).
383
</p>
384
</li>
385
</ul></div>
386
</td>
387
</tr></table>
388
</div>
389
</div>
390
<h2 id="_how_can_i_render_indented_paragraphs">14. How can I render indented paragraphs?</h2>
391
<div class="sectionbody">
392
<div class="paragraph"><p>To unconditionally indent all paragraphs add the following line to the
393
<tt>xhtml11.css</tt> stylesheet (or a custom stylesheet).</p></div>
394
<div class="listingblock">
395
<div class="content">
396
<pre><tt>div.paragraph p {text-indent: 3em;}</tt></pre>
397
</div></div>
398
<div class="paragraph"><p>This will restyle the entire document by indenting all paragraphs
399
which is normally what you want to do (mixed paragraph styles produce
400
ugly documents).</p></div>
401
<div class="paragraph"><p>To selectively indent paragraphs with the <em>indented</em> style add the
402
following line to the <tt>xhtml11.css</tt> stylesheet (or a custom
403
stylesheet).</p></div>
404
<div class="listingblock">
405
<div class="content">
406
<pre><tt>div.paragraph.indented p {text-indent: 3em;}</tt></pre>
407
</div></div>
408
<div class="paragraph"><p>Then apply the <em>indented</em> style to normal paragraphs, for example:</p></div>
409
<div class="listingblock">
410
<div class="content">
411
<pre><tt>[indented]
412
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas
413
ultrices justo porttitor augue. Vestibulum pretium. Donec porta
414
vestibulum mi. Aliquam pede. Aenean lobortis lorem et lacus. Sed
415
lacinia. Vivamus at lectus.</tt></pre>
416
</div></div>
417
<div class="admonitionblock">
418
<table><tr>
419
<td class="icon">
420
<img src="./images/icons/note.png" alt="Note" />
421
</td>
422
<td class="content">This FAQ applies to XHTML output not DocBook. To achieve the
423
same results with DocBook you would need to customize the DocBook XSL
424
stylesheets to indent paragraphs with the <tt>simpara</tt> element
425
<tt>role="indented"</tt> attribute.</td>
426
</tr></table>
427
</div>
428
</div>
429
<h2 id="_is_there_a_way_to_set_default_image_height_and_width_attributes">15. Is there a way to set default image height and width attributes?</h2>
430
<div class="sectionbody">
431
<div class="paragraph"><p>You can set the <em>height</em> and <em>width</em> attributes globally in your
432
document with Attribute Entries or from the command-line using the
433
<tt>--attribute</tt> option. In the following example images that don’t
434
explicitly set the <em>height</em> and <em>width</em> values will be 350 by 250
435
pixels.</p></div>
436
<div class="listingblock">
437
<div class="content">
438
<pre><tt>:height: 250
439
:width: 350
440
441
image:images/tiger.png[]</tt></pre>
442
</div></div>
443
<div class="admonitionblock">
444
<table><tr>
445
<td class="icon">
446
<img src="./images/icons/note.png" alt="Note" />
447
</td>
448
<td class="content">Setting the global <em>width</em> attribute will also set the default
449
table width and you will need to explicitly table widths.</td>
450
</tr></table>
451
</div>
452
</div>
453
<h2 id="_how_can_i_place_a_backslash_character_in_front_of_an_attribute_reference_without_escaping_the_reference">16. How can I place a backslash character in front of an attribute reference without escaping the reference?</h2>
454
<div class="sectionbody">
455
<div class="paragraph"><p>Use the predefined <tt>{backslash}</tt> attribute reference instead of an
456
actual backslash, for example if the <tt>{projectname}</tt> attribute has
457
the value <tt>foobar</tt> then:</p></div>
458
<div class="literalblock">
459
<div class="content">
460
<pre><tt>d:\data{backslash}{projectname}</tt></pre>
461
</div></div>
462
<div class="paragraph"><p>would be rendered as:</p></div>
463
<div class="literalblock">
464
<div class="content">
465
<pre><tt>d:\data\foobar</tt></pre>
466
</div></div>
467
</div>
468
<h2 id="_how_can_i_escape_asciidoc_markup">17. How can I escape AsciiDoc markup?</h2>
469
<div class="sectionbody">
470
<div class="paragraph"><p>Most AsciiDoc inline elements can be suppressed by preceding them with
471
a backslash character. These elements include:</p></div>
472
<div class="ulist"><ul>
473
<li>
474
<p>
475
Attribute references.
476
</p>
477
</li>
478
<li>
479
<p>
480
Text formatting.
481
</p>
482
</li>
483
<li>
484
<p>
485
Quoting,
486
</p>
487
</li>
488
<li>
489
<p>
490
Macros.
491
</p>
492
</li>
493
<li>
494
<p>
495
Replacements.
496
</p>
497
</li>
498
<li>
499
<p>
500
Special words.
501
</p>
502
</li>
503
<li>
504
<p>
505
Table cell separators.
506
</p>
507
</li>
508
</ul></div>
509
<div class="paragraph"><p>But there are exceptions — see the next question.</p></div>
510
</div>
511
<h2 id="_some_elements_can_8217_t_be_escaped_with_a_single_backslash">18. Some elements can’t be escaped with a single backslash</h2>
512
<div class="sectionbody">
513
<div class="paragraph"><p>There are a number of exceptions to the usual single backslash rule — mostly relating to URL macros that have two syntaxes or quoting
514
ambiguity. Here are some non-standard escape examples:</p></div>
515
<div class="tableblock">
516
<table rules="all"
517
width="40%"
518
frame="border"
519
cellspacing="0" cellpadding="4">
520
<col width="50%" />
521
<col width="50%" />
522
<thead>
523
<tr>
524
<th align="left" valign="top">AsciiDoc </th>
525
<th align="left" valign="top"> Renders</th>
526
</tr>
527
</thead>
528
<tbody>
529
<tr>
530
<td align="left" valign="top"><div class="literal"><pre><tt>\srackham@methods.co.nz
531
<\srackham@methods.co.nz>
532
\mailto:[\srackham@methods.co.nz]</tt></pre></div></td>
533
<td align="left" valign="top"><div class="verse">srackham@methods.co.nz
534
<srackham@methods.co.nz>
535
mailto:[srackham@methods.co.nz]</div></td>
536
</tr>
537
<tr>
538
<td align="left" valign="top"><div class="literal"><pre><tt>\http://www.foo1.co.nz
539
\\http://www.foobar.com[]
540
\\http://www.foobar.com[Foobar Limited]</tt></pre></div></td>
541
<td align="left" valign="top"><div class="verse">http://www.foo1.co.nz
542
http://www.foobar.com[]
543
http://www.foobar.com[Foobar Limited]</div></td>
544
</tr>
545
<tr>
546
<td align="left" valign="top"><div class="literal"><pre><tt>A C\++ Library for C++
547
\\``double-quotes''
548
\*\*F**ile Open\...</tt></pre></div></td>
549
<td align="left" valign="top"><div class="verse">A C++ Library for C++
550
``double-quotes''
551
**F**ile Open...</div></td>
552
</tr>
553
</tbody>
554
</table>
555
</div>
556
<div class="paragraph"><p>The source of this problem is ambiguity across substitution types — the first match unescapes allowing the second to substitute. A
557
work-around for difficult cases is to side-step the problem using the
558
<tt>pass:[]</tt> passthrough inline macro.</p></div>
559
<div class="admonitionblock">
560
<table><tr>
561
<td class="icon">
562
<img src="./images/icons/note.png" alt="Note" />
563
</td>
564
<td class="content">Escaping is unnecessary inside <em>inline literal passthroughs</em>
565
(backtick quoted text).</td>
566
</tr></table>
567
</div>
568
</div>
569
<h2 id="_how_can_i_set_default_list_and_tables_styles">19. How can I set default list and tables styles?</h2>
570
<div class="sectionbody">
571
<div class="paragraph"><p>You can set the element’s <em>style</em> entry in a global or custom
572
configuration file.</p></div>
573
<div class="paragraph"><p>This example this will horizontally style all labeled lists that don’t
574
have an explicit style attribute:</p></div>
575
<div class="listingblock">
576
<div class="content">
577
<pre><tt>[listdef-labeled]
578
style=horizontal
579
580
[listdef-labeled2]
581
style=horizontal</tt></pre>
582
</div></div>
583
<div class="paragraph"><p>This example will put a top and bottom border on all tables that don’t
584
already have an explicit style attribute:</p></div>
585
<div class="listingblock">
586
<div class="content">
587
<pre><tt>[tabledef-default]
588
style=topbot
589
topbot-style=frame="topbot"</tt></pre>
590
</div></div>
591
<div class="paragraph"><p>Alternatively you can set the configuration entries from inside your
592
document, the above examples are equivalent to:</p></div>
593
<div class="listingblock">
594
<div class="content">
595
<pre><tt>:listdef-labeled.style: horizontal
596
:listdef-labeled2.style: horizontal
597
598
:tabledef-default.topbot-style: frame="topbot"
599
:tabledef-default.style: topbot</tt></pre>
600
</div></div>
601
</div>
602
<h2 id="_why_do_i_get_a_filter_non_zero_exit_code_error">20. Why do I get a filter non-zero exit code error?</h2>
603
<div class="sectionbody">
604
<div class="paragraph"><p>An error was returned when AsciiDoc tried to execute an external
605
filter command. The most common reason for this is that the filter
606
command could not be found by the command shell. To figure out what
607
the problem is run AsciiDoc with the <tt>--verbose</tt> option to determine
608
the command that is failing and then try to run the command manually
609
from the command-line.</p></div>
610
</div>
611
<h2 id="_are_there_any_docbook_viewers">21. Are there any DocBook viewers?</h2>
612
<div class="sectionbody">
613
<div class="paragraph"><p><a href="http://live.gnome.org/Yelp">Yelp</a>, the GNOME help viewer, does a
614
creditable job of displaying DocBook XML files directly. Just
615
run it from the command-line, for example:</p></div>
616
<div class="literalblock">
617
<div class="content">
618
<pre><tt>$ yelp file://home/srackham/tmp/book.xml</tt></pre>
619
</div></div>
620
<div class="paragraph"><p>Note that you have to supply the full path name in URI format, this
621
shell script makes interactive use easier:</p></div>
622
<div class="listingblock">
623
<div class="content">
624
<pre><tt>#!/bin/sh
625
if [ -z "$1" ]; then
626
echo "usage: dbkview FILE"
627
exit 1
628
fi
629
yelp "file://$(pwd)/$1"</tt></pre>
630
</div></div>
631
<div class="paragraph"><p>This tip was submitted by Lionel Orry.</p></div>
632
</div>
633
<h2 id="_can_you_create_odf_documents_using_asciidoc">22. Can you create ODF documents using AsciiDoc?</h2>
634
<div class="sectionbody">
635
<div class="paragraph"><p>The easiest and highest fidelity method I’ve seen is to generate
636
HTML from AsciiDoc then paste it from your browser (we use Firefox)
637
into OpenOffice Writer.</p></div>
638
<div class="ulist"><ul>
639
<li>
640
<p>
641
I found that that there is better fidelity pasting HTML generated by
642
the <em>html4</em> backend instead of the default <em>xhtml11</em> backend.
643
</p>
644
</li>
645
<li>
646
<p>
647
Don’t paste AsciiDoc tables of contents, OpenOffice Writer (I was
648
using version 2.3) hangs when saving. This may be something to do
649
with the embedded JavaScript but I haven’t looked closely at it, I
650
may even be wrong about this.
651
</p>
652
</li>
653
</ul></div>
654
<div class="paragraph"><p>This tip was contributed by Bernard Amade.</p></div>
655
</div>
656
<h2 id="_how_can_i_supress_cell_separators_in_included_table_data_files">23. How can I supress cell separators in included table data files?</h2>
657
<div class="sectionbody">
658
<div class="paragraph"><p>Use the <tt>{include:}</tt> system attribute instead of the <tt>include::[]</tt>
659
macro (the former is not expanded until after the table data has been
660
parsed into cells, whereas the latter is included before the table is
661
processed.</p></div>
662
</div>
663
<h2 id="_how_can_i_preserve_paragraph_line_boundaries">24. How can I preserve paragraph line boundaries?</h2>
664
<div class="sectionbody">
665
<div class="paragraph"><p>Apply the The <em>verse</em> paragraph style, the rendered text preserves
666
line boundaries and is useful for lyrics and poems. For example:</p></div>
667
<div class="listingblock">
668
<div class="content">
669
<pre><tt>[verse]
670
Consul *necessitatibus* per id,
671
consetetur, eu pro everti postulant
672
homero verear ea mea, qui.</tt></pre>
673
</div></div>
674
<div class="paragraph"><p>Alternatively, if you are generating PDF files files, you can use line
675
breaks. For example:</p></div>
676
<div class="listingblock">
677
<div class="content">
678
<pre><tt>Consul *necessitatibus* per id, +
679
consetetur, eu pro everti postulant +
680
homero verear ea mea, qui.</tt></pre>
681
</div></div>
682
</div>
683
<h2 id="_how_can_i_include_non_breaking_space_characters">25. How can I include non-breaking space characters?</h2>
684
<div class="sectionbody">
685
<div class="paragraph"><p>Use the non-breaking space character entity reference <tt>&#160;</tt> (see
686
the next question). You could also use the predefined <tt>{nbsp}</tt>
687
attribute reference.</p></div>
688
</div>
689
<h2 id="_can_i_include_html_and_xml_character_entity_references_in_my_document">26. Can I include HTML and XML character entity references in my document?</h2>
690
<div class="sectionbody">
691
<div class="paragraph"><p>Yes, just enter the reference in your document. For example <tt>&#946;</tt>
692
will print a Greek small beta character β</p></div>
693
</div>
694
<h2 id="X1">27. How do I include spaces in URLs?</h2>
695
<div class="sectionbody">
696
<div class="paragraph"><p>URL inline macro targets (addresses) cannot contain white space
697
characters. If you need spaces encode them as <tt>%20</tt>. For example:</p></div>
698
<div class="literalblock">
699
<div class="content">
700
<pre><tt>image:large%20image.png[]
701
http://www.foo.bar.com/an%20example%20document.html</tt></pre>
702
</div></div>
703
</div>
704
<h2 id="_how_can_i_get_asciidoc_to_assign_the_correct_docbook_language_attribute">28. How can I get AsciiDoc to assign the correct DocBook language attribute?</h2>
705
<div class="sectionbody">
706
<div class="paragraph"><p>Set the AsciiDoc <em>lang</em> attribute to the appropriate language code.
707
For example:</p></div>
708
<div class="literalblock">
709
<div class="content">
710
<pre><tt>$ a2x -a lang=es doc/article.txt</tt></pre>
711
</div></div>
712
<div class="paragraph"><p>This will ensure that downstream DocBook processing will generate the
713
correct language specific document headings (things like table of
714
contents, revision history, figure and table captions, admonition
715
captions).</p></div>
716
</div>
717
<h2 id="_why_does_asciidoc_give_me_a_8220_malformed_author_8221_error">29. Why does AsciiDoc give me a “malformed author” error?</h2>
718
<div class="sectionbody">
719
<div class="paragraph"><p>This is normally because there are more than three names (up to three
720
are expected: first name, middle name and last name). For example,
721
this author line would result in an error:</p></div>
722
<div class="literalblock">
723
<div class="content">
724
<pre><tt>Vincent Willem van Gogh</tt></pre>
725
</div></div>
726
<div class="paragraph"><p>You can enter multi-word first, middle and last names in the author
727
line using the underscore as a word separator. For example:</p></div>
728
<div class="literalblock">
729
<div class="content">
730
<pre><tt>Vincent Willem van_Gogh</tt></pre>
731
</div></div>
732
<div class="paragraph"><p>You could also resolve the problem by replacing the author line with
733
explicit attribute entries:</p></div>
734
<div class="listingblock">
735
<div class="content">
736
<pre><tt>:First name: Vincent
737
:Middle name: Willem
738
:Last name: Van Gogh</tt></pre>
739
</div></div>
740
</div>
741
<h2 id="_how_can_i_turn_off_table_and_image_title_numbering">30. How can I turn off table and image title numbering?</h2>
742
<div class="sectionbody">
743
<div class="paragraph"><p>For HTML outputs set the <em>caption</em> attribute to an empty string,
744
either globally:</p></div>
745
<div class="listingblock">
746
<div class="content">
747
<pre><tt>:caption:</tt></pre>
748
</div></div>
749
<div class="paragraph"><p>or on an element by element basis, for example:</p></div>
750
<div class="listingblock">
751
<div class="content">
752
<pre><tt>.Tiger
753
[caption=""]
754
image::images/tiger.png[]</tt></pre>
755
</div></div>
756
</div>
757
<h2 id="_how_can_i_assign_multiple_author_names">31. How can I assign multiple author names?</h2>
758
<div class="sectionbody">
759
<div class="paragraph"><p>A quick way to do this is put both authors in a single first name, for
760
example:</p></div>
761
<div class="listingblock">
762
<div class="content">
763
<pre><tt>My Document
764
===========
765
:Author: Bill_and_Ben_the_Flowerpot_Men
766
:Author Initials: BB & BC</tt></pre>
767
</div></div>
768
<div class="paragraph"><p><tt>asciidoc(1)</tt> replaces the underscores with spaces.</p></div>
769
<div class="paragraph"><p>If you are generating DocBook then a more flexible approach is to
770
create a <em>docinfo</em> file containing a DocBook <em>authorgroup</em> element
771
(search the <em>User Guide</em> for <em>docinfo</em> for more details).</p></div>
772
</div>
773
<h2 id="_how_can_i_escape_a_list">32. How can I escape a list?</h2>
774
<div class="sectionbody">
775
<div class="paragraph"><p>Here’s how to handle situations where the first line of a paragraph is
776
mistaken for a list item.</p></div>
777
<h3 id="_numbered_and_bulleted_lists">32.1. Numbered and bulleted lists</h3><div style="clear:left"></div>
778
<div class="paragraph"><p>Precede the bullet or index of the first list item with an <tt>{empty}</tt>
779
attribute, for example:</p></div>
780
<div class="literalblock">
781
<div class="content">
782
<pre><tt>{empty}- Qui in magna commodo est labitur dolorum an. Est ne magna
783
primis adolescens.</tt></pre>
784
</div></div>
785
<div class="paragraph"><p>The predefined <tt>{empty}</tt> attribute is replaced by an empty string and
786
ensures the first line is not mistaken for a bulleted list item.</p></div>
787
<h3 id="_labeled_lists">32.2. Labeled lists</h3><div style="clear:left"></div>
788
<div class="paragraph"><p>Two colons or semicolons in a paragraph may be confused with a labeled
789
list entry. Use the predefined <tt>{two-colons}</tt> and <tt>{two-semicolons}</tt>
790
attributes to suppress this behavior, for example:</p></div>
791
<div class="literalblock">
792
<div class="content">
793
<pre><tt>Qui in magna commodo{two-colons} est labitur dolorum an. Est ne
794
magna primis adolescens.</tt></pre>
795
</div></div>
796
<div class="paragraph"><p>Will be rendered as:</p></div>
797
<div class="paragraph"><p>Qui in magna commodo:: est labitur dolorum an. Est ne
798
magna primis adolescens.</p></div>
799
</div>
800
<h2 id="_how_can_i_selectively_disable_a_quoted_text_substitution">33. How can I selectively disable a quoted text substitution?</h2>
801
<div class="sectionbody">
802
<div class="paragraph"><p>Omitting the tag name will disable quoting. For example, if you don’t
803
want superscripts or subscripts then put the following in a custom
804
configuration file or edit the global <tt>asciidoc.conf</tt> configuration
805
file:</p></div>
806
<div class="listingblock">
807
<div class="content">
808
<pre><tt>[quotes]
809
^=
810
~=</tt></pre>
811
</div></div>
812
<div class="paragraph"><p>Alternatively you can set the configuration entries from within your
813
document, the above examples are equivalent to:</p></div>
814
<div class="listingblock">
815
<div class="content">
816
<pre><tt>:quotes.^:
817
:quotes.~:</tt></pre>
818
</div></div>
819
</div>
820
<h2 id="_how_can_i_customize_the_localdate_format">34. How can I customize the {localdate} format?</h2>
821
<div class="sectionbody">
822
<div class="paragraph"><p>The default format for the <tt>{localdate}</tt> attribute is the ISO 8601
823
<tt>yyyy-mm-dd</tt> format. You can change this format by explicitly setting
824
the <tt>{localdate}</tt> attribute. For example by setting it using the
825
<tt>asciidoc(1)</tt> <tt>-a</tt> command-line option:</p></div>
826
<div class="literalblock">
827
<div class="content">
828
<pre><tt>$ asciidoc -a localdate=`date +%d-%d-%Y` mydoc.txt</tt></pre>
829
</div></div>
830
<div class="paragraph"><p>You could also set it by adding an Attribute Entry to your souce
831
document, for example:</p></div>
832
<div class="literalblock">
833
<div class="content">
834
<pre><tt>:localdate: {sys: date +%Y-%m-%d}</tt></pre>
835
</div></div>
836
</div>
837
<h2 id="_why_doesn_8217_t_asciidoc_support_strike_through_text">35. Why doesn’t AsciiDoc support strike through text?</h2>
838
<div class="sectionbody">
839
<div class="paragraph"><p>The reason it’s not in the distribution is that DocBook does not have
840
provision for strike through text and one of the AsciiDoc design goals
841
is that AsciiDoc markup should strive to be applicable to all output
842
formats.</p></div>
843
<div class="paragraph"><p>Strike through is normally used to mark deleted text — a more
844
comprehensive way to manage document revisions is to use a version
845
control system such as Subversion. You can also use the AsciiDoc
846
<em>CommentLines</em> and <em>CommentBlocks</em> to retain revised text in the
847
source document.</p></div>
848
<div class="paragraph"><p>If you really need strike through text for (X)HTML outputs then adding
849
the following to a configuration file will allow you to quote strike
850
through text with hyphen characters:</p></div>
851
<div class="listingblock">
852
<div class="content">
853
<pre><tt> ifdef::basebackend-html[]
854
855
[quotes]
856
-=strikethrough
857
858
[tags]
859
strikethrough=<del>|</del>
860
861
endif::basebackend-html[]</tt></pre>
862
</div></div>
863
</div>
864
<h2 id="_where_can_i_find_examples_of_commands_used_to_build_output_documents">36. Where can I find examples of commands used to build output documents?</h2>
865
<div class="sectionbody">
866
<div class="paragraph"><p>The User Guide has some. You could also look at <tt>./doc/main.aap</tt> in
867
the AsciiDoc distribution, it has all the commands used to build the
868
AsciiDoc documentation (even if you don’t use A-A-P you’ll still find
869
it useful).</p></div>
870
</div>
871
<h2 id="_why_have_you_used_the_docbook_lt_simpara_gt_element_instead_of_lt_para_gt">37. Why have you used the DocBook <simpara> element instead of <para>?</h2>
872
<div class="sectionbody">
873
<div class="paragraph"><p><tt><simpara></tt> is really the same as <tt><para></tt> except it can’t contain
874
block elements — this matches, more closely, the AsciiDoc paragraph
875
semantics.</p></div>
876
</div>
877
<h2 id="_how_can_i_format_text_inside_a_listing_block">38. How can I format text inside a listing block?</h2>
878
<div class="sectionbody">
879
<div class="paragraph"><p>By default only <em>specialcharacters</em> and <em>callouts</em> are substituted in
880
listing blocks; you can add quotes substitutions by explicitly setting
881
the block <em>subs</em> attribute, for example:</p></div>
882
<div class="listingblock">
883
<div class="content">
884
<pre><tt>[subs="quotes"]
885
------------------------------------------
886
$ ls *-al*
887
------------------------------------------</tt></pre>
888
</div></div>
889
<div class="paragraph"><p>The <tt>-al</tt> will rendered bold. Note that:</p></div>
890
<div class="ulist"><ul>
891
<li>
892
<p>
893
You would need to explicitly escape text you didn’t want quoted.
894
</p>
895
</li>
896
<li>
897
<p>
898
Don’t do this in source code listing blocks because it modifies the
899
source code which confuses the syntax highlighter.
900
</p>
901
</li>
902
<li>
903
<p>
904
This only works if your DocBook processor recognizes DocBook
905
<tt><emphasis></tt> elements inside <tt><screen></tt> elements.
906
</p>
907
</li>
908
</ul></div>
909
<div class="paragraph"><p>Alternative, if the lines are contiguous, you could use the <em>literal</em>
910
paragraph style:</p></div>
911
<div class="listingblock">
912
<div class="content">
913
<pre><tt>["literal",subs="quotes"]
914
$ ls *-al*</tt></pre>
915
</div></div>
916
</div>
917
<h2 id="_why_doesn_8217_t_the_include1_macro_work">39. Why doesn’t the include1::[] macro work?</h2>
918
<div class="sectionbody">
919
<div class="paragraph"><p>Internally the <tt>include1</tt> macro is translated to the <tt>include1</tt> system
920
attribute which means it must be evaluated in a region where attribute
921
substitution is enabled. <tt>include1</tt> won’t work, for example, in a
922
ListingBlock (unless attribute substitution is enabled). <tt>include1</tt>
923
is intended for use in configuration files, use the <tt>include</tt> macro
924
and set the attribute <tt>depth=1</tt> instead, for example:</p></div>
925
<div class="listingblock">
926
<div class="content">
927
<pre><tt>------------------------------------------------
928
include::blogpost_media_processing.txt[depth=1]
929
------------------------------------------------</tt></pre>
930
</div></div>
931
</div>
932
<h2 id="_how_can_i_customize_pdf_files_generated_by_dblatex">40. How can I customize PDF files generated by dblatex?</h2>
933
<div class="sectionbody">
934
<div class="paragraph"><p>There are a number of dblatex XSL parameters that can be used to
935
customize PDF output. You can set them globally in the AsciiDoc
936
<tt>./dblatex/asciidoc-dblatex.xsl</tt> configuration file or you can also
937
pass them on the <tt>a2x(1)</tt> command-line, for example:</p></div>
938
<div class="literalblock">
939
<div class="content">
940
<pre><tt>a2x -f pdf --dblatex-opts "-P latex.output.revhistory=0" doc/article.txt</tt></pre>
941
</div></div>
942
<div class="paragraph"><p>See also the <a href="http://dblatex.sourceforge.net/">dblatex</a> documentation.</p></div>
943
</div>
944
<h2 id="_how_can_i_make_the_mailto_macro_work_with_multiple_email_addresses">41. How can I make the mailto macro work with multiple email addresses?</h2>
945
<div class="sectionbody">
946
<div class="paragraph"><p>For the AsciiDoc <em>mailto</em> macro to work with multiple email addresses
947
(as per RFC2368) you need to URL encode the <em>@</em> characters (replace
948
them with <em>%40</em>), if you don’t the individual addresses will be
949
rendered as separate links. You also need to <a href="#X1">replace spaces with <em>%20</em></a>.</p></div>
950
<div class="paragraph"><p>For example, the following call won’t work:</p></div>
951
<div class="literalblock">
952
<div class="content">
953
<pre><tt>mailto:jb@foobar.com,jd@acme.co.nz?subject=New foofoo release[New foofoo release]</tt></pre>
954
</div></div>
955
<div class="paragraph"><p>Use this instead:</p></div>
956
<div class="literalblock">
957
<div class="content">
958
<pre><tt>mailto:jb%40foobar.com,jd%40acme.co.nz?subject=New%20foofoo%20release[New foofoo release]</tt></pre>
959
</div></div>
960
</div>
961
<h2 id="_how_can_a_replacement_have_a_trailing_backslash">42. How can a replacement have a trailing backslash?</h2>
962
<div class="sectionbody">
963
<div class="paragraph"><p>Quote the entry name — this nonsensical example replaces <tt>x\</tt> with
964
<tt>y</tt>:</p></div>
965
<div class="literalblock">
966
<div class="content">
967
<pre><tt>"x\\"=y</tt></pre>
968
</div></div>
969
<div class="paragraph"><p>If quoting were omitted the equals character (separating the
970
entry name <tt>x</tt> from the value <tt>y</tt>) would be escaped.</p></div>
971
</div>
972
</div>
973
<div id="footnotes"><hr /></div>
974
<div id="footer">
975
<div id="footer-text">
976
Version 8.5.2<br />
977
Last updated 2009-12-07 17:24:51 NZDT
978
</div>
979
<div id="footer-badges">
980
<a href="http://validator.w3.org/check?uri=referer">
981
<img style="border:0;width:88px;height:31px"
982
src="http://www.w3.org/Icons/valid-xhtml11-blue"
983
alt="Valid XHTML 1.1" height="31" width="88" />
984
</a>
985
<a href="http://jigsaw.w3.org/css-validator/">
986
<img style="border:0;width:88px;height:31px"
987
src="http://jigsaw.w3.org/css-validator/images/vcss-blue"
988
alt="Valid CSS!" />
989
</a>
990
<a href="http://www.mozilla.org/products/firefox/">
991
<img style="border:none; width:110px; height:32px;"
992
src="http://www.spreadfirefox.com/community/images/affiliates/Buttons/110x32/safer.gif"
993
alt="Get Firefox!" />
994
</a>
995
</div>
996
</div>
997
</div>
998
</td>
999
</tr>
1000
</table>
1001
</body>
1002
</html>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1