AsciiDoc User Guide
53 / 88
24.1 Document Header
Amanpage document Header is mandatory. The title line contains the man page name followed immediately by the manual
section number in brackets, for example ASCIIDOC(1). The title name should not contain white space and the manual section
number is a single digit optionally followed by a single character.
24.2 The NAME Section
The first manpage section is mandatory, mustbe titledNAME and must contain a single paragraph(usually a single line) consist-
ing of a list of one or more comma separated command name(s) separated from the command purpose by a dash character. The
dash must have at least one white space character on either side. For example:
printf, fprintf, sprintf - print formatted output
24.3 The SYNOPSIS Section
The second manpage section is mandatory and must be titledSYNOPSIS.
24.4 refmiscinfo attributes
In addition to the automatically created man pageintrinsicattributes you can assign DocBookrefmiscinfo element source,
version and manual values using AsciiDoc {mansource}, {manversion} and{manmanual} attributes respectively. This
example is from the AsciiDoc header of a man page source file:
:man source:
AsciiDoc
:man version:
{revnumber}
:man manual:
AsciiDoc Manual
25 Mathematical Formulas
The asciimath and latexmathpassthroughmacros along with asciimath and latexmathpassthroughblocks provide a (backend
dependent) mechanism for rendering mathematical formulas. You can use the following math markups:
Note
The latexmath macro used to include LaTeX Math in DocBook outputs is not the same as the latexmath macro used to include
LaTeX MathMLinXHTML outputs. LaTeX Math applies toDocBook outputs that areprocessedbydblatexand is normally used
to generate PDF files. LaTeXMathML is very much a subset of LaTeX Math and applies to XHTML documents.
25.1 LaTeX Math
LaTeX mathcanbeincludedindocumentsthatareprocessedbydblatex(1).Exampleinlineformula:
latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$]
For more examples see theAsciiDocwebsiteor the distributed doc/latexmath.txt file.
Create pdf bookmarks online - add, remove, update PDF bookmarks in C#.net, ASP.NET, MVC, Ajax, WinForms, WPF
Empower Your C# Project with Rapid PDF Internal Navigation Via Bookmark and Outline
bookmarks pdf files; add bookmarks to pdf online
Create pdf bookmarks online - VB.NET PDF bookmark library: add, remove, update PDF bookmarks in vb.net, ASP.NET, MVC, Ajax, WinForms, WPF
Empower Your VB.NET Project with Rapid PDF Internal Navigation Via Bookmark and Outline
auto bookmark pdf; split pdf by bookmark
AsciiDoc User Guide
54 / 88
25.2 ASCIIMathML
ASCIIMathMLformulascanbeincludedinXHTMLdocumentsgeneratedusingthexhtml11andhtml5backends. Toenable
ASCIIMathML support you must define the asciimath attribute, for example using the -a asciimath command-line option.
Example inline formula:
asciimath:[‘x/x={(1,if x!=0),(text{undefined},if x=0):}‘]
For more examples see theAsciiDocwebsiteor the distributed doc/asciimathml.txt file.
25.3 LaTeXMathML
LaTeXMathML allows LaTeX Math style formulas to be included in XHTML documents generated using the AsciiDoc xhtml11
and html5 backends. AsciiDoc uses theoriginalLaTeXMathML by Douglas Woodall. LaTeXMathML is derived from ASCI-
IMathML and is for users who are more familiar with or prefer using LaTeX math formulas (it recognizes a subset of LaTeX
Math, the differences are documented on the LaTeXMathML web page). To enable LaTeXMathML support you must define the
latexmath attribute, for example using the -a latexmath command-line option. Example inline formula:
latexmath:[$\sum_{n=1}^\infty \frac{1}{2^n}$]
For more examples see theAsciiDocwebsiteor the distributed doc/latexmathml.txt file.
25.4 MathML
MathMLisalowlevelXMLmarkupformathematics.AsciiDochasnomacrosforMathMLbutusersfamiliarwiththismarkup
could use passthrough macros and passthrough blocks to include MathML in output documents.
26 Configuration Files
AsciiDoc source file syntax and output file markup is largely controlled by a set of cascading, text based, configuration files. At
runtime The AsciiDoc default configuration files are combined with optional user and document specific configuration files.
26.1 Configuration File Format
Configuration files contain named sections. Each section begins with a section name in square brackets []. The section body
consists of the lines of text between adjacent section headings.
• Section names consist of one or more alphanumeric, underscore or dash characters and cannot begin or end with a dash.
• Lines starting with a # character are treated as comments and ignored.
• If the section name is prefixed with a + character then the section contents is appended to the contents of an already existing
same-named section.
• Otherwise same-named sections and section entries override previously loaded sections and section entries (this is sometimes
referred to as cascading). Consequently, downstream configuration files need only contain those sections and section entries
that need to be overridden.
Tip
When creating custom configuration files you only need to include the sections and entries that differ from the default configu-
ration.
VB.NET PDF File Compress Library: Compress reduce PDF size in vb.
Bookmarks. inputFilePath = Program.RootPath + "\\" 3.pdf"; String outputFilePath = Program.RootPath + "\\" 3_optimized.pdf"; 'create optimizing options
bookmarks in pdf files; create bookmarks in pdf reader
VB.NET PDF File Split Library: Split, seperate PDF into multiple
how to split a PDF file into multiple ones by PDF bookmarks or outlines Valid value for each index: 1 to (Page Count - 1). ' Create output PDF file path
bookmarks in pdf reader; pdf create bookmarks
AsciiDoc User Guide
55 / 88
Tip
The best way to learn about configuration files is to read the default configuration files in the AsciiDoc distribution in conjunc-
tion with
asciidoc(1)
output files. You can view configuration file load sequence by turning on the
asciidoc(1) -v
(
--verbose
)command-line option.
AsciiDoc reserves the following section names for specific purposes:
miscellaneous
Configuration options that don’t belong anywhere else.
attributes
Attribute name/value entries.
specialcharacters
Special characters reservedby the backend markup.
tags
Backendmarkup tags.
quotes
Definitions for quoted inline character formatting.
specialwords
Lists of words andphrases singled out for special markup.
replacements, replacements2, replacements3
Findand replace substitution definitions.
specialsections
Used to single out special section names for specific markup.
macros
Macro syntax definitions.
titles
Heading, section and block title definitions.
paradef-*
Paragraph element definitions.
blockdef-*
DelimitedBlock element definitions.
listdef-*
List element definitions.
listtags-*
List element tag definitions.
tabledef-*
Table element definitions.
tabletags-*
Table element tag definitions.
Eachline of text in these sections is a section entry. Section entries share the following syntax:
name=value
The entry value is set to value.
C# PDF File Split Library: Split, seperate PDF into multiple files
Free download library and use online C# class source codes in .NET framework 2.0 explain how to split a PDF file into multiple ones by PDF bookmarks or outlines
create bookmarks pdf files; export pdf bookmarks
C# PDF File Compress Library: Compress reduce PDF size in C#.net
Bookmarks. inputFilePath = Program.RootPath + "\\" 3.pdf"; String outputFilePath = Program.RootPath + "\\" 3_optimized.pdf"; // create optimizing options
display bookmarks in pdf; delete bookmarks pdf
AsciiDoc User Guide
56 / 88
name=
The entry value is set to a zerolength string.
name!
The entry is undefined (deleted from the configuration). This syntax only applies to attributes and miscellaneous sections.
S
ECTION ENTRY BEHAVIOR
• All equals characters inside the name must be escaped with a backslash character.
• name and value are stripped of leading and trailing white space.
• Attribute names, tagentry names and markuptemplate section names consist of one or morealphanumeric, underscoreor dash
characters. Names should not begin or end with a dash.
• A blank configuration file section (one without any entries) deletes any preceding section with the same name (applies to
non-markup template sections).
26.2 Miscellaneous section
The optional [miscellaneous] section specifies the following name=value options:
newline
Output file line termination characters. Can include any valid Python string escape sequences. The default value is \r\n
(carriage return, line feed). Should not be quoted or contain explicit spaces (use \x20 instead). For example:
$ asciidoc -a ’newline=\n’ -b docbook mydoc.txt
outfilesuffix
The default extension for the output file, for example outfilesuffix=.html. Defaults to backend name.
tabsize
The number of spaces to expand tab characters, for example tabsize=4. Defaults to 8. A tabsize of zero suppresses tab
expansion(usefulwhen piping included files through blockfilters). Included files canoverride this optionusing the tabsize
attribute.
pagewidth, pageunits
These global table related options are documented in theTableConfigurationFileDefinitionssub-section.
Note
[miscellaneous]
configuration file entries can be set using the
asciidoc(1) -a
(
--attribute
)command-line
option.
26.3 Titles section
sectiontitle
Two line sectiontitle pattern. The entry value is a Python regular expression containing the named group title.
underlines
Acomma separatedlist of document and section title underline character pairs starting with the section level 0 and ending
with section level 4 underline. The default setting is:
underlines="==","--","~~","^^","++"
C# Create PDF Library SDK to convert PDF from other file formats
and save editable PDF with a blank page, bookmarks, links, signatures Create fillable PDF document with fields. Preview PDF documents without other plug-ins.
create bookmark pdf file; pdf export bookmarks
.NET PDF SDK - Description of All PDF Processing Control Feastures
Download Free Trial View Online Demo Purchase Now. Full page navigation, zooming & rotation; Outlines, bookmarks, & thumbnail display; Conversion. PDF Create.
export bookmarks from pdf to excel; add bookmarks pdf
AsciiDoc User Guide
57 / 88
sect0.. .sect4
One line section title patterns. The entry value is a Python regular expression containing the named group title.
blocktitle
BlockTitle elementpattern.TheentryvalueisaPythonregularexpressioncontainingthenamedgrouptitle.
subs
Acomma separated list of substitutions that are performed on the document header and section titles. Defaults to normal
substitution.
26.4 Tags section
The [tags] section contains backend tag definitions (one per line). Tags are used to translate AsciiDoc elements to backend
markup.
An AsciiDoc tag definition is formatted like <tagname>=<starttag>|<endtag>. For example:
emphasis=<em>|</em>
In this example asciidoc(1) replaces the | character with the emphasized text from the AsciiDoc input file and writes the
result to the output file.
Use the {brvbar} attribute reference if you need to include a | pipe character inside tag text.
26.5 Attributes section
The optional [attributes] section contains predefined attributes.
If the attribute value requires leading or trailing spaces then the text text should be enclosed in quotation mark (") characters.
Todeletea attributeinserta name! entry in adownstream configuration fileor usetheasciidoc(1)--attribute name!
command-line option (an attribute name suffixed with a ! character deletes the attribute)
26.6 Special Characters section
The [specialcharacters] section specifies how to escape characters reserved by the backend markup. Each translation is
specified on a single line formatted like:
<special_character>=<translated_characters>
Special characters are normally confined to those that resolve markup ambiguity (in the case of HTML and XML markups the
ampersand, less than andgreater than characters). The following example causes alloccurrences of the < character tobe replaced
by &lt;.
<=&lt;
26.7 Quoted Text section
Quoting is usedprimarily for text formatting. The [quotes] section defines AsciiDoc quotingcharacters andtheir correspond-
ing backend markup tags. Each section entry value is the name of a of a [tags] section entry. The entry name is the character
(or characters) that quote the text. The following examples are taken from AsciiDoc configuration files:
[quotes]
_=emphasis
VB.NET Create PDF Library SDK to convert PDF from other file
editable PDF with a blank page, bookmarks, links, signatures Create fillable PDF document with fields in Visual Load PDF from stream programmatically in VB.NET.
pdf bookmark; adding bookmarks to a pdf
XDoc.Word for .NET, Advanced .NET Word Processing Features
& rotation; Outlines, bookmarks, & thumbnail display; Integrated annotation; More about Web Viewer ▶. Conversion. Word Create. Create Word from PDF; Create Word
how to add bookmarks to pdf document; bookmark template pdf
AsciiDoc User Guide
58 / 88
[tags]
emphasis=<em>|</em>
You can specify the left and right quote strings separately by separating them with a | character, for example:
‘‘|’’=quoted
Omitting the tag will disable quoting, for example, if you don’t want superscripts or subscripts put the following in a custom
configuration file or edit the global asciidoc.conf configuration file:
[quotes]
^=
~=
Unconstrained quotesaredifferentiatedfromconstrainedquotesbyprefixingthetagnamewithahashcharacter,forexample:
__=#emphasis
Q
UOTED TEXT BEHAVIOR
• Quote characters must be non-alphanumeric.
• To minimize quoting ambiguity try not to use the same quote characters in different quote types.
26.8 Special Words section
The [specialwords] section is used to single out words and phrases that you want to consistently format in some way
throughout your document without having to repeatedly specify the markup. The name of each entry corresponds to a markup
template section and the entry value consists of a list of words and phrases to be marked up. For example:
[specialwords]
strongwords=NOTE IMPORTANT
[strongwords]
<strong>{words}</strong>
The examples specifies that anyoccurrence of NOTE or IMPORTANT should appear in a bold font.
Words and word phrases are treated as Python regular expressions: for example, the word ˆNOTE would only match NOTE if
appeared at the start of a line.
AsciiDoc comes with three built-in Special Word types: emphasizedwords, monospacedwords and strongwords, each has a
corresponding (backend specific) markup template section. Edit the configuration files to customize existing Special Words and
to add new ones.
S
PECIAL WORD BEHAVIOR
• Word list entries must be separated by space characters.
• Word list entries with embedded spaces should be enclosed in quotation (") characters.
• A [specialwords] section entry of the form name=word1 [word2...] adds words to existing name entries.
• A [specialwords] section entry of the form name undefines (deletes) all existing name words.
• Since word list entries are processed as Python regular expressions you need to be careful to escape regular expression special
characters.
• By default Special Words are substituted before Inline Macros, this may lead to undesirable consequences. For example the
special word foobar would be expanded inside the macro call http://www.foobar.com[]. A possible solution is to
emphasize whole words only by defining the word using regular expression characters, for example \bfoobar\b.
• If the first matched character of a special word is a backslash then the remaining characters are output without markup i.e.
the backslash can be used to escape special word markup. For example the special word \\?\b[Tt]en\b will mark up the
words Ten and ten only if they are not preceded by a backslash.
AsciiDoc User Guide
59 / 88
26.9 Replacements section
[replacements], [replacements2] and [replacements3] configuration file entries specify find and replace text
and are formatted like:
<find_pattern>=<replacement_text>
The find text can be a Python regular expression; the replace text can contain Python regular expression group references.
Use Replacement shortcuts for often used macro references, for example (the second replacement allows us to backslash escape
the macro name):
NEW!=image:./images/smallnew.png[New!]
\\NEW!=NEW!
The only difference between the three replacement types is how they are applied. By default replacements and replacements2
are applied innormalsubstitution contexts whereas replacements3 needs to be configured explicitly and should only be used in
backend configuration files.
R
EPLACEMENT BEHAVIOR
• The built-in replacements can be escaped with a backslash.
• If the find or replace text has leading or trailing spaces then the text should be enclosed in quotation (") characters.
• Since the find text is processed as a regular expressionyou need to be careful toescape regular expression special characters.
• Replacements are performed in the same order they appear in the configuration file replacements section.
26.10 Markup Template Sections
Markup template sections supply backend markup for translating AsciiDoc elements. Since the text is normally backend depen-
dentyou’ll find these sections in the backendspecific configuration files. Template sections differ from other sections inthatthey
contain a single block of text instead of per line name=value entries. A markup template section body can contain:
• Attribute references
• System macro calls.
• A document content placeholder
The document content placeholder is a single | character and is replaced by text from the source element. Use the {brvbar}
attribute reference if you need a literal | character in the template.
26.11 Configuration file names, precedence and locations
Configuration files have a .conf file name extension; they are loaded from the following locations:
1. The directory containing the asciidoc executable.
2. If there is no asciidoc.conf file in the directory containing the asciidoc executable then load from the global con-
figuration directory (normally /etc/asciidoc or /usr/local/etc/asciidoc) i.e. the global configuration files
directory is skipped if AsciiDoc configuration files are installed in the same directory as the asciidoc executable. This
allows both a system wide copy and multiple local copies of AsciiDoc to coexist on the same host PC.
3. The user’s $HOME/.asciidoc directory (if it exists).
4. The directory containing the AsciiDoc source file.
AsciiDoc User Guide
60 / 88
5. Explicit configuration files specified using:
• The conf-files attribute (one or more file names separated bya | character). These files are loadedin the order they
are specified and prior tofiles specifiedusing the --conf-file command-line option.
• The asciidoc(1) --conf-file) command-line option. The --conf-file option can be specified multiple
times, in which case configuration files will be processed in the same order theyappear on the command-line.
6. Backendpluginconfiguration files are loaded from subdirectories named like backends/<backend> in locations 1, 2
and 3.
7. Filterconfiguration files are loaded from subdirectories named like filters/<filter> in locations 1, 2 and 3.
Configuration files from the above locations are loaded in the following order:
• The [attributes] section only from:
– asciidoc.conf in location 3
– Files from location 5.
This first pass makes locally set attributes available in the global asciidoc.conf file.
• asciidoc.conf from locations 1, 2, 3.
• attributes, titles and specialcharacters sections from the asciidoc.conf inlocation 4.
• The document header is parsed at this point and we can assume the backend and doctype have now been defined.
• Backendplugin <backend>.conf and <backend>-<doctype>.conf files from locations 6. If a backendpluginis not
found then try locations 1, 2 and 3 for <backend>.conf and <backend>-<doctype>.conf backend configuration
files.
• Filter conf files from locations 7.
• lang-<lang>.conf from locations 1, 2, 3.
• asciidoc.conf from location 4.
• <backend>.conf and <backend>-<doctype>.conf from location 4.
• Filter conf files from location 4.
• <docfile>.conf and <docfile>-<backend>.conf from location 4.
• Configuration files from location 5.
Where:
• <backend>and<doctype>are values specifiedby theasciidoc(1)-b (--backend) and-d(--doctype) command-
line options.
• <infile> is the path name of the AsciiDoc input file without the file name extension.
• <lang> is a two letter country code set by the the AsciiDoc lang attribute.
AsciiDoc User Guide
61 / 88
Note
The backend and language global configuration files are loaded after the header has been parsed. This means that you can
set most attributes in the document header. Here’s an example header:
Life’s Mysteries
================
:author: Hu Nose
:doctype: book
:toc:
:icons:
:data-uri:
:lang: en
:encoding: iso-8859-1
Attributes set in the document header take precedence over configuration file attributes.
Tip
Use the
asciidoc(1) -v
(
--verbose
)command-line option to see which configuration files are loaded and the order in
which they are loaded.
27 Document Attributes
Adocument attribute is comprised of a name and a textual value and is used for textual substitution in AsciiDoc documents and
configuration files. Anattribute reference (an attribute name enclosed inbraces) is replaced bythe corresponding attribute value.
Attribute names are case insensitive and canonly contain alphanumeric, dash and underscore characters.
There are four sources of document attributes (from highest to lowest precedence):
• Command-line attributes.
• AttributeEntry, AttributeList, Macro and BlockId elements.
• Configuration file [attributes] sections.
• Intrinsic attributes.
Within each of these divisions the last processed entry takes precedence.
Note
If an attribute is not defined then the line containing the attribute reference is dropped. This property is used extensively in
AsciiDoc configuration files to facilitate conditional markup generation.
28 Attribute Entries
The AttributeEntry block element allows document attributes to be assigned within an AsciiDoc document. Attribute
entries are added to the global document attributes dictionary. The attribute name/value syntax is a single line like:
:<name>: <value>
For example:
AsciiDoc User Guide
62 / 88
:Author Initials: JB
This will set an attribute reference {authorinitials} to the value JB in the current document.
To delete (undefine) an attribute use the following syntax:
:<name>!:
A
TTRIBUTE
E
NTRY BEHAVIOR
• The attribute entry line begins with colon—no white space allowed in left margin.
• AsciiDoc converts the <name> to a legal attribute name (lower case, alphanumeric, dash and underscore characters only— all
other characters deleted). This allows more human friendly text to be used.
• Leading and trailing white space is stripped from the <value>.
• Lines ending in a space followed by a plus character are continued to the next line, for example:
:description: AsciiDoc is a text document format for writing notes, +
documentation, articles, books, slideshows, web pages +
and man pages.
• If the <value> is blank then the corresponding attribute value is set to an empty string.
• Attribute references contained in the entry <value> will be expanded.
• By default AttributeEntry values are substituted for specialcharacters and attributes (see above), if you want to
change or disable AttributeEntry substitution use theinlinemacro syntax.
• Attribute entries in the document Header are available for header markup template substitution.
• Attribute elements override configuration file and intrinsic attributes but do not override command-line attributes.
Here are some more attribute entry examples:
AsciiDoc User Manual
====================
:author:
Stuart Rackham
:email:
srackham@gmail.com
:revdate:
April 23, 2004
:revnumber: 5.1.1
Which creates these attributes:
{author}, {firstname}, {lastname}, {authorinitials}, {email},
{revdate}, {revnumber}
The previous example is equivalent to thisdocumentheader:
AsciiDoc User Manual
====================
Stuart Rackham <srackham@gmail.com>
5.1.1, April 23, 2004
Documents you may be interested
Documents you may be interested