Access denied | www.econotimes.com used Cloudflare to restrict access
Please enable cookies.
What happened?
The owner of this website (www.econotimes.com) has banned your access based on your browser's signature (40bc-ua98).2.4.1 String literals
String literals are described by the following lexical definitions:
stringliteral:
shortstring | longstring
shortstring:
"'" shortstringitem* "'" | '"' shortstringitem* '"'
longstring:
"'''" longstringitem* "'''" | '"""' longstringitem* '"""'
shortstringitem: shortstringchar | escapeseq
longstringitem:
longstringchar | escapeseq
shortstringchar: &any ASCII character except "\" or newline or the quote&
longstringchar:
&any ASCII character except "\"&
escapeseq:
"\" &any ASCII character&
In plain English: String literals can be enclosed in matching single
quotes (') or double quotes (").
They can also be
enclosed in matching groups of three single or double quotes (these
are generally referred to as triple-quoted strings).
backslash (\) character is used to escape characters that
otherwise have a special meaning, such as newline, backslash itself,
or the quote character.
String literals may optionally be prefixed
with a letter `r' or `R'; such strings are called raw strings and use
different rules for backslash escape sequences.
In triple-quoted strings,
unescaped newlines and quotes are allowed (and are retained), except
that three unescaped quotes in a row terminate the string.
``quote'' is the character used to open the string, i.e. either
Unless an `r' or `R' prefix is present, escape sequences in strings
are interpreted according to rules similar
to those used by Standard C.
The recognized escape sequences are:
for information on suggesting changes.ANSI character set and equivalent Unicode and HTML characters
Character sets
ANSI character set and equivalent Unicode and HTML characters
ANSI&| &| &| &| &| &| &| &|
The ANSI set of 217 characters, also known as Windows-1252, was the standard for the core fonts supplied with US versions of Microsoft Windows up to and including Windows 95 and Windows NT 4.
During the lifetime of those two products, Microsoft added the euro currency symbol bringing the number of characters to 218, and introduced a new core set of Pan-European fonts containing the
character set, with 652 characters.
If you use an old, non-Unicode version of Windows that was designed for a
such as Arabic, Cyrillic, Greek, Hebrew or Thai to view a document that has been typed using the ANSI character set, then characters from these languages may replace some of those in the 128–255 this problem has mostly been resolved now that Unicode is widely used, because it provides a unique numeric identifier for each character.
There were similar problems when transferring ANSI documents to DOS or Macintosh computers, because DOS and
arrange characters differently in the 128–255 range.
ANSI characters 32 to 127 correspond to those in the 7-bit ASCII character set, which forms the
Unicode character range.
Characters 160–255 correspond to those in the
Unicode character range.
Positions 128–159 in Latin-1 Supplement are reserved for controls, but most of them are used for printable characters in ANSI; the Unicode equivalents are noted in the table below.
Entries in the “Entity” column are
that can be used in HTML and should be interpreted correctly by Web browsers that support HTML 4.0.
The characters that appear in the first column of the following table are generated from Unicode numeric character references, and so they should appear correctly in any Web browser that supports
and that has suitable fonts available, regardless of the operating system.
CharacterANSI&Number&&Unicode&Number&ANSI&Hex&Unicode&Hex&HTML 4.0&EntityUnicode NameUnicode Range
' '32320x20U+0020&spaceBasic Latin
!33330x21U+0021&exclamation markBasic Latin
"34340x22U+0022&quotation markBasic Latin
#35350x23U+0023&number signBasic Latin
$36360x24U+0024&dollar signBasic Latin
%37370x25U+0025&percent signBasic Latin
&38380x26U+0026&ampersandBasic Latin
'39390x27U+0027&apostropheBasic Latin
(40400x28U+0028&left parenthesisBasic Latin
)41410x29U+0029&right parenthesisBasic Latin
*42420x2AU+002A&asteriskBasic Latin
+43430x2BU+002B&plus signBasic Latin
,44440x2CU+002C&commaBasic Latin
-45450x2DU+002D&hyphen-minusBasic Latin
.46460x2EU+002E&full stopBasic Latin
/47470x2FU+002F&solidusBasic Latin
048480x30U+0030&digit zeroBasic Latin
149490x31U+0031&digit oneBasic Latin
250500x32U+0032&digit twoBasic Latin
351510x33U+0033&digit threeBasic Latin
452520x34U+0034&digit fourBasic Latin
553530x35U+0035&digit fiveBasic Latin
654540x36U+0036&digit sixBasic Latin
755550x37U+0037&digit sevenBasic Latin
856560x38U+0038&digit eightBasic Latin
957570x39U+0039&digit nineBasic Latin
:58580x3AU+003A&colonBasic Latin
&#59;59590x3BU+003B&semicolonBasic Latin
<60600x3CU+003C&less-than signBasic Latin
=61610x3DU+003D&equals signBasic Latin
>62620x3EU+003E&greater-than signBasic Latin
?63630x3FU+003F&question markBasic Latin
@64640x40U+0040&commercial atBasic Latin
A65650x41U+0041&Latin capital letter ABasic Latin
B66660x42U+0042&Latin capital letter BBasic Latin
C67670x43U+0043&Latin capital letter CBasic Latin
D68680x44U+0044&Latin capital letter DBasic Latin
E69690x45U+0045&Latin capital letter EBasic Latin
F70700x46U+0046&Latin capital letter FBasic Latin
G71710x47U+0047&Latin capital letter GBasic Latin
H72720x48U+0048&Latin capital letter HBasic Latin
I73730x49U+0049&Latin capital letter IBasic Latin
J74740x4AU+004A&Latin capital letter JBasic Latin
K75750x4BU+004B&Latin capital letter KBasic Latin
L76760x4CU+004C&Latin capital letter LBasic Latin
M77770x4DU+004D&Latin capital letter MBasic Latin
N78780x4EU+004E&Latin capital letter NBasic Latin
O79790x4FU+004F&Latin capital letter OBasic Latin
P80800x50U+0050&Latin capital letter PBasic Latin
Q81810x51U+0051&Latin capital letter QBasic Latin
R82820x52U+0052&Latin capital letter RBasic Latin
S83830x53U+0053&Latin capital letter SBasic Latin
T84840x54U+0054&Latin capital letter TBasic Latin
U85850x55U+0055&Latin capital letter UBasic Latin
V86860x56U+0056&Latin capital letter VBasic Latin
W87870x57U+0057&Latin capital letter WBasic Latin
X88880x58U+0058&Latin capital letter XBasic Latin
Y89890x59U+0059&Latin capital letter YBasic Latin
Z90900x5AU+005A&Latin capital letter ZBasic Latin
[91910x5BU+005B&left square bracketBasic Latin
\92920x5CU+005C&reverse solidusBasic Latin
]93930x5DU+005D&right square bracketBasic Latin
^94940x5EU+005E&circumflex accentBasic Latin
_95950x5FU+005F&low lineBasic Latin
`96960x60U+0060&grave accentBasic Latin
a97970x61U+0061&Latin small letter aBasic Latin
b98980x62U+0062&Latin small letter bBasic Latin
c99990x63U+0063&Latin small letter cBasic Latin
d1001000x64U+0064&Latin small letter dBasic Latin
e1011010x65U+0065&Latin small letter eBasic Latin
f1021020x66U+0066&Latin small letter fBasic Latin
g1031030x67U+0067&Latin small letter gBasic Latin
h1041040x68U+0068&Latin small letter hBasic Latin
i1051050x69U+0069&Latin small letter iBasic Latin
j1061060x6AU+006A&Latin small letter jBasic Latin
k1071070x6BU+006B&Latin small letter kBasic Latin
l1081080x6CU+006C&Latin small letter lBasic Latin
m1091090x6DU+006D&Latin small letter mBasic Latin
n1101100x6EU+006E&Latin small letter nBasic Latin
o1111110x6FU+006F&Latin small letter oBasic Latin
p1121120x70U+0070&Latin small letter pBasic Latin
q1131130x71U+0071&Latin small letter qBasic Latin
r1141140x72U+0072&Latin small letter rBasic Latin
s1151150x73U+0073&Latin small letter sBasic Latin
t1161160x74U+0074&Latin small letter tBasic Latin
u1171170x75U+0075&Latin small letter uBasic Latin
v1181180x76U+0076&Latin small letter vBasic Latin
w1191190x77U+0077&Latin small letter wBasic Latin
x1201200x78U+0078&Latin small letter xBasic Latin
y1211210x79U+0079&Latin small letter yBasic Latin
z1221220x7AU+007A&Latin small letter zBasic Latin
{1231230x7BU+007B&left curly bracketBasic Latin
|1241240x7CU+007C&vertical lineBasic Latin
}1251250x7DU+007D&right curly bracketBasic Latin
~1261260x7EU+007E&tildeBasic Latin
&1271270x7FU+007F&(not used)&
€12883640x80U+20AC&euro signCurrency Symbols
&1291290x81U+0081&(not used)&
‚13082180x82U+201A&single low-9 quotation markGeneral Punctuation
ƒ1314020x83U+0192&Latin small letter f with hookLatin Extended-B
„13282220x84U+201E&double low-9 quotation markGeneral Punctuation
…13382300x85U+2026&horizontal ellipsisGeneral Punctuation
†13482240x86U+2020&daggerGeneral Punctuation
‡13582250x87U+2021&Ddouble daggerGeneral Punctuation
ˆ1367100x88U+02C6&modifier letter circumflex accentSpacing Modifier Letters
‰13782400x89U+2030&per mille signGeneral Punctuation
Š1383520x8AU+0160&SLatin capital letter S with caronLatin Extended-A
‹13982490x8BU+2039&single left-pointing angle quotation markGeneral Punctuation
Œ1403380x8CU+0152&OELatin capital ligature OELatin Extended-A
&1411410x8DU+008D&(not used)&
Ž1423810x8EU+017D&Latin capital letter Z with caronLatin Extended-A
&1431430x8FU+008F&(not used)&
&1441440x90U+0090&(not used)&
‘14582160x91U+2018&left single quotation markGeneral Punctuation
’14682170x92U+2019&right single quotation markGeneral Punctuation
“14782200x93U+201C&left double quotation markGeneral Punctuation
”14882210x94U+201D&right double quotation markGeneral Punctuation
•14982260x95U+2022&bulletGeneral Punctuation
–15082110x96U+2013&en dashGeneral Punctuation
—15182120x97U+2014&em dashGeneral Punctuation
˜1527320x98U+02DC&small tildeSpacing Modifier Letters
™15384820x99U+2122&trade mark signLetterlike Symbols
š1543530x9AU+0161&Latin small letter s with caronLatin Extended-A
›15582500x9BU+203A&single right-pointing angle quotation markGeneral Punctuation
œ1563390x9CU+0153&Latin small ligature oeLatin Extended-A
&1571570x9DU+009D&(not used)&
ž1583820x9EU+017E&Latin small letter z with caronLatin Extended-A
Ÿ1593760x9FU+0178&YLatin capital letter Y with diaeresisLatin Extended-A
 1601600xA0U+00A0&no-break spaceLatin-1 Supplement
¡1611610xA1U+00A1&inverted exclamation markLatin-1 Supplement
¢1621620xA2U+00A2&cent signLatin-1 Supplement
£1631630xA3U+00A3&pound signLatin-1 Supplement
¤1641640xA4U+00A4&currency signLatin-1 Supplement
¥1651650xA5U+00A5&yen signLatin-1 Supplement
¦1661660xA6U+00A6&broken barLatin-1 Supplement
§1671670xA7U+00A7&section signLatin-1 Supplement
¨1681680xA8U+00A8&diaeresisLatin-1 Supplement
©1691690xA9U+00A9&copyright signLatin-1 Supplement
ª1701700xAAU+00AA&feminine ordinal indicatorLatin-1 Supplement
«1711710xABU+00AB&left-pointing double angle quotation markLatin-1 Supplement
¬1721720xACU+00AC&not signLatin-1 Supplement
­1731730xADU+00AD&soft hyphenLatin-1 Supplement
®1741740xAEU+00AE&registered signLatin-1 Supplement
¯1751750xAFU+00AF&macronLatin-1 Supplement
°1761760xB0U+00B0&degree signLatin-1 Supplement
±1771770xB1U+00B1&plus-minus signLatin-1 Supplement
²1781780xB2U+00B2²superscript twoLatin-1 Supplement
³1791790xB3U+00B3³superscript threeLatin-1 Supplement
´1801800xB4U+00B4&acute accentLatin-1 Supplement
µ1811810xB5U+00B5&micro signLatin-1 Supplement
¶1821820xB6U+00B6&pilcrow signLatin-1 Supplement
·1831830xB7U+00B7&middle dotLatin-1 Supplement
¸1841840xB8U+00B8&cedillaLatin-1 Supplement
¹1851850xB9U+00B9¹superscript oneLatin-1 Supplement
º1861860xBAU+00BA&masculine ordinal indicatorLatin-1 Supplement
»1871870xBBU+00BB&right-pointing double angle quotation markLatin-1 Supplement
¼1881880xBCU+00BC¼vulgar fraction one quarterLatin-1 Supplement
½1891890xBDU+00BD½vulgar fraction one halfLatin-1 Supplement
¾1901900xBEU+00BE¾vulgar fraction three quartersLatin-1 Supplement
¿1911910xBFU+00BF&inverted question markLatin-1 Supplement
À1921920xC0U+00C0&ALatin capital letter A with graveLatin-1 Supplement
Á1931930xC1U+00C1&ALatin capital letter A with acuteLatin-1 Supplement
Â1941940xC2U+00C2&ALatin capital letter A with circumflexLatin-1 Supplement
Ã1951950xC3U+00C3&ALatin capital letter A with tildeLatin-1 Supplement
Ä1961960xC4U+00C4&ALatin capital letter A with diaeresisLatin-1 Supplement
Å1971970xC5U+00C5&ALatin capital letter A with ring aboveLatin-1 Supplement
Æ1981980xC6U+00C6&AELatin capital letter AELatin-1 Supplement
Ç1991990xC7U+00C7&CLatin capital letter C with cedillaLatin-1 Supplement
È2002000xC8U+00C8&ELatin capital letter E with graveLatin-1 Supplement
É2012010xC9U+00C9&ELatin capital letter E with acuteLatin-1 Supplement
Ê2022020xCAU+00CA&ELatin capital letter E with circumflexLatin-1 Supplement
Ë2032030xCBU+00CB&ELatin capital letter E with diaeresisLatin-1 Supplement
Ì2042040xCCU+00CC&ILatin capital letter I with graveLatin-1 Supplement
Í2052050xCDU+00CD&ILatin capital letter I with acuteLatin-1 Supplement
Î2062060xCEU+00CE&ILatin capital letter I with circumflexLatin-1 Supplement
Ï2072070xCFU+00CF&ILatin capital letter I with diaeresisLatin-1 Supplement
Ð2082080xD0U+00D0ÐLatin capital letter EthLatin-1 Supplement
Ñ2092090xD1U+00D1&NLatin capital letter N with tildeLatin-1 Supplement
Ò2102100xD2U+00D2&OLatin capital letter O with graveLatin-1 Supplement
Ó2112110xD3U+00D3&OLatin capital letter O with acuteLatin-1 Supplement
Ô2122120xD4U+00D4&OLatin capital letter O with circumflexLatin-1 Supplement
Õ2132130xD5U+00D5&OLatin capital letter O with tildeLatin-1 Supplement
Ö2142140xD6U+00D6&OLatin capital letter O with diaeresisLatin-1 Supplement
×2152150xD7U+00D7&multiplication signLatin-1 Supplement
Ø2162160xD8U+00D8&OLatin capital letter O with strokeLatin-1 Supplement
Ù2172170xD9U+00D9&ULatin capital letter U with graveLatin-1 Supplement
Ú2182180xDAU+00DA&ULatin capital letter U with acuteLatin-1 Supplement
Û2192190xDBU+00DB&ULatin capital letter U with circumflexLatin-1 Supplement
Ü2202200xDCU+00DC&ULatin capital letter U with diaeresisLatin-1 Supplement
Ý2212210xDDU+00DD&YLatin capital letter Y with acuteLatin-1 Supplement
Þ2222220xDEU+00DEÞLatin capital letter ThornLatin-1 Supplement
ß2232230xDFU+00DF&Latin small letter sharp sLatin-1 Supplement
à2242240xE0U+00E0&Latin small letter a with graveLatin-1 Supplement
á2252250xE1U+00E1&Latin small letter a with acuteLatin-1 Supplement
â2262260xE2U+00E2&Latin small letter a with circumflexLatin-1 Supplement
ã2272270xE3U+00E3&Latin small letter a with tildeLatin-1 Supplement
ä2282280xE4U+00E4&Latin small letter a with diaeresisLatin-1 Supplement
å2292290xE5U+00E5&Latin small letter a with ring aboveLatin-1 Supplement
æ2302300xE6U+00E6&Latin small letter aeLatin-1 Supplement
ç2312310xE7U+00E7&Latin small letter c with cedillaLatin-1 Supplement
è2322320xE8U+00E8&Latin small letter e with graveLatin-1 Supplement
é2332330xE9U+00E9&Latin small letter e with acuteLatin-1 Supplement
ê2342340xEAU+00EA&Latin small letter e with circumflexLatin-1 Supplement
ë2352350xEBU+00EB&Latin small letter e with diaeresisLatin-1 Supplement
ì2362360xECU+00EC&Latin small letter i with graveLatin-1 Supplement
í2372370xEDU+00ED&Latin small letter i with acuteLatin-1 Supplement
î2382380xEEU+00EE&Latin small letter i with circumflexLatin-1 Supplement
ï2392390xEFU+00EF&Latin small letter i with diaeresisLatin-1 Supplement
ð2402400xF0U+00F0&Latin small letter ethLatin-1 Supplement
ñ2412410xF1U+00F1&Latin small letter n with tildeLatin-1 Supplement
ò2422420xF2U+00F2&Latin small letter o with graveLatin-1 Supplement
ó2432430xF3U+00F3&Latin small letter o with acuteLatin-1 Supplement
ô2442440xF4U+00F4&Latin small letter o with circumflexLatin-1 Supplement
õ2452450xF5U+00F5&Latin small letter o with tildeLatin-1 Supplement
ö2462460xF6U+00F6&Latin small letter o with diaeresisLatin-1 Supplement
÷2472470xF7U+00F7&division signLatin-1 Supplement
ø2482480xF8U+00F8&Latin small letter o with strokeLatin-1 Supplement
ù2492490xF9U+00F9&Latin small letter u with graveLatin-1 Supplement
ú2502500xFAU+00FA&Latin small letter u with acuteLatin-1 Supplement
û2512510xFBU+00FB&Latin small letter
with circumflexLatin-1 Supplement
ü2522520xFCU+00FC&Latin small letter u with diaeresisLatin-1 Supplement
ý2532530xFDU+00FD&Latin small letter y with acuteLatin-1 Supplement
þ2542540xFEU+00FE&Latin small letter thornLatin-1 Supplement
ÿ2552550xFFU+00FF&Latin small letter y with diaeresisLatin-1 Supplement
If you use old, pre-Unicode Arabic, Greek, Hebrew, Russian or Thai versions of Microsoft Windows to view a file that uses Latin script and includes accented characters, then the accented characters may be replaced or omitted.
For example:
US Windows
Russian Windows
Thai Windows
This happens because the characters for these non-Latin scripts are coded to the same numbers as the accented Latin characters in the ANSI this problem has largely been resolved now that
has become widely used, because it provides a unique numeric identifier for each character.
Copyright (C)
Created 15th March 1999 – Last modified 22nd November 2012AsciiDoc Frequently Asked Questions
Text based document generation
JavaScript must be enabled in your browser to display the table of contents.
New FAQs are appended to the bottom of this document.
1. How do you handle spaces in included file names?
Spaces are not allowed in macro targets so this include macro will not
be processed:
include::my document.txt[]
The work-around is to replace the spaces with the {sp} (space
character) attribute, for example:
include::my{sp}document.txt[]
2. How do I number all paragraphs?
Some documents such as specifications and legalese require all
paragraphs to be sequentially numbered through the document, and to be
able to reference these numbers.
This can be achieved by using the DocBook toolchain but numbering the
paragraphs with AsciiDoc using a custom config file containing the
following (see
for ways to include such a file):
[paragraph]
&formalpara{id? id="{id}"}{role? role="{role}"}{id? xreflabel="{paracounter}"}&&title&{title}&/title&&para&
{title%}&simpara{id? id="{id}"}{role? role="{role}"}{id? xreflabel="{paracounter}"}&
{paracounter} |
{title%}&/simpara&
{title#}&/para&&/formalpara&
{counter2:paracounter}
References to the paragraphs operate in the normal way, you label the
paragraph:
[[some_label_you_understand]]
paragraph contents
and reference it in the normal manner:
&&some_label_you_understand&&
The text of the reference will be the paragraph number.
For this to work for HTML you have to generate it via the DocBook
toolchain.
DocBook is a content and structure markup language, therefore
AsciiDoc generated DocBook markup is also limited to content and
structure.
Layout and formatting definition is specific to the
DocBook toolchain.
The dblatex toolchain can be configured by setting parameters defined
more complex styling by custom Latex stylesheets described at
Similarly FOP can be configured by parameters described at
and with custom xsl
stylesheets generating formatting objects as described at
4. How can I include embedded fonts in an EPUB document?
This is a two step process:
Declare the font files and their use in your document’s CSS
stylesheet. For example:
@font-face {
font-family : LiberationSerif-R
font-weight :
font-style:
src : url(LiberationSerif-Regular.ttf);
font-family: LiberationSerif-Regular,
Declare the font file as resource when you use a2x(1) to
compile the EPUB. For example:
a2x -f epub -d book --epubcheck --stylesheet epubtest.css --resource .ttf=application/x-font-ttf --resource LiberationSerif-Regular.ttf epubtest.txt
Requires AsciiDoc 8.6.5 or better.
The True Type Font mimetype had to be declared explicitly with the
--resource .ttf=application/x-font-ttf option because it wasn’t
registered on my Linux system.
In the above example the font file is in the same directory as the
AsciiDoc source file and is installed to the same relative location
in the EPUB archive OEBPS directory — if your font file resides in
a different location you’ll need to adjust the --resource option
accordingly (see the RESOURCES section in the a2x(1) man page
for details).
The URL value of the CSS src property is set to the destination
font file relative to the CSS file.
The --resource option allows you to inject any file (not just font
files) into the EPUB output document.
Using the CSS @font-face rule is a complex subject and is outside
the scope of this FAQ.
Many EPUB readers do not process embedded fonts.
5. What’s the difference between + quoted text and ` quoted monospaced text?
+ (plus) quoted text is implemented as an AsciiDoc quotes whereas
` (grave accent or backtick) quoted text is implemented as an
AsciiDoc inline literal passthrough macro. The semantics are
different:
Inline passthrough macros are processed before any other inline
substitutions e.g. all of the following line will be processed as a
single inline passthrough and rendered as monospaced text (which is
not the intended result):
`single quoted text' and `monospaced quoted text`
This line works as expected:
`single quoted text' and +monospaced quoted text+
Backtick quoted text is rendered literally i.e. no substitutions
are performed on the enclosed text.
Here are some examples that
would have to be escaped if plus quoting were used ():
The `++i` and `++j` auto-increments.
Paths `~/.vim` and `~/docs`.
The `__init__` method.
The `{id}` attribute.
6. Why is the generated HTML title element text invalid?
Probably because your document title contains formatting that has
generated HTML title markup. You can resolve this by explicitly
defining the title attribute in your document’s header.
AsciiDoc is backend agnostic, the asciidoc command has no knowledge
of the syntax or structure of the backend format that it generates.
Output document validation (syntactic and structural) should be
performed separately by external validation tools. For example,
AsciiDoc’s a2x toolchain command automatically performs validation
checks using xmllint.
8. The AsciiDoc toclevels attribute does not work with DocBook outputs, why?
DocBook has no provision for specifying table of contents levels but
you can set the TOC level further down the toolchain by passing the
DocBook XSL Stylesheets
parameter to dblatex (using the --param option) or xsltproc
(using the --stringparam option).
For example to show only chapter
titles in the TOC of a book document set toc.section.depth to 0.
Increment the toc.section.depth value to show more sub-section
titles. If you are using a2x you can set the options in the source
file, for example:
// a2x: --xsltproc-opts "--stringparam toc.section.depth 0"
// a2x: --dblatex-opts "--param toc.section.depth=0"
If the document is of type article use the value 1 to show only
top level section titles in the TOC, use the value 2 for two levels
9. How can I include chapter and section tables of contents?
DocBook outputs processed by DocBook XSL Stylesheets (either manually
or via a2x) can generate additional separate section and chapter
tables of contents using combinations of the
Here are some examples using combinations of the
generate.section.toc.level and toc.section.depth DocBook XSL
Stylesheets parameters:
generate.section.toc.level
toc.section.depth
Single level book chapter TOCs or article section TOCs
Article section TOCs with two levels
Book chapter TOCs with two levels
10. How can I customize the appearance of XHTML and EPUB documents generated by a2x?
You can customize the appearance of an EPUB document with CSS.
on the AsciiDoc website.
11. DocBook has many elements for document meta-data — how can I use them from AsciiDoc?
The docinfo, docinfo1 and docinfo2 attributes allow you include
containing DocBook
XML into the header of the output file.
12. Do element titles automatically generate link captions?
If you go the DocBook route then yes — just omit the caption from the
AsciiDoc xref (&&...&&) macro. Both dblatex and DocBook XSL will
use the target element’s title text. Examples:
Section One
-----------
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas
ultrices justo porttitor augue. Vestibulum pretium. Donec porta
See also &&X3&& (this link displays the text 'A titled paragraph').
[id="X2",reftext="2nd section"]
Section Two
-----------
See also &&X1&& (this link displays the text 'Section One').
.A titled paragraph
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
See also &&X2&& (this link displays the text '2nd section').
The AsciiDoc reftext attribute has been used to explicitly set the
link text to 2nd section for Section Two.
13. Can I define my own table styles?
In addition to the built-in styles you can define your own. This
(simplified) example for HTML backends defines a table style called
red which sets the background cell color to red. First put the
definition in a configuration file:
[tabledef-default]
red-style=tags="red"
[tabletags-red]
bodydata=&td style="background-color:"&|&/td&
Now you can use the style name to style cells or columns (in this
example we use an unambiguous shortened abbreviation r):
|==================================
|Normal cell
r|Red cell
|==================================
Both block and inline
displayed on the output if the showcomments attribute is defined.
:showcomments:
// A block comment line.
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
// An inline comment line.
adolescens.
Is rendered as:
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.
are never displayed.
15. What is the preferred file name extension for AsciiDoc files?
is preferred, but it’s just a convention and it’s not enforced by the
AsciiDoc source files are human readable
files which is
what the .txt extension is for. All text editors recognize and open
files with a .txt extension. The .txt extension is universally
recognized and unambiguous — you are not left asking questions like
“What on earth is this file with the funny extension?”, “How do I
open it?” and “Is it safe to open?”.
16. How can I generate numbered bibliographic entries?
If your outputs are DocBook generated then adding the following inline
macro to a custom configuration file will result in auto-incrementing
bibliography entry numbers (instead of displaying the bibliographic
identifiers):
[anchor3-inlinemacro]
&anchor id="{1}" xreflabel="[{counter:bibliography1}]"/&[{counter:bibliography2}]
This FAQ submitted by Bela Hausmann.
A line of four or more dashes will be mistaken for the ListingBlock
terminator, one way round this problem is to use a LiteralBlock styled
as a listing block. For example:
...........................
Lorum ipsum
-----------
...........................
18. How can I customize PDF files generated by dblatex?
There are a number of dblatex XSL parameters that can be used to
customize PDF output. You can set them globally in the AsciiDoc
./dblatex/asciidoc-dblatex.xsl configuration file or you can also
pass them on the a2x(1) command-line. Here are some examples:
parameter is used to suppress the revision history:
a2x -f pdf --dblatex-opts "-P latex.output.revhistory=0" doc/article.txt
parameter is used to include the cover page and document body (i.e. excludes
table of contents and index), the
parameter is used to exclude the cover page logo:
a2x -f pdf --dblatex-opts " -P doc.layout=\"coverpage mainmatter\" -P doc.publisher.show=0" doc/article.txt
See also the
19. How can I add lists of figures and tables to PDFs created by dblatex?
 — you can set it using the dblatex --param command-line
option, for example:
a2x --dblatex-opts="--param=doc.lot.show=figure,table" doc/article.txt
20. How can I stop the document title being displayed?
You could simply omit the document title, but this will result in a
blank title element in HTML outputs. If you want the HTML title
element to contain the document title then define the notitle
attribute (this will just suppress displaying the title), for example:
My document title
=================
:no title:
21. Why am I having trouble getting nested macros to work?
The following example expands the image inline macro, but the
expansion contains double-quote characters which confuses the ensuing
footnoteref macro expansion:
footnoteref:["F1","A footnote, with an image image:smallnew.png[]"]
The solution is to use unquoted attribute values, replacing embedded
commas with the comma character entity (,):
footnoteref:[F1,A footnote, with an image image:smallnew.png[]]
Similarly, you can embed double-quote characters in unquoted attribute
values using the " character entity.
22. Why am I getting DocBook validation errors?
Not all valid AsciiDoc source generates valid DocBook, for example
special sections (abstract, preface, colophon, dedication,
bibliography, glossary, appendix, index, synopsis) have different
DocBook schema’s to normal document sections. For example, a paragraph
is illegal in a bibliography.
Don’t forget if your document is a book you need to specify the
asciidoc -d book command option, if you don’t an article DocBook
document will be generated, possibly containing book specific
sections, resulting in validation errors.
23. How can I disable special section titles?
For example, you want to use References as a normal section name but
AsciiDoc is auto-magically generating a DocBook bibliography
section. All you need to do is explicitly specify the section template
name, for example:
References
----------
24. How can I insert XML processing instructions into output documents?
Use an inline or block passthrough macros. This example inserts
&?dblatex bgcolor="#cceeff"?& into the DocBook output generated by
pass::[&?dblatex bgcolor="#cceeff"?&]
XML processing instructions are specific to the application that
processes the XML (the previous dblatex processing instruction is
recognized by dblatex(1) when it processes the DocBook XML generated
by Asciidoc).
25. How do I prevent double-quoted text being mistaken for an inline literal?
Mixing doubled-quoted text with inline literal passthroughs can
produce undesired results, for example, all of the following line is
interpreted as an inline literal passthrough:
``XXX'' `YYY`
In this case the solution is to use monospace quoting instead of the
inline literal:
``XXX'' +YYY+
Use the pass:[] macro if it’s necessary to suppress
substitutions in the monospaced text, for example:
``XXX'' +pass:[don't `quote` me]+
26. How can I generate a single HTML document file containing images and CSS styles?
With the advent of Internet Explorer 8 all major web browsers now
support the
embedded images. The AsciiDoc xhtml11 and html5 backends supports
the data URI scheme for embedded images and by default it embeds the
CSS stylesheet. For example the following command will generate a
single article.html file containing embedded images, admonition
icons and the CSS stylesheet:
asciidoc -a data-uri -a icons article.txt
AsciiDoc has a built-in trace mechanism which is controlled by the
trace there is also the --verbose command-line option.
These features are detailed in
28. One-liner ifdef::[]'s are disproportionately verbose can they shortened?
This is the response to a question posted on the AsciiDoc discussion
list, it illustrates a number of useful techniques. The question arose
because the source highlight filter language identifier for the C++
language is c++ when generating PDFs via dblatex (LaTeX listings
package) or cpp when generating HTML (GNU source-highlight).
Using straight ifdef::[] block macros we have:
ifdef::basebackend-docbook[]
[source,c++]
endif::basebackend-docbook[]
ifdef::basebackend-html[]
[source,cpp]
endif::basebackend-html[]
-----------------------------------------
class FooParser {
virtual void startDocument() = 0;
virtual void endDocument() = 0;
-----------------------------------------
This can be shortened using the short form of the ifdef::[] macro:
ifdef::basebackend-docbook[[source,c++]]
ifdef::basebackend-html[[source,cpp]]
-----------------------------------------
class FooParser {
virtual void startDocument() = 0;
virtual void endDocument() = 0;
-----------------------------------------
Using a conditional attribute instead of the ifdef::[] macro is even
[source,{basebackend@docbook:c++:cpp}]
-----------------------------------------
class FooParser {
virtual void startDocument() = 0;
virtual void endDocument() = 0;
-----------------------------------------
If you have a number of listings it makes sense to factor the
conditional attribute to a normal attribute:
:cpp: {basebackend@docbook:c++:cpp}
[source,{cpp}]
-----------------------------------------
class FooParser {
virtual void startDocument() = 0;
virtual void endDocument() = 0;
-----------------------------------------
Even shorter, set the default source highlight filter language
attribute so you don’t have to specify it every time:
:language: {basebackend@docbook:c++:cpp}
-----------------------------------------
class FooParser {
virtual void startDocument() = 0;
virtual void endDocument() = 0;
-----------------------------------------
29. Some of my inline passthroughs are not passed through, why?
Most likely the passthrough encloses another passthrough with a higher
precedence. For example trying to render this pass:[] with this
`pass:[]` results in a blank string because the pass:[]
passthrough evaluates first, instead use monospaced quoting
and escape
the passthrough i.e.
+\pass:[]+
30. How can I place an anchor (link target) on a list item?
You can’t use a BlockId block element inside a list but you can use
the syntactically identical anchor inline macro. For example:
one:: Item one.
[[X2]]two:: Item two.
three:: Item three.
This will not work:
one:: Item one.
two:: Item two.
three:: Item three.
31. How can I stop lists from nesting?
If you place two lists with different syntax hard up against each
other then the second list will be nested in the first. If you don’t
want the second list to be nested separate them with a comment line
block macro. For example:
1. List 1.
2. List 1.
a. List 2.
b. List 2.
32. Is it possible to include charts in AsciiDoc documents?
There are a number of programs available that generate presentation
charts from textual specification, for example
is a library for writing chart
scripts in Python. Here’s an example from the Pychart documentation:
barchart.py
# Example bar chart (from Pychart documentation http://home.gna.org/pychart/).
from pychart import *
theme.get_options()
data = [(10, 20, 30, 5), (20, 65, 33, 5), (30, 55, 30, 5), (40, 45, 51, 7),
(50, 25, 27, 3), (60, 75, 30, 5), (70, 80, 42, 5), (80, 62, 32, 5),
(90, 42, 39, 5), (100, 32, 39, 4)]
# The attribute y_coord=... tells that the Y axis values
# should be taken from samples.
# In this example, Y values will be [40,50,60,70,80].
ar = area.T(y_coord = category_coord.T(data[3:8], 0),
x_grid_style=line_style.gray50_dash1,
x_grid_interval=20, x_range = (0,100),
x_axis=axis.X(label="X label"),
y_axis=axis.Y(label="Y label"),
bg_style = fill_style.gray90,
border_line_style = line_style.default,
legend = legend.T(loc=(80,10)))
# Below call sets the default attributes for all bar plots.
chart_object.set_defaults(bar_plot.T, direction="horizontal", data=data)
# Attribute cluster=(0,3) tells that you are going to draw three bar
# plots side by side.
The plot labeled "foo" will the leftmost (i.e.,
# 0th out of 3).
Attribute hcol tells the column from which to
# retrive sample values from.
It defaults to one.
ar.add_plot(bar_plot.T(label="foo", cluster=(0,3)))
ar.add_plot(bar_plot.T(label="bar", hcol=2, cluster=(1,3)))
ar.add_plot(bar_plot.T(label="baz", hcol=3, cluster=(2,3)))
To execute the script and include the generated chart image in your
document add the following lines to the AsciiDoc source:
// Generate chart image file.
sys2::[python "{indir}/barchart.py" --format=png --output="{outdir}/barchart.png" --scale=2]
// Display chart image file.
image::barchart.png[]
The barchart.py script is located in the same directory as the
AsciiDoc source file ({indir}).
The generated chart image file (barchart.png) is written to the
same directory as the output file ({outdir}).
33. How can I render indented paragraphs?
Styling is backend dependent:
Create an indented paragraph style (xhtml11 and html5 backends)
Define an indented paragraph style, for example, by putting this
in a custom configuration file:
[paradef-default]
indented-style=template="indentedparagraph"
[indentedparagraph]
&div class="paragraph"{id? id="{id}"} style="text-indent:3"&{title?&div class="title"&{title}&/div&}&p&
&/p&&/div&
Now apply the indented style to normal paragraphs, for example:
[indented]
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas
ultrices justo porttitor augue. Vestibulum pretium. Donec porta
vestibulum mi. Aliquam pede. Aenean lobortis lorem et lacus. Sed
lacinia. Vivamus at lectus.
Use the role attribute (xhtml11 and html5 backends)
Add the following line to custom stylesheet:
div.paragraph.indented p {text-indent: 3}
Apply the role attribute to indented paragraphs, for example:
[role="indented"]
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas
ultrices justo porttitor augue. Vestibulum pretium. Donec porta
vestibulum mi. Aliquam pede. Aenean lobortis lorem et lacus. Sed
lacinia. Vivamus at lectus.
Include the custom stylesheet by setting the stylesheet attribute
(either from the command-line or with an attribute entry in the
document header).
Use the role attribute (docbook backend)
Add the following line to the distributed docbook-xsl.css
stylesheet or include it in a custom stylesheet:
p.indented {text-indent: 3}
Apply the role attribute to indented paragraphs, for example:
[role="indented"]
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas
ultrices justo porttitor augue. Vestibulum pretium. Donec porta
vestibulum mi. Aliquam pede. Aenean lobortis lorem et lacus. Sed
lacinia. Vivamus at lectus.
If you have included the custom CSS in a separate stylesheet you
will need to specify the stylesheet file name (along with the
default docbook-xsl.css stylesheet file name) with the
html.stylesheet XSL parameter. If you are using a2x(1) use the
--stylesheet option (it sets the html.stylesheet XSL parameter),
for example: --stylesheet "docbook-xsl.css mycss.css".
This applies to HTML outputs not PDF. To achieve the same
results with PDF outputs you will need to customize the DocBook XSL
Stylesheets to render indented paragraphs from DocBook simpara
elements containing the the role="indented" attribute.
34. Is there a way to set default table grid and frame attributes?
You can set the grid and frame attributes globally in your
document header with Attribute Entries or from the command-line using
the --attribute option. In the following example tables that don’t
explicitly set the grid and frame values will default to all and
topbot respectively:
:grid: all
:frame: topbot
This technique can be applied to any block element attribute
(just beware of possible ambiguity, for example, table and image
blocks both have a width attribute).
35. How can I place a backslash character in front of an attribute reference without escaping the reference?
Use the predefined {backslash} attribute reference instead of an
actual backslash, for example if the {projectname} attribute has
the value foobar then:
d:\data{backslash}{projectname}
would be rendered as:
d:\data\foobar
36. How can I escape AsciiDoc markup?
Most AsciiDoc inline elements can be suppressed by preceding them with
a backslash character. These elements include:
Attribute references.
Text formatting.
Replacements.
Special words.
Table cell separators.
But there are exceptions — see the next question.
37. Some elements can’t be escaped with a single backslash
There are a number of
exceptions to the usual single backslash rule — mostly relating to URL macros that
have two syntaxes or quoting
ambiguity.
Here are some non-standard escape examples:
\mailto:[\joe.]
mailto:[joe.]
\http://www.example.com
\\http://www.example.com[]
\\http://www.example.com[Foobar Limited]
http://www.example.com
http://www.example.com[]
http://www.example.com[Foobar Limited]
A C\++ Library for C++
\\``double-quotes''
\*\*F**ile Open\...
A C++ Library for C++
``double-quotes''
**F**ile Open...
The source of this problem is ambiguity across substitution types — the first match unescapes allowing the second to substitute. A
work-around for difficult cases is to side-step the problem using the
pass:[] passthrough inline macro.
Escaping is unnecessary inside inline literal passthroughs
(backtick quoted text).
38. How can I escape a list?
Here’s how to handle situations where the first line of a paragraph is
mistaken for a list item.
Numbered and bulleted lists
Precede the bullet or index of the first list item with an {empty}
attribute, for example:
{empty}- Qui in magna commodo est labitur dolorum an.
Est ne magna
primis adolescens.
The predefined {empty} attribute is replaced by an empty string and
ensures the first line is not mistaken for a bulleted list item.
Labeled lists
Two colons or semicolons in a paragraph may be confused with a labeled
list entry. Use the predefined {two-colons} and {two-semicolons}
attributes to suppress this behavior, for example:
Qui in magna commodo{two-colons} est labitur dolorum an. Est ne
magna primis adolescens.
Will be rendered as:
Qui in magna commodo:: est labitur dolorum an. Est ne
magna primis adolescens.
39. How can I set default list and tables styles?
You can set the element’s style entry in a global or custom
configuration file.
This example this will horizontally style all labeled lists that don’t
have an explicit style attribute:
[listdef-labeled]
style=horizontal
[listdef-labeled2]
style=horizontal
This example will put a top and bottom border on all tables that don’t
already have an explicit style attribute:
[tabledef-default]
style=topbot
topbot-style=frame="topbot"
Alternatively you can set the configuration entries from inside your
document, the above examples are equivalent to:
:listdef-labeled.style: horizontal
:listdef-labeled2.style: horizontal
:tabledef-default.topbot-style: frame="topbot"
:tabledef-default.style: topbot
40. Why do I get a filter non-zero exit code error?
An error was returned when AsciiDoc tried to execute an external
filter command. The most common reason for this is that the filter
command could not be found by the command shell. To figure out what
the problem is run AsciiDoc with the --verbose option to determine
the command that is failing and then try to run the command manually
from the command-line.
41. Are there any DocBook viewers?
, the GNOME help viewer, does a
creditable job of displaying DocBook XML files directly.
42. Can you create ODF and PDF files using LibreOffice?
can convert HTML produced by
AsciiDoc to ODF text format and PDF format (I used LibreOffice 3.5 at
the time of writing, the fidelity is very good but it’s not perfect):
Create the HTML file using AsciiDoc, for example:
asciidoc -a icons -a numbered -a disable-javascript article.txt
JavaScript is disabled because LibreOffice does not execute
JavaScript, this means that AsciiDoc table of contents and footnotes
will not be rendered into ODF (if you want the table of contents and
footnotes you could manually cut and paste them from a Web browser).
Convert the HTML file to an ODF text file using LibreOffice:
lowriter --invisible --convert-to odt article.html
The images imported from an HTML file will be linked, if your document
contains images you should convert them to embedded images:
Open the document in LibreOffice Writer.
Run the Edit→Links… menu command.
Select all links and press the Break Link button.
Some images may also have been resized. To restore an image to its
original size:
Right-click on the image and select the Picture… menu item.
Click on the Crop tab.
Press the Original Size button.
Convert the ODF file to an PDF text file using LibreOffice:
lowriter --invisible --convert-to pdf article.odt
A PDF index is automatically created using the section headings.
Alternatively you could manually copy-and-paste the entire document
from a Web browser into a blank ODF document in LibreOffice — this
technique will bring through the table of contents and footnotes.
This tip was originally contributed by Bernard Amade.
43. How can I suppress cell separators in included table data files?
Use the {include:} system attribute instead of the include::[]
macro (the former is not expanded until after the table data has been
parsed into cells, whereas the latter is included before the table is
processed.
44. How can I preserve paragraph line boundaries?
Apply the The verse paragraph style, the rendered text preserves
line boundaries and is useful for lyrics and poems.
For example:
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
Alternatively, if you are generating PDF files, you can use line
breaks. For example:
Consul *necessitatibus* per id, +
consetetur, eu pro everti postulant +
homero verear ea mea, qui.
45. How can I include non-breaking space characters?
Use the non-breaking space character entity reference   (see
the next question). You could also use the predefined {nbsp}
attribute reference.
46. Can I include HTML and XML character entity references in my document?
Yes, just enter the reference in your document. For example β
will print a Greek small beta character β
47. How do I include spaces in URLs?
URL inline macro targets (addresses) cannot contain white space
characters. If you need spaces encode them as %20. For example:
image:large%20image.png[]
http://www.foo.bar.com/an%20example%20document.html
48. How can I get AsciiDoc to assign the correct DocBook language attribute?
Set the AsciiDoc lang attribute to the appropriate language code.
For example:
a2x -a lang=es doc/article.txt
This will ensure that downstream DocBook processing will generate the
correct language specific document headings (things like table of
contents, revision history, figure and table captions, admonition
captions).
49. How can I turn off table and image title numbering?
For HTML outputs set the caption attribute to an empty string,
either globally:
or on an element by element basis, for example:
[caption=""]
image::images/tiger.png[]
50. How can I assign multiple author names?
A quick way to do this is put both authors in a single first name, for
My Document
===========
:Author: Bill_and_Ben_the_Flowerpot_Men
:Author Initials: BB & BC
asciidoc(1) replaces the underscores with spaces.
If you are generating DocBook then a
more flexible approach is to
create a docinfo file containing a DocBook authorgroup element
(search the User Guide for docinfo for more details).
51. How can I selectively disable a quoted text substitution?
Omitting the tag name will disable quoting. For example, if you don’t
want superscripts or subscripts then put the following in a custom
configuration file or edit the global asciidoc.conf configuration
Alternatively you can set the configuration entries from within your
document, the above examples are equivalent to:
:quotes.^:
:quotes.~:
The default format for the {localdate} attribute is the ISO 8601
yyyy-mm-dd format. You can change this format by explicitly setting
the {localdate} attribute. For example by setting it using the
asciidoc(1) -a command-line option:
asciidoc -a localdate=`date +%d-%m-%Y` mydoc.txt
You could also set it by adding an Attribute Entry to your source
document, for example:
:localdate: {sys: date +%Y-%m-%d}
53. Where can I find examples of commands used to build output documents?
The User Guide has some. You could also look at ./doc/main.aap and
./examples/website/main.aap in the AsciiDoc distribution, they have
all the commands used to build the AsciiDoc documentation and the
AsciiDoc website (even if you don’t use A-A-P you’ll still find it
54. Why have you used the DocBook &simpara& element instead of &para&?
&simpara& is really the same as &para& except it can’t contain
block elements — this matches, more closely, the AsciiDoc paragraph
semantics.
By default only specialcharacters and callouts are substituted in
you can add quotes substitutions by explicitly setting
the block subs attribute, for example:
[subs="quotes"]
------------------------------------------
$ ls *-al*
------------------------------------------
The -al will rendered bold. Note that:
You would need to explicitly escape text you didn’t want quoted.
Don’t do this in source code listing blocks because it modifies the
source code which confuses the syntax highlighter.
This only works if your DocBook processor recognizes DocBook
&emphasis& elements inside &screen& elements.
Alternative, if the lines are contiguous, you could use the literal
paragraph style:
["literal",subs="quotes"]
$ ls *-al*
56. Why doesn’t the include1::[] macro work?
Internally the include1 macro is translated to the include1 system
attribute which means it must be evaluated in a region where attribute
substitution is enabled. include1 won’t work, for example, in a
ListingBlock (unless attribute substitution is enabled).
is intended for use in configuration files, use the include macro
and set the attribute depth=1 instead, for example:
------------------------------------------------
include::blogpost_media_processing.txt[depth=1]
------------------------------------------------
57. How can I make the mailto macro work with multiple email addresses?
For the AsciiDoc mailto macro to work with multiple email addresses
(as per RFC2368) you need to URL encode the @ characters (replace
them with %40), if you don’t the individual addresses will be
rendered as separate links. You also need to .
For example, the following call won’t work:
mailto:,?subject=New foofoo release[New foofoo release]
Use this instead:
mailto:jb%40example.com,jd%40example.com?subject=New%20foofoo%20release[New foofoo release]
58. How can a replacement have a trailing backslash?
Quote the entry name — this nonsensical example replaces x\ with
If quoting were omitted the equals character (separating the
entry name x from the value y) would be escaped.
59. How can I control page breaks when printing HTML outputs?
Here are some techniques you can use to control page breaks in HTML
outputs produced by the xhtml11 and html5 backends:
You can generate a page break with the &&& block macro. The
following example prints the Rats and Mice section on a new page:
== Rats and Mice
Lorum ipsum ...
You can use the unbreakable option to instruct the browser not to
break a block element. The following image and it’s caption will be
kept together the printed page:
[options="unbreakable"]
.Tiger block image
image::images/tiger.png[Tiger image]
You can apply the unbreakable option globally to all block
elements by defining the unbreakable-option attribute in your
document header.
Finally, the most powerful technique is to create custom CSS
containing paged media properties. For example this asciidoc(1)
asciidoc --attribute stylesheet=article.css article.txt
Will include the following article.css file in the output document:
div#toc, div.sect1 { page-break-before: }
Which will ensure the table of contents and all top level sections
start on a new printed page.
60. Is it possible to reposition the Table of Contents in HTML outputs?
By default the xhtml11 and html5 backends auto-position the TOC
after the header. You can manually position the TOC by setting the
toc-placement attribute value to manual and then inserting the
toc::[] block macro where you want the TOC to appear. For example,
put this in the document header:
:toc-placement: manual
The put this where you want the TOC to appear:
61. HTML generated by AsciiDoc fills the width of the browser, how can I limit it to a more readable book width?
You can set the maximum with for outputs generated by html5,
xhtml11 and slidy backends by assigning the
attribute (either from the
command-line or with an attribute entry in the document header). For
asciidoc -a max-width=55em article.txt
62. Using roles to select fonts for PDF
Some applications require mixing fonts beyond the set of faces
normally provided by default (normal, monospace, italic etc.) for
example mixed language text where the font used for the majority of
text does not contain suitable glyphs in the minority language.
As AsciiDoc can not provide presentation markup since it is not
provided by Docbook this is achieved by marking text which should use
a different font with a custom role which can be rendered by the the
docbook toolchain.
For XHTML outputs AsciiDoc translates the role attribute to a
class which can be selected and styled by CSS as described in the
AsciiDoc users guide.
The Docbook toolchains will have to be configured to render the text
that you mark with the custom role.
For FOP a small XSL wrapper is needed, say a file called my_fo.xsl
containing:
&xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"&
&xsl:import href="/etc/asciidoc/docbook-xsl/fo.xsl"/&
&xsl:template match="phrase[@role='f2']"&
&fo:inline font-family="the font for f2"&
&xsl:apply-templates/&
&/fo:inline&
&/xsl:template&
&/xsl:stylesheet&
This is used with a2x by:
a2x -f pdf --fop --xsl-file=my_fo.xsl input.txt
and the AsciiDoc source marked by:
normal text [f2]#special font is like this# and back to normal
Thanks to Antonio Borneo for this answer.
A closing quote is not recognised if it is immediately followed by a
letter (the f in footnote in the following example):
``Double-quoted text''footnote:[Lorum ipsum...]
A workaround is to put a word-joiner between the trailing quote
and the footnote (the {empty} attribute would also work), for
``Double-quoted text''{wj}footnote:[Lorum ipsum...]
64. How can I convert documents from other formats to AsciiDoc?
You can use
to convert
documents in ,
to AsciiDoc.
65. How can I insert raw HTML in a document processed by a2x?
a2x generates HTML via DocBook (DocBook XSL Stylesheets) so if you
use a passthrough block it must contain DocBook (not HTML).
Fortunately DocBook XSL Stylesheets has a
which will inlcude a file containing raw HTML
into the generated HTML output. For example:
&?dbhtml-include href="snippet.html"?&
66. Why is there a period after the block title in the PDF output?
If your document has blocks that have block titles, you may notice in
the PDF output (generated by a2x(1) using the --fop flag) that a
period gets added to the end of the block title.
You will not see the period in the intermediary DocBook XML that’s
generated when creating a PDF — it’s added by the DocBook XSL
templates when the DocBook XML is converted to FO XML.
The DocBook XSL attribute that controls what character is added after
a block title is
You can override it and eliminate
the default period value by adding the following line to the
./docbook-xsl/common.xsl file that ships with AsciiDoc:
&xsl:param name="runinhead.default.title.end.punct"/&
This FAQ was