AsciiDoc User Guide
73 / 88
32.5 Tables
Table behavior and syntax is determined by [tabledef-
*
]and [tabletags-
*
]configuration file sections. The user can
change existing table behavior and add new table types by editing configuration files. The following [tabledef-
*
]section
entries generate table output markup elements:
colspec
The table colspec tag definition.
headrow, footrow, bodyrow
Table header, footer and body row tag definitions. headrow and footrow table definition entries default to bodyrow if they
are undefined.
headdata, footdata, bodydata
Table header, footer and body data tag definitions. headdata and footdata table definition entries default to bodydata if
they are undefined.
paragraph
If the paragraph tag is specified then blank lines in the cell data are treated as paragraph delimiters and marked up using
this tag.
Table behavior is also influenced by the following [miscellaneous] configuration file entries:
pagewidth
This integer value is the printable width of the output media. Seetableattributes.
pageunits
The units of width in output markup width attribute values.
T
ABLE DEFINITION BEHAVIOR
• The outputmarkup generation is specificallydesigned to work with the HTML and CALS (DocBook) table models, butshould
be adaptable to most XML table schema.
• Table definitions can be “mixed in” from multiple cascading configuration files.
• Newtabledefinitions inheritthedefaulttable andtable tags definitions([tabledef-default] and[tabletags-default])
so you only need to override those conf file entries that require modification.
33 Filters
AsciiDoc filters allow external commands to process AsciiDoc Paragraphs, DelimitedBlocks and Table content. Filters are
primarily an extension mechanism for generating specialized outputs. Filters are implemented using external commands which
are specified in configurationfile definitions.
There’s nothing special about the filters, they’re just standard UNIXfilters: they read text from the standard input, process it, and
write to the standard output.
The asciidoc(1) command --filter option can be used to install and remove filters. The same option is used to uncon-
ditionally load a filter.
Attribute substitution is performed onthe filter commandprior to execution— attributes can be used topass parameters from the
AsciiDoc source document to the filter.
Warning
Filters sometimes included executable code. Before installing a filter you should verify that it is from a trusted source.
Add bookmarks to pdf preview - 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
bookmark page in pdf; creating bookmarks pdf
Add bookmarks to pdf preview - 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
excel pdf bookmarks; create bookmark pdf file
AsciiDoc User Guide
74 / 88
33.1 Filter Search Paths
If the filter command does not specify a directory path then asciidoc(1) recursively searches for the executable filter com-
mand:
• First it looks in the user’s $HOME/.asciidoc/filters directory.
• Next the global filters directory (usually /etc/asciidoc/filters or /usr/local/etc/asciidoc) directory is
searched.
• Then it looks in the asciidoc(1) ./filters directory.
• Finally it relies on the executing shell to search the environment search path ($PATH).
Standard practice is to install each filter in it’s own sub-directory with the same name as the filter’s style definition. For example
the music filter’s style name is music so it’s configuration and filter files are stored in the filters/music directory.
33.2 Filter Configuration Files
Filters are normally accompanied by a configuration file containing a Paragraph or DelimitedBlock definition along with corre-
sponding markup templates.
While it is possible to create new Paragraph or DelimitedBlock definitions the preferred way to implement a filter is to add a
styletotheexistingParagraphandListingBlockdefinitions(allfiltersshippedwithAsciiDocusethistechnique). Thefilteris
applied to the paragraph or delimited block by preceding it with an attribute list: the first positional attribute is the style name,
remaining attributes are normally filter specific parameters.
asciidoc(1) auto-loads all .conf files found in the filter search paths unless the container directory also contains a file
named __noautoload__ (see previous section). The __noautoload__ feature is used for filters that will be loaded
manually using the --filter option.
33.3 Example Filter
AsciiDoccomes withatoyfilter for highlightingsourcecode keywordsandcomments. Seealsothe./filters/code/code-filter-readme.txt
file.
Note
The purpose of this toy filter is to demonstrate how to write a filter—it’s much to simplistic to be passed off as a code syntax
highlighter. If you want a full featured multi-language highlighter use thesourcecodehighlighterfilter.
33.4 Built-in filters
The AsciiDoc distribution includes source, music, latex and graphviz filters, details are on theAsciiDocwebsite.
Table 11: Built-in filters list
Filter name
Description
music
Amusicfilteris included in the distribution ./filters/ directory. It translates music in
LilyPondorABCnotationtostandardclassicalnotation.
source
Asourcecodehighlightfilter is included in the distribution./filters/ directory.
latex
TheAsciiDocLaTeXfiltertranslates LaTeX source to a PNG image that is automatically inserted
into the AsciiDoc output documents.
graphviz
Gouichi Iisaka has written aGraphvizfilter for AsciiDoc. Graphviz generates diagrams from a
textual specification. Gouichi Iisaka’s Graphviz filter is included in the AsciiDoc distribution. Here
are someAsciiDocGraphvizexamples.
VB.NET PDF File Compress Library: Compress reduce PDF size in vb.
Remove bookmarks, annotations, watermark, page labels and article threads from PDF while compressing. Also a preview component enables compressing and
create pdf with bookmarks from word; create bookmarks pdf
VB.NET PDF File Split Library: Split, seperate PDF into multiple
Independent component for splitting PDF document in preview without using Add necessary references: a PDF file into multiple ones by PDF bookmarks or outlines.
bookmarks pdf file; how to add bookmarks to pdf document
AsciiDoc User Guide
75 / 88
33.5 Filter plugins
Filterpluginsare a mechanism for distributing AsciiDoc filters. A filter plugin is a Zip file containing the files that constitute a
filter. The asciidoc(1) --filter option is used to load and manage filerplugins.
• Filter pluginstakeprecedence over built-in filters with the same name.
• By default filter plugins are installed in $HOME/.asciidoc/filters/<filter> where <filter> is the filter name.
34 Plugins
The AsciiDoc plugin architecture is an extension mechanism that allows additionalbackends,filtersandthemes to be added to
AsciiDoc.
• A plugin is a Zip file containing an AsciiDoc backend, filter or theme (configuration files, stylesheets, scripts, images).
• The asciidoc(1) --backend, --filter and --theme command-line options are used to load and manage plugins.
Each of these options responds to the plugin management install, list, remove andbuild commands.
• The plugin management command names are reserved and cannot be used for filter, backend or theme names.
• The plugin Zip file name always begins with the backend, filter or theme name.
Plugin commands and conventions are documented in the asciidoc(1) man page. You can find lists of plugins on the
AsciiDoc website.
35 Help Commands
The asciidoc(1) commandhas a --help optionwhichprints help topics to stdout. Thedefaulttopic summarizes asciidoc(1)
usage:
$ asciidoc --help
To print a help topic specify the topic name as a command argument. Help topic names can be shortened so long as they are not
ambiguous. Examples:
$ asciidoc --help manpage
$ asciidoc -h m
# Short version of previous example.
$ asciidoc --help syntax
$ asciidoc -h s
# Short version of previous example.
35.1 Customizing Help
To change, delete or add your own help topics edit a help configuration file. The help file name help-<lang>.conf is based
on the setting of the lang attribute, it defaults to help.conf (English). Thehelpfilelocation will depend on whether you
want the topics to apply to all users or just the current user.
The help topic files have the same named section format as otherconfigurationfiles. The help.conf files are stored in the
same locations and loaded in the same order as other configuration files.
Whenthe --help command-line optionis specifiedAsciiDoc loads the appropriatehelpfiles and then prints the contents of the
section whose name matches the help topic name. If a topic name is not specified default is used. You don’t need to specify
the whole help topic name on the command-line, just enough letters to ensure it’s not ambiguous. If a matching help file section
is not found a list of available topics is printed.
C# PDF File Split Library: Split, seperate PDF into multiple files
Advanced component for splitting PDF document in preview without any third Add necessary references: a PDF file into multiple ones by PDF bookmarks or outlines.
bookmark pdf in preview; create bookmark pdf
C# Create PDF Library SDK to convert PDF from other file formats
editable PDF with a blank page, bookmarks, links, signatures document in C#.NET using this PDF document creating toolkit, if you need to add some text
delete bookmarks pdf; how to add bookmarks to a pdf
AsciiDoc User Guide
76 / 88
36 Tips and Tricks
36.1 Know Your Editor
Writing AsciiDoc documents will be a whole lot more pleasant if you know your favorite text editor. Learn how to indent and
reformat text blocks, paragraphs, lists and sentences.Tipsforvimusersfollow.
36.2 Vim Commands for Formatting AsciiDoc
36.2.1 Text Wrap Paragraphs
Use the vim :gq command to reformat paragraphs. Setting the textwidth sets the right text wrap margin; for example:
:set textwidth=70
To reformat a paragraph:
1. Position the cursor at the start of the paragraph.
2. Type gq}.
Execute :help gq command to read about the vim gq command.
Tip
• Assign the
gq}
command to the Q key with the
nnoremap Q gq}
command or put it in your
~/.vimrc
file to so it’s
always available (see theExample~/.vimrcfile).
• Put
set
commands in your
~/.vimrc
file so you don’t have to enter them manually.
• The Vim website (http://www.vim.org) has a wealth of resources, including scripts for automated spell checking and ASCII
Art drawing.
36.2.2 Format Lists
The gq command can also be used to format bulleted, numbered and callout lists. First you need to set the comments,
formatoptions and formatlistpat (see theExample~/.vimrcfile).
Now you can format simple lists that use dash, asterisk, period and plus bullets along with numbered ordered lists:
1. Position the cursor at the start of the list.
2. Type gq}.
36.2.3 Indent Paragraphs
Indent whole paragraphs by indenting the fist line with the desired indent and then executing the gq} command.
C# powerpoint - Convert PowerPoint to HTML in C#.NET
HTML document file, converted by C#.NET PowerPoint to HTML converter toolkit SDK, preserves all the original anchors, links, bookmarks and font Add references:
add bookmarks to pdf reader; add bookmark pdf
C# Word - Convert Word to HTML in C#.NET
VB.NET How-to, VB.NET PDF, VB.NET Word, VB.NET Excel, VB HTML converter toolkit SDK, preserves all the original anchors, links, bookmarks and font Add references
bookmarks in pdf reader; creating bookmarks in a pdf document
AsciiDoc User Guide
77 / 88
36.2.4 Example
~/.vimrc
File
" Use bold bright fonts.
set background=dark
" Show tabs and trailing characters.
"set listchars=tab:»·,trail:·,eol:\ensuremath{\lnot}
set listchars=tab:»·,trail:·
set list
" Reformat paragraphs and list.
nnoremap <Leader>r gq}
" Delete trailing white space and Dos-returns and to expand tabs to spaces.
nnoremap <Leader>t :set et<CR>:retab!<CR>:%s/[\r \t]\+$//<CR>
autocmd BufRead,BufNewFile
*
.txt,
*
.asciidoc,README,TODO,CHANGELOG,NOTES,ABOUT
\ setlocal autoindent expandtab tabstop=8 softtabstop=2 shiftwidth=2 filetype=  -
asciidoc
\ textwidth=70 wrap formatoptions=tcqn
\ formatlistpat=^\\s
*
\\d\\+\\.\\s\\+\\\\|^\\s
*
<\\d\\+>\\s\\+\\\\|^\\s
*
[a-zA-Z  -
.]\\.\\s\\+\\\\|^\\s
*
[ivxIVX]\\+\\.\\s\\+
\ comments=s1:/
*
,ex:
*
/,://,b:#,:%,:XCOMM,fb:-,fb:
*
,fb:+,fb:.,fb:>
36.3 Troubleshooting
AsciiDoc diagnostic features are detailed in theDiagnosticsappendix.
36.4 Gotchas
Incorrect character encoding
If you get an error message like ’UTF-8’ codec can’t decode ... then you source file contains invalid UTF-8
characters —set the AsciiDocencodingattribute for thecorrectcharacter set(typicallyISO-8859-1 (Latin-1) for European
languages).
Invalid output
AsciiDoc attempts to validate the input AsciiDoc source but makes no attempt to validate the output markup, it leaves that
to external tools such as xmllint(1) (integratedinto a2x(1)). Backend validation cannot be hardcoded into AsciiDoc
because backends are dynamically configured. The following example generates valid HTML but invalid DocBook (the
DocBook literal element cannot contain an emphasis element):
+monospaced text with an _emphasized_ word+
Misinterpreted text formatting
You can suppress markup expansion by placing a backslash character immediately in front of the element. The following
example suppresses inline monospaced formatting:
\+1 for C++.
Overlapping text formatting
Overlapping text formatting will generate illegal overlapping markup tags which will result in downstream XML parsing
errors. Here’s an example:
Some
*
strong markup _that overlaps
*
emphasized markup_.
How to C#: Basic SDK Concept of XDoc.PowerPoint
Conversely, conversion from PDF to PowerPoint (.PPTX) is also split PowerPoint file(s), and add, create, insert This class describes bookmarks in a PowerPoint
pdf export bookmarks; create bookmarks in pdf reader
How to C#: Basic SDK Concept of XDoc.Word
Conversely, conversion from PDF to Word (.docx) is also and split Word file(s), and add, create, insert This class describes bookmarks in a Word document.
export pdf bookmarks to excel; bookmarks in pdf files
AsciiDoc User Guide
78 / 88
Ambiguous underlines
ADelimitedBlock can immediately follow a paragraph without an intervening blank line, but be careful, a single line
paragraph underline may be misinterpreted as a section title underline resulting in a “closing block delimiter expected”
error.
Ambiguous ordered list items
Lines beginning with numbers at the end of sentences will be interpreted as ordered list items. The following example
(incorrectly) begins a new list with item number 1999:
He was last sighted in
1999. Since then things have moved on.
The list item out of sequence warning makes it unlikely that this problem will go unnoticed.
Special characters in attribute values
Special character substitution precedes attribute substitution so if attribute values contain special characters you may,
depending on the substitution context, need to escape the special characters yourself. For example:
$ asciidoc -a ’orgname=Bill &amp; Ben Inc.’ mydoc.txt
Attribute lists
If any named attribute entries are present thenall string attribute values must be quoted. For example:
["Desktop screenshot",width=32]
36.5 Combining separate documents
You have a number of stand-alone AsciiDoc documents that you want to process as a single document. Simply processing them
witha series of include macros won’t work because the documents contain (level 0) document titles. The solution is to create
atop level wrapper document and use the leveloffset attribute to push them all down one level. For example:
Combined Document Title
=======================
// Push titles down one level.
:leveloffset: 1
include::document1.txt[]
// Return to normal title levels.
:leveloffset: 0
A Top Level Section
-------------------
Lorum ipsum.
// Push titles down one level.
:leveloffset: 1
include::document2.txt[]
include::document3.txt[]
The document titles in the included documents will nowbe processed as level 1 section titles, level 1 sections as level 2 sections
and so on.
• Put a blank line between the include macro lines to ensure the title of the included document is not seen as part of the last
paragraph of the previous document.
• Youwon’t want non-title document header lines (for example, Author and Revision lines) in the included files— conditionally
exclude them if they are necessary for stand-alone processing.
C# Excel - Convert Excel to HTML in C#.NET
document file, converted by C#.NET Excel to HTML converter toolkit SDK, preserves all the original anchors, links, bookmarks and font Add necessary references:
create pdf bookmark; convert word pdf bookmarks
How to C#: Basic SDK Concept of XDoc.Excel
Conversely, conversion from PDF to Excel (.XLSX) is also and split Excel file(s), and add, create, insert This class describes bookmarks in a Excel document.
adding bookmarks in pdf; pdf bookmark
AsciiDoc User Guide
79 / 88
36.6 Processing document sections separately
You have divided your AsciiDoc document into separate files (one per top level section) whichare combinedand processed with
the following top level document:
Combined Document Title
=======================
Joe Bloggs
v1.0, 12-Aug-03
include::section1.txt[]
include::section2.txt[]
include::section3.txt[]
You alsowant toprocess the section files as separate documents. This is easybecauseasciidoc(1) will quite happily process
section1.txt, section2.txt and section3.txt separately—the resulting output documents contain the section but
have no document title.
36.7 Processing document snippets
Use the -s (--no-header-footer) command-lineoptiontosuppress header andfooter output, this is useful if the processed
output is to be included in another file. For example:
$ asciidoc -sb docbook section1.txt
asciidoc(1) can be used as a filter, so you can pipe chunks of text through it. For example:
$ echo ’Hello
*
World!
*
’ | asciidoc -s -
<div class="paragraph"><p>Hello <strong>World!</strong></p></div>
36.8 Badges in HTML page footers
See the [footer] section in the AsciiDoc distribution xhtml11.conf configuration file.
36.9 Pretty printing AsciiDoc output
If the indentation and layout of the asciidoc(1) output is not to your liking you can:
1. Change the indentation and layout of configuration file markup template sections. The {empty} attribute is useful for
outputting trailing blank lines in markup templates.
2. Use Dave Raggett’sHTMLTidyprogram to tidy asciidoc(1) output. Example:
$ asciidoc -b docbook -o - mydoc.txt | tidy -indent -xml >mydoc.xml
3. Use the xmllint(1) format option. Example:
$ xmllint --format mydoc.xml
36.10 Supporting minor DocBook DTD variations
The conditional inclusion of DocBook SGML markup at the end of the distribution docbook45.conf file illustrates how to
support minor DTDvariations. The included sections override corresponding entries from preceding sections.
AsciiDoc User Guide
80 / 88
36.11 Creating stand-alone HTML documents
If you’ve ever tried to send someone an HTML document that includes stylesheets and images you’ll know that it’s not as
straight-forward as exchanging asingle file. AsciiDochas options tocreate stand-alone documents containingembedded images,
stylesheets and scripts. The following AsciiDoc command creates a single file containingembeddedimages, CSS stylesheets,
and JavaScript (for table of contents and footnotes):
$ asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt
You can view the HTML file here:http://asciidoc.org/article-standalone.html
36.12 Shipping stand-alone AsciiDoc source
Reproducingpresentation documents from someone else’s source has one major problem: unless your configuration files are the
same as the creator’s you won’t get the same output.
The solution is to create a single backend specific configuration file using the asciidoc(1) -c (--dump-conf) command-
line option. You then ship this file along with the AsciiDoc source document plus the asciidoc.py script. The only end user
requirement is that they have Python installed (and that they consider you a trusted source). This example creates a composite
HTML configuration file for mydoc.txt:
$ asciidoc -cb xhtml11 mydoc.txt > mydoc-xhtml11.conf
Ship mydoc.txt, mydoc-html.conf, and asciidoc.py. With these three files (and a Python interpreter) the recipient
can regenerate the HMTL output:
$ ./asciidoc.py -eb xhtml11 mydoc.txt
The -e(--no-conf) optionexcludes theuse of implicitconfigurationfiles, ensuringthatonlyentriesfrom themydoc-html.conf
configuration are used.
36.13 Inserting blank space
Adjust your style sheets to add the correct separation between block elements. Inserting blank paragraphs containing a single
non-breaking space character {nbsp} works but is an ad hoc solution compared to using style sheets.
36.14 Closing open sections
You can close off section tags up to level N by calling the eval::[Section.setlevel(N)] system macro. This is useful
if you want to include a section composed of raw markup. The following example includes a DocBook glossary division at the
top section level (level 0):
ifdef::basebackend-docbook[]
eval::[Section.setlevel(0)]
+++++++++++++++++++++++++++++++
<glossary>
<title>Glossary</title>
<glossdiv>
...
</glossdiv>
</glossary>
+++++++++++++++++++++++++++++++
endif::basebackend-docbook[]
AsciiDoc User Guide
81 / 88
36.15 Validating output files
Use xmllint(1) to check the AsciiDoc generated markup is both well formed and valid. Here are some examples:
$ xmllint --nonet --noout --valid docbook-file.xml
$ xmllint --nonet --noout --valid xhtml11-file.html
$ xmllint --nonet --noout --valid --html html4-file.html
The --valid option checks the file is valid against the document type’s DTD, if the DTD is not installed in your system’s
catalog then it will be fetched from its Internet location. If you omit the --valid option the document will only be checked
that it is well formed.
The onlineW3CMarkupValidationServiceis the defacto standard when it comes to validating HTML (it validates all HTML
standards including HTML5).
37 Glossary
Block element
An AsciiDoc block element is a document entity composed of one or more whole lines of text.
Inline element
AsciiDoc inline elements occur within block element textual content, they perform formatting and substitution tasks.
Formal element
An AsciiDoc block element that has a BlockTitle. Formalelements are normally listedin front or back matter, for example
lists of tables, examples and figures.
Verbatim element
The word verbatim indicates that white space and line breaks in the source document are to be preserved in the output
document.
A Migration Notes
A.1 Version 7 to version 8
• A new setof quotes has beenintroducedwhich may match inline text inexistingdocuments— if they do you’ll need to escape
the matched text with backslashes.
• The indexentry inline macro syntax has changed—if your documents include indexes you may need to edit them.
• Replaced a2x(1) --no-icons and --no-copy options with their negated equivalents: --icons and --copy respec-
tively. The default behavior has alsochanged—the use of icons and copying of icon and CSS files must be specified explicitly
with the --icons and --copy options.
The rationale for the changes can be found in the AsciiDoc CHANGELOG.
Note
If you want to disableunconstrainedquotes, the new alternative constrainedquotes syntax andthe new index entry syntax then
youcandefinetheattribute
asciidoc7compatible
(forexample by usingthe
-a asciidoc7compatible
command-
line option).
AsciiDoc User Guide
82 / 88
B Packager Notes
Read the README andINSTALL files (inthe distribution root directory) for installprerequisites andprocedures. The distribution
Makefile.in (used by configure to generate the Makefile) is the canonical installation procedure.
C AsciiDoc Safe Mode
AsciiDoc safe mode skips potentially dangerous scriptedsections inAsciiDocsource files byinhibiting the executionof arbitrary
code or the inclusion of arbitrary files.
The safe mode is disabled bydefault, it can be enabled with the asciidoc(1) --safe command-line option.
S
AFE MODE CONSTRAINTS
• eval, sys and sys2 executable attributes and block macros are not executed.
• include::<filename>[] and include1::<filename>[] block macro files must reside inside the parent file’s
directory.
• {include:<filename>} executable attribute files must reside inside the source document directory.
• Passthrough Blocks are dropped.
Warning
The safe mode is not designed to protect against unsafe AsciiDoc configuration files. Be especially careful when:
1. Implementing filters.
2. Implementing elements that don’t escape special characters.
3. Accepting configuration files from untrusted sources.
D Using AsciiDoc with non-English Languages
AsciiDoc can process UTF-8character sets but there are some things you need to be aware of:
• If you are generating output documents using a DocBook toolchain then you should set the AsciiDoc lang attribute to the
appropriate language (it defaults to en (English)). This will ensure things like table of contents, figure and table captions and
admonition captions are output in the specified language. For example:
$ a2x -a lang=es doc/article.txt
• If you are outputtingHTML directlyfrom asciidoc(1) you’llneedto setthevarious
*
_caption attributes tomatch your
target language (see the list of captions and titles in the [attributes] section of the distribution lang-
*
.conf files).
The easiest way is to create a language .conf file (see the AsciiDoc’s lang-en.conf file).
Note
You still use the NOTE, CAUTION, TIP, WARNING, IMPORTANT captions in the AsciiDoc source, they get translated in the
HTML output file.
• asciidoc(1) automatically loads configuration files named like lang-<lang>.conf where <lang> is a two letter
language code that matches the current AsciiDoc lang attribute. See alsoConfigurationFileNamesandLocations.
Documents you may be interested
Documents you may be interested