/script-kiddie/002_script_kiddie/script-kiddie/node_modules/ace-builds/demo/kitchen-sink/docs/asciidoc.asciidoc |
@@ -0,0 +1,6040 @@ |
AsciiDoc User Guide |
=================== |
Stuart Rackham <srackham@gmail.com> |
:Author Initials: SJR |
:toc: |
:icons: |
:numbered: |
:website: http://www.methods.co.nz/asciidoc/ |
|
AsciiDoc is a text document format for writing notes, documentation, |
articles, books, ebooks, slideshows, web pages, blogs and UNIX man |
pages. AsciiDoc files can be translated to many formats including |
HTML, PDF, EPUB, man page. AsciiDoc is highly configurable: both the |
AsciiDoc source file syntax and the backend output markups (which can |
be almost any type of SGML/XML markup) can be customized and extended |
by the user. |
|
.This document |
********************************************************************** |
This is an overly large document, it probably needs to be refactored |
into a Tutorial, Quick Reference and Formal Reference. |
|
If you're new to AsciiDoc read this section and the <<X6,Getting |
Started>> section and take a look at the example AsciiDoc (`*.txt`) |
source files in the distribution `doc` directory. |
********************************************************************** |
|
|
Introduction |
------------ |
AsciiDoc is a plain text human readable/writable document format that |
can be translated to DocBook or HTML using the asciidoc(1) command. |
You can then either use asciidoc(1) generated HTML directly or run |
asciidoc(1) DocBook output through your favorite DocBook toolchain or |
use the AsciiDoc a2x(1) toolchain wrapper to produce PDF, EPUB, DVI, |
LaTeX, PostScript, man page, HTML and text formats. |
|
The AsciiDoc format is a useful presentation format in its own right: |
AsciiDoc markup is simple, intuitive and as such is easily proofed and |
edited. |
|
AsciiDoc is light weight: it consists of a single Python script and a |
bunch of configuration files. Apart from asciidoc(1) and a Python |
interpreter, no other programs are required to convert AsciiDoc text |
files to DocBook or HTML. See <<X11,Example AsciiDoc Documents>> |
below. |
|
Text markup conventions tend to be a matter of (often strong) personal |
preference: if the default syntax is not to your liking you can define |
your own by editing the text based asciidoc(1) configuration files. |
You can also create configuration files to translate AsciiDoc |
documents to almost any SGML/XML markup. |
|
asciidoc(1) comes with a set of configuration files to translate |
AsciiDoc articles, books and man pages to HTML or DocBook backend |
formats. |
|
.My AsciiDoc Itch |
********************************************************************** |
DocBook has emerged as the de facto standard Open Source documentation |
format. But DocBook is a complex language, the markup is difficult to |
read and even more difficult to write directly -- I found I was |
spending more time typing markup tags, consulting reference manuals |
and fixing syntax errors, than I was writing the documentation. |
********************************************************************** |
|
|
[[X6]] |
Getting Started |
--------------- |
Installing AsciiDoc |
~~~~~~~~~~~~~~~~~~~ |
See the `README` and `INSTALL` files for install prerequisites and |
procedures. Packagers take a look at <<X38,Packager Notes>>. |
|
[[X11]] |
Example AsciiDoc Documents |
~~~~~~~~~~~~~~~~~~~~~~~~~~ |
The best way to quickly get a feel for AsciiDoc is to view the |
AsciiDoc web site and/or distributed examples: |
|
- Take a look at the linked examples on the AsciiDoc web site home |
page {website}. Press the 'Page Source' sidebar menu item to view |
corresponding AsciiDoc source. |
- Read the `*.txt` source files in the distribution `./doc` directory |
along with the corresponding HTML and DocBook XML files. |
|
|
AsciiDoc Document Types |
----------------------- |
There are three types of AsciiDoc documents: article, book and |
manpage. All document types share the same AsciiDoc format with some |
minor variations. If you are familiar with DocBook you will have |
noticed that AsciiDoc document types correspond to the same-named |
DocBook document types. |
|
Use the asciidoc(1) `-d` (`--doctype`) option to specify the AsciiDoc |
document type -- the default document type is 'article'. |
|
By convention the `.txt` file extension is used for AsciiDoc document |
source files. |
|
article |
~~~~~~~ |
Used for short documents, articles and general documentation. See the |
AsciiDoc distribution `./doc/article.txt` example. |
|
AsciiDoc defines standard DocBook article frontmatter and backmatter |
<<X93,section markup templates>> (appendix, abstract, bibliography, |
glossary, index). |
|
book |
~~~~ |
Books share the same format as articles, with the following |
differences: |
|
- The part titles in multi-part books are <<X17,top level titles>> |
(same level as book title). |
- Some sections are book specific e.g. preface and colophon. |
|
Book documents will normally be used to produce DocBook output since |
DocBook processors can automatically generate footnotes, table of |
contents, list of tables, list of figures, list of examples and |
indexes. |
|
AsciiDoc defines standard DocBook book frontmatter and backmatter |
<<X93,section markup templates>> (appendix, dedication, preface, |
bibliography, glossary, index, colophon). |
|
.Example book documents |
Book:: |
The `./doc/book.txt` file in the AsciiDoc distribution. |
|
Multi-part book:: |
The `./doc/book-multi.txt` file in the AsciiDoc distribution. |
|
manpage |
~~~~~~~ |
Used to generate roff format UNIX manual pages. AsciiDoc manpage |
documents observe special header title and section naming conventions |
-- see the <<X1,Manpage Documents>> section for details. |
|
AsciiDoc defines the 'synopsis' <<X93,section markup template>> to |
generate the DocBook `refsynopsisdiv` section. |
|
See also the asciidoc(1) man page source (`./doc/asciidoc.1.txt`) from |
the AsciiDoc distribution. |
|
|
[[X5]] |
AsciiDoc Backends |
----------------- |
The asciidoc(1) command translates an AsciiDoc formatted file to the |
backend format specified by the `-b` (`--backend`) command-line |
option. asciidoc(1) itself has little intrinsic knowledge of backend |
formats, all translation rules are contained in customizable cascading |
configuration files. Backend specific attributes are listed in the |
<<X88,Backend Attributes>> section. |
|
docbook45:: |
Outputs DocBook XML 4.5 markup. |
|
html4:: |
This backend generates plain HTML 4.01 Transitional markup. |
|
xhtml11:: |
This backend generates XHTML 1.1 markup styled with CSS2. Output |
files have an `.html` extension. |
|
html5:: |
This backend generates HTML 5 markup, apart from the inclusion of |
<<X98,audio and video block macros>> it is functionally identical to |
the 'xhtml11' backend. |
|
slidy:: |
Use this backend to generate self-contained |
http://www.w3.org/Talks/Tools/Slidy2/[Slidy] HTML slideshows for |
your web browser from AsciiDoc documents. The Slidy backend is |
documented in the distribution `doc/slidy.txt` file and |
{website}slidy.html[online]. |
|
wordpress:: |
A minor variant of the 'html4' backend to support |
http://srackham.wordpress.com/blogpost1/[blogpost]. |
|
latex:: |
Experimental LaTeX backend. |
|
Backend Aliases |
~~~~~~~~~~~~~~~ |
Backend aliases are alternative names for AsciiDoc backends. AsciiDoc |
comes with two backend aliases: 'html' (aliased to 'xhtml11') and |
'docbook' (aliased to 'docbook45'). |
|
You can assign (or reassign) backend aliases by setting an AsciiDoc |
attribute named like `backend-alias-<alias>` to an AsciiDoc backend |
name. For example, the following backend alias attribute definitions |
appear in the `[attributes]` section of the global `asciidoc.conf` |
configuration file: |
|
backend-alias-html=xhtml11 |
backend-alias-docbook=docbook45 |
|
[[X100]] |
Backend Plugins |
~~~~~~~~~~~~~~~ |
The asciidoc(1) `--backend` option is also used to install and manage |
backend <<X101,plugins>>. |
|
- A backend plugin is used just like the built-in backends. |
- Backend plugins <<X27,take precedence>> over built-in backends with |
the same name. |
- You can use the `{asciidoc-confdir}` <<X60, intrinsic attribute>> to |
refer to the built-in backend configuration file location from |
backend plugin configuration files. |
- You can use the `{backend-confdir}` <<X60, intrinsic attribute>> to |
refer to the backend plugin configuration file location. |
- By default backends plugins are installed in |
`$HOME/.asciidoc/backends/<backend>` where `<backend>` is the |
backend name. |
|
|
DocBook |
------- |
AsciiDoc generates 'article', 'book' and 'refentry' |
http://www.docbook.org/[DocBook] documents (corresponding to the |
AsciiDoc 'article', 'book' and 'manpage' document types). |
|
Most Linux distributions come with conversion tools (collectively |
called a toolchain) for <<X12,converting DocBook files>> to |
presentation formats such as Postscript, HTML, PDF, EPUB, DVI, |
PostScript, LaTeX, roff (the native man page format), HTMLHelp, |
JavaHelp and text. There are also programs that allow you to view |
DocBook files directly, for example http://live.gnome.org/Yelp[Yelp] |
(the GNOME help viewer). |
|
[[X12]] |
Converting DocBook to other file formats |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
DocBook files are validated, parsed and translated various |
presentation file formats using a combination of applications |
collectively called a DocBook 'tool chain'. The function of a tool |
chain is to read the DocBook markup (produced by AsciiDoc) and |
transform it to a presentation format (for example HTML, PDF, HTML |
Help, EPUB, DVI, PostScript, LaTeX). |
|
A wide range of user output format requirements coupled with a choice |
of available tools and stylesheets results in many valid tool chain |
combinations. |
|
[[X43]] |
a2x Toolchain Wrapper |
~~~~~~~~~~~~~~~~~~~~~ |
One of the biggest hurdles for new users is installing, configuring |
and using a DocBook XML toolchain. `a2x(1)` can help -- it's a |
toolchain wrapper command that will generate XHTML (chunked and |
unchunked), PDF, EPUB, DVI, PS, LaTeX, man page, HTML Help and text |
file outputs from an AsciiDoc text file. `a2x(1)` does all the grunt |
work associated with generating and sequencing the toolchain commands |
and managing intermediate and output files. `a2x(1)` also optionally |
deploys admonition and navigation icons and a CSS stylesheet. See the |
`a2x(1)` man page for more details. In addition to `asciidoc(1)` you |
also need <<X40,xsltproc(1)>>, <<X13,DocBook XSL Stylesheets>> and |
optionally: <<X31,dblatex>> or <<X14,FOP>> (to generate PDF); |
`w3m(1)` or `lynx(1)` (to generate text). |
|
The following examples generate `doc/source-highlight-filter.pdf` from |
the AsciiDoc `doc/source-highlight-filter.txt` source file. The first |
example uses `dblatex(1)` (the default PDF generator) the second |
example forces FOP to be used: |
|
$ a2x -f pdf doc/source-highlight-filter.txt |
$ a2x -f pdf --fop doc/source-highlight-filter.txt |
|
See the `a2x(1)` man page for details. |
|
TIP: Use the `--verbose` command-line option to view executed |
toolchain commands. |
|
HTML generation |
~~~~~~~~~~~~~~~ |
AsciiDoc produces nicely styled HTML directly without requiring a |
DocBook toolchain but there are also advantages in going the DocBook |
route: |
|
- HTML from DocBook can optionally include automatically generated |
indexes, tables of contents, footnotes, lists of figures and tables. |
- DocBook toolchains can also (optionally) generate separate (chunked) |
linked HTML pages for each document section. |
- Toolchain processing performs link and document validity checks. |
- If the DocBook 'lang' attribute is set then things like table of |
contents, figure and table captions and admonition captions will be |
output in the specified language (setting the AsciiDoc 'lang' |
attribute sets the DocBook 'lang' attribute). |
|
On the other hand, HTML output directly from AsciiDoc is much faster, |
is easily customized and can be used in situations where there is no |
suitable DocBook toolchain (for example, see the {website}[AsciiDoc |
website]). |
|
PDF generation |
~~~~~~~~~~~~~~ |
There are two commonly used tools to generate PDFs from DocBook, |
<<X31,dblatex>> and <<X14,FOP>>. |
|
.dblatex or FOP? |
- 'dblatex' is easier to install, there's zero configuration |
required and no Java VM to install -- it just works out of the box. |
- 'dblatex' source code highlighting and numbering is superb. |
- 'dblatex' is easier to use as it converts DocBook directly to PDF |
whereas before using 'FOP' you have to convert DocBook to XML-FO |
using <<X13,DocBook XSL Stylesheets>>. |
- 'FOP' is more feature complete (for example, callouts are processed |
inside literal layouts) and arguably produces nicer looking output. |
|
HTML Help generation |
~~~~~~~~~~~~~~~~~~~~ |
. Convert DocBook XML documents to HTML Help compiler source files |
using <<X13,DocBook XSL Stylesheets>> and <<X40,xsltproc(1)>>. |
. Convert the HTML Help source (`.hhp` and `.html`) files to HTML Help |
(`.chm`) files using the <<X67,Microsoft HTML Help Compiler>>. |
|
Toolchain components summary |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
AsciiDoc:: |
Converts AsciiDoc (`.txt`) files to DocBook XML (`.xml`) files. |
|
[[X13]]http://docbook.sourceforge.net/projects/xsl/[DocBook XSL Stylesheets]:: |
These are a set of XSL stylesheets containing rules for converting |
DocBook XML documents to HTML, XSL-FO, manpage and HTML Help files. |
The stylesheets are used in conjunction with an XML parser such as |
<<X40,xsltproc(1)>>. |
|
[[X40]]http://www.xmlsoft.org[xsltproc]:: |
An XML parser for applying XSLT stylesheets (in our case the |
<<X13,DocBook XSL Stylesheets>>) to XML documents. |
|
[[X31]]http://dblatex.sourceforge.net/[dblatex]:: |
Generates PDF, DVI, PostScript and LaTeX formats directly from |
DocBook source via the intermediate LaTeX typesetting language -- |
uses <<X13,DocBook XSL Stylesheets>>, <<X40,xsltproc(1)>> and |
`latex(1)`. |
|
[[X14]]http://xml.apache.org/fop/[FOP]:: |
The Apache Formatting Objects Processor converts XSL-FO (`.fo`) |
files to PDF files. The XSL-FO files are generated from DocBook |
source files using <<X13,DocBook XSL Stylesheets>> and |
<<X40,xsltproc(1)>>. |
|
[[X67]]Microsoft Help Compiler:: |
The Microsoft HTML Help Compiler (`hhc.exe`) is a command-line tool |
that converts HTML Help source files to a single HTML Help (`.chm`) |
file. It runs on MS Windows platforms and can be downloaded from |
http://www.microsoft.com. |
|
AsciiDoc dblatex configuration files |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
The AsciiDoc distribution `./dblatex` directory contains |
`asciidoc-dblatex.xsl` (customized XSL parameter settings) and |
`asciidoc-dblatex.sty` (customized LaTeX settings). These are examples |
of optional <<X31,dblatex>> output customization and are used by |
<<X43,a2x(1)>>. |
|
AsciiDoc DocBook XSL Stylesheets drivers |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
You will have noticed that the distributed HTML and HTML Help |
documentation files (for example `./doc/asciidoc.html`) are not the |
plain outputs produced using the default 'DocBook XSL Stylesheets' |
configuration. This is because they have been processed using |
customized DocBook XSL Stylesheets along with (in the case of HTML |
outputs) the custom `./stylesheets/docbook-xsl.css` CSS stylesheet. |
|
You'll find the customized DocBook XSL drivers along with additional |
documentation in the distribution `./docbook-xsl` directory. The |
examples that follow are executed from the distribution documentation |
(`./doc`) directory. These drivers are also used by <<X43,a2x(1)>>. |
|
`common.xsl`:: |
Shared driver parameters. This file is not used directly but is |
included in all the following drivers. |
|
`chunked.xsl`:: |
Generate chunked XHTML (separate HTML pages for each document |
section) in the `./doc/chunked` directory. For example: |
|
$ python ../asciidoc.py -b docbook asciidoc.txt |
$ xsltproc --nonet ../docbook-xsl/chunked.xsl asciidoc.xml |
|
`epub.xsl`:: |
Used by <<X43,a2x(1)>> to generate EPUB formatted documents. |
|
`fo.xsl`:: |
Generate XSL Formatting Object (`.fo`) files for subsequent PDF |
file generation using FOP. For example: |
|
$ python ../asciidoc.py -b docbook article.txt |
$ xsltproc --nonet ../docbook-xsl/fo.xsl article.xml > article.fo |
$ fop article.fo article.pdf |
|
`htmlhelp.xsl`:: |
Generate Microsoft HTML Help source files for the MS HTML Help |
Compiler in the `./doc/htmlhelp` directory. This example is run on |
MS Windows from a Cygwin shell prompt: |
|
$ python ../asciidoc.py -b docbook asciidoc.txt |
$ xsltproc --nonet ../docbook-xsl/htmlhelp.xsl asciidoc.xml |
$ c:/Program\ Files/HTML\ Help\ Workshop/hhc.exe htmlhelp.hhp |
|
`manpage.xsl`:: |
Generate a `roff(1)` format UNIX man page from a DocBook XML |
'refentry' document. This example generates an `asciidoc.1` man |
page file: |
|
$ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt |
$ xsltproc --nonet ../docbook-xsl/manpage.xsl asciidoc.1.xml |
|
`xhtml.xsl`:: |
Convert a DocBook XML file to a single XHTML file. For example: |
|
$ python ../asciidoc.py -b docbook asciidoc.txt |
$ xsltproc --nonet ../docbook-xsl/xhtml.xsl asciidoc.xml > asciidoc.html |
|
If you want to see how the complete documentation set is processed |
take a look at the A-A-P script `./doc/main.aap`. |
|
|
Generating Plain Text Files |
--------------------------- |
AsciiDoc does not have a text backend (for most purposes AsciiDoc |
source text is fine), however you can convert AsciiDoc text files to |
formatted text using the AsciiDoc <<X43,a2x(1)>> toolchain wrapper |
utility. |
|
|
[[X35]] |
HTML5 and XHTML 1.1 |
------------------- |
The 'xhtml11' and 'html5' backends embed or link CSS and JavaScript |
files in their outputs, there is also a <<X99,themes>> plugin |
framework. |
|
- If the AsciiDoc 'linkcss' attribute is defined then CSS and |
JavaScript files are linked to the output document, otherwise they |
are embedded (the default behavior). |
- The default locations for CSS and JavaScript files can be changed by |
setting the AsciiDoc 'stylesdir' and 'scriptsdir' attributes |
respectively. |
- The default locations for embedded and linked files differ and are |
calculated at different times -- embedded files are loaded when |
asciidoc(1) generates the output document, linked files are loaded |
by the browser when the user views the output document. |
- Embedded files are automatically inserted in the output files but |
you need to manually copy linked CSS and Javascript files from |
AsciiDoc <<X27,configuration directories>> to the correct location |
relative to the output document. |
|
.Stylesheet file locations |
[cols="3*",frame="topbot",options="header"] |
|==================================================================== |
|'stylesdir' attribute |
|Linked location ('linkcss' attribute defined) |
|Embedded location ('linkcss' attribute undefined) |
|
|Undefined (default). |
|Same directory as the output document. |
|`stylesheets` subdirectory in the AsciiDoc configuration directory |
(the directory containing the backend conf file). |
|
|Absolute or relative directory name. |
|Absolute or relative to the output document. |
|Absolute or relative to the AsciiDoc configuration directory (the |
directory containing the backend conf file). |
|
|==================================================================== |
|
.JavaScript file locations |
[cols="3*",frame="topbot",options="header"] |
|==================================================================== |
|'scriptsdir' attribute |
|Linked location ('linkcss' attribute defined) |
|Embedded location ('linkcss' attribute undefined) |
|
|Undefined (default). |
|Same directory as the output document. |
|`javascripts` subdirectory in the AsciiDoc configuration directory |
(the directory containing the backend conf file). |
|
|Absolute or relative directory name. |
|Absolute or relative to the output document. |
|Absolute or relative to the AsciiDoc configuration directory (the |
directory containing the backend conf file). |
|
|==================================================================== |
|
[[X99]] |
Themes |
~~~~~~ |
The AsciiDoc 'theme' attribute is used to select an alternative CSS |
stylesheet and to optionally include additional JavaScript code. |
|
- Theme files reside in an AsciiDoc <<X27,configuration directory>> |
named `themes/<theme>/` (where `<theme>` is the the theme name set |
by the 'theme' attribute). asciidoc(1) sets the 'themedir' attribute |
to the theme directory path name. |
- The 'theme' attribute can also be set using the asciidoc(1) |
`--theme` option, the `--theme` option can also be used to manage |
theme <<X101,plugins>>. |
- AsciiDoc ships with two themes: 'flask' and 'volnitsky'. |
- The `<theme>.css` file replaces the default `asciidoc.css` CSS file. |
- The `<theme>.js` file is included in addition to the default |
`asciidoc.js` JavaScript file. |
- If the <<X66,data-uri>> attribute is defined then icons are loaded |
from the theme `icons` sub-directory if it exists (i.e. the |
'iconsdir' attribute is set to theme `icons` sub-directory path). |
- Embedded theme files are automatically inserted in the output files |
but you need to manually copy linked CSS and Javascript files to the |
location of the output documents. |
- Linked CSS and JavaScript theme files are linked to the same linked |
locations as <<X35,other CSS and JavaScript files>>. |
|
For example, the command-line option `--theme foo` (or `--attribute |
theme=foo`) will cause asciidoc(1) to search <<"X27","configuration |
file locations 1, 2 and 3">> for a sub-directory called `themes/foo` |
containing the stylesheet `foo.css` and optionally a JavaScript file |
name `foo.js`. |
|
|
Document Structure |
------------------ |
An AsciiDoc document consists of a series of <<X8,block elements>> |
starting with an optional document Header, followed by an optional |
Preamble, followed by zero or more document Sections. |
|
Almost any combination of zero or more elements constitutes a valid |
AsciiDoc document: documents can range from a single sentence to a |
multi-part book. |
|
Block Elements |
~~~~~~~~~~~~~~ |
Block elements consist of one or more lines of text and may contain |
other block elements. |
|
The AsciiDoc block structure can be informally summarized as follows |
footnote:[This is a rough structural guide, not a rigorous syntax |
definition]: |
|
Document ::= (Header?,Preamble?,Section*) |
Header ::= (Title,(AuthorInfo,RevisionInfo?)?) |
AuthorInfo ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?) |
RevisionInfo ::= (RevisionNumber?,RevisionDate,RevisionRemark?) |
Preamble ::= (SectionBody) |
Section ::= (Title,SectionBody?,(Section)*) |
SectionBody ::= ((BlockTitle?,Block)|BlockMacro)+ |
Block ::= (Paragraph|DelimitedBlock|List|Table) |
List ::= (BulletedList|NumberedList|LabeledList|CalloutList) |
BulletedList ::= (ListItem)+ |
NumberedList ::= (ListItem)+ |
CalloutList ::= (ListItem)+ |
LabeledList ::= (ListEntry)+ |
ListEntry ::= (ListLabel,ListItem) |
ListLabel ::= (ListTerm+) |
ListItem ::= (ItemText,(List|ListParagraph|ListContinuation)*) |
|
Where: |
|
- '?' implies zero or one occurrence, '+' implies one or more |
occurrences, '*' implies zero or more occurrences. |
- All block elements are separated by line boundaries. |
- `BlockId`, `AttributeEntry` and `AttributeList` block elements (not |
shown) can occur almost anywhere. |
- There are a number of document type and backend specific |
restrictions imposed on the block syntax. |
- The following elements cannot contain blank lines: Header, Title, |
Paragraph, ItemText. |
- A ListParagraph is a Paragraph with its 'listelement' option set. |
- A ListContinuation is a <<X15,list continuation element>>. |
|
[[X95]] |
Header |
~~~~~~ |
The Header contains document meta-data, typically title plus optional |
authorship and revision information: |
|
- The Header is optional, but if it is used it must start with a |
document <<X17,title>>. |
- Optional Author and Revision information immediately follows the |
header title. |
- The document header must be separated from the remainder of the |
document by one or more blank lines and cannot contain blank lines. |
- The header can include comments. |
- The header can include <<X18,attribute entries>>, typically |
'doctype', 'lang', 'encoding', 'icons', 'data-uri', 'toc', |
'numbered'. |
- Header attributes are overridden by command-line attributes. |
- If the header contains non-UTF-8 characters then the 'encoding' must |
precede the header (either in the document or on the command-line). |
|
Here's an example AsciiDoc document header: |
|
Writing Documentation using AsciiDoc |
==================================== |
Joe Bloggs <jbloggs@mymail.com> |
v2.0, February 2003: |
Rewritten for version 2 release. |
|
The author information line contains the author's name optionally |
followed by the author's email address. The author's name is formatted |
like: |
|
firstname[ [middlename ]lastname][ <email>]] |
|
i.e. a first name followed by optional middle and last names followed |
by an email address in that order. Multi-word first, middle and last |
names can be entered using the underscore as a word separator. The |
email address comes last and must be enclosed in angle <> brackets. |
Here a some examples of author information lines: |
|
Joe Bloggs <jbloggs@mymail.com> |
Joe Bloggs |
Vincent Willem van_Gogh |
|
If the author line does not match the above specification then the |
entire author line is treated as the first name. |
|
The optional revision information line follows the author information |
line. The revision information can be one of two formats: |
|
. An optional document revision number followed by an optional |
revision date followed by an optional revision remark: |
+ |
-- |
* If the revision number is specified it must be followed by a |
comma. |
* The revision number must contain at least one numeric character. |
* Any non-numeric characters preceding the first numeric character |
will be dropped. |
* If a revision remark is specified it must be preceded by a colon. |
The revision remark extends from the colon up to the next blank |
line, attribute entry or comment and is subject to normal text |
substitutions. |
* If a revision number or remark has been set but the revision date |
has not been set then the revision date is set to the value of the |
'docdate' attribute. |
|
Examples: |
|
v2.0, February 2003 |
February 2003 |
v2.0, |
v2.0, February 2003: Rewritten for version 2 release. |
February 2003: Rewritten for version 2 release. |
v2.0,: Rewritten for version 2 release. |
:Rewritten for version 2 release. |
-- |
|
. The revision information line can also be an RCS/CVS/SVN $Id$ |
marker: |
+ |
-- |
* AsciiDoc extracts the 'revnumber', 'revdate', and 'author' |
attributes from the $Id$ revision marker and displays them in the |
document header. |
* If an $Id$ revision marker is used the header author line can be |
omitted. |
|
Example: |
|
$Id: mydoc.txt,v 1.5 2009/05/17 17:58:44 jbloggs Exp $ |
-- |
|
You can override or set header parameters by passing 'revnumber', |
'revremark', 'revdate', 'email', 'author', 'authorinitials', |
'firstname' and 'lastname' attributes using the asciidoc(1) `-a` |
(`--attribute`) command-line option. For example: |
|
$ asciidoc -a revdate=2004/07/27 article.txt |
|
Attribute entries can also be added to the header for substitution in |
the header template with <<X18,Attribute Entry>> elements. |
|
The 'title' element in HTML outputs is set to the AsciiDoc document |
title, you can set it to a different value by including a 'title' |
attribute entry in the document header. |
|
[[X87]] |
Additional document header information |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
AsciiDoc has two mechanisms for optionally including additional |
meta-data in the header of the output document: |
|
'docinfo' configuration file sections:: |
If a <<X7,configuration file>> section named 'docinfo' has been loaded |
then it will be included in the document header. Typically the |
'docinfo' section name will be prefixed with a '+' character so that it |
is appended to (rather than replace) other 'docinfo' sections. |
|
'docinfo' files:: |
Two docinfo files are recognized: one named `docinfo` and a second |
named like the AsciiDoc source file with a `-docinfo` suffix. For |
example, if the source document is called `mydoc.txt` then the |
document information files would be `docinfo.xml` and |
`mydoc-docinfo.xml` (for DocBook outputs) and `docinfo.html` and |
`mydoc-docinfo.html` (for HTML outputs). The <<X97,docinfo, docinfo1 |
and docinfo2>> attributes control which docinfo files are included in |
the output files. |
|
The contents docinfo templates and files is dependent on the type of |
output: |
|
HTML:: |
Valid 'head' child elements. Typically 'style' and 'script' elements |
for CSS and JavaScript inclusion. |
|
DocBook:: |
Valid 'articleinfo' or 'bookinfo' child elements. DocBook defines |
numerous elements for document meta-data, for example: copyrights, |
document history and authorship information. See the DocBook |
`./doc/article-docinfo.xml` example that comes with the AsciiDoc |
distribution. The rendering of meta-data elements (or not) is |
DocBook processor dependent. |
|
|
[[X86]] |
Preamble |
~~~~~~~~ |
The Preamble is an optional untitled section body between the document |
Header and the first Section title. |
|
Sections |
~~~~~~~~ |
In addition to the document title (level 0), AsciiDoc supports four |
section levels: 1 (top) to 4 (bottom). Section levels are delimited |
by section <<X17,titles>>. Sections are translated using |
configuration file <<X93,section markup templates>>. AsciiDoc |
generates the following <<X60,intrinsic attributes>> specifically for |
use in section markup templates: |
|
level:: |
The `level` attribute is the section level number, it is normally just |
the <<X17,title>> level number (1..4). However, if the `leveloffset` |
attribute is defined it will be added to the `level` attribute. The |
`leveloffset` attribute is useful for <<X90,combining documents>>. |
|
sectnum:: |
The `-n` (`--section-numbers`) command-line option generates the |
`sectnum` (section number) attribute. The `sectnum` attribute is used |
for section numbers in HTML outputs (DocBook section numbering are |
handled automatically by the DocBook toolchain commands). |
|
[[X93]] |
Section markup templates |
^^^^^^^^^^^^^^^^^^^^^^^^ |
Section markup templates specify output markup and are defined in |
AsciiDoc configuration files. Section markup template names are |
derived as follows (in order of precedence): |
|
1. From the title's first positional attribute or 'template' |
attribute. For example, the following three section titles are |
functionally equivalent: |
+ |
..................................................................... |
[[terms]] |
[glossary] |
List of Terms |
------------- |
|
["glossary",id="terms"] |
List of Terms |
------------- |
|
[template="glossary",id="terms"] |
List of Terms |
------------- |
..................................................................... |
|
2. When the title text matches a configuration file |
<<X16,`[specialsections]`>> entry. |
3. If neither of the above the default `sect<level>` template is used |
(where `<level>` is a number from 1 to 4). |
|
In addition to the normal section template names ('sect1', 'sect2', |
'sect3', 'sect4') AsciiDoc has the following templates for |
frontmatter, backmatter and other special sections: 'abstract', |
'preface', 'colophon', 'dedication', 'glossary', 'bibliography', |
'synopsis', 'appendix', 'index'. These special section templates |
generate the corresponding Docbook elements; for HTML outputs they |
default to the 'sect1' section template. |
|
Section IDs |
^^^^^^^^^^^ |
If no explicit section ID is specified an ID will be synthesised from |
the section title. The primary purpose of this feature is to ensure |
persistence of table of contents links (permalinks): the missing |
section IDs are generated dynamically by the JavaScript TOC generator |
*after* the page is loaded. If you link to a dynamically generated TOC |
address the page will load but the browser will ignore the (as yet |
ungenerated) section ID. |
|
The IDs are generated by the following algorithm: |
|
- Replace all non-alphanumeric title characters with underscores. |
- Strip leading or trailing underscores. |
- Convert to lowercase. |
- Prepend the `idprefix` attribute (so there's no possibility of name |
clashes with existing document IDs). Prepend an underscore if the |
`idprefix` attribute is not defined. |
- A numbered suffix (`_2`, `_3` ...) is added if a same named |
auto-generated section ID exists. |
- If the `ascii-ids` attribute is defined then non-ASCII characters |
are replaced with ASCII equivalents. This attribute may be |
deprecated in future releases and *should be avoided*, it's sole |
purpose is to accommodate deficient downstream applications that |
cannot process non-ASCII ID attributes. |
|
Example: the title 'Jim's House' would generate the ID `_jim_s_house`. |
|
Section ID synthesis can be disabled by undefining the `sectids` |
attribute. |
|
[[X16]] |
Special Section Titles |
^^^^^^^^^^^^^^^^^^^^^^ |
AsciiDoc has a mechanism for mapping predefined section titles |
auto-magically to specific markup templates. For example a title |
'Appendix A: Code Reference' will automatically use the 'appendix' |
<<X93,section markup template>>. The mappings from title to template |
name are specified in `[specialsections]` sections in the Asciidoc |
language configuration files (`lang-*.conf`). Section entries are |
formatted like: |
|
<title>=<template> |
|
`<title>` is a Python regular expression and `<template>` is the name |
of a configuration file markup template section. If the `<title>` |
matches an AsciiDoc document section title then the backend output is |
marked up using the `<template>` markup template (instead of the |
default `sect<level>` section template). The `{title}` attribute value |
is set to the value of the matched regular expression group named |
'title', if there is no 'title' group `{title}` defaults to the whole |
of the AsciiDoc section title. If `<template>` is blank then any |
existing entry with the same `<title>` will be deleted. |
|
.Special section titles vs. explicit template names |
********************************************************************* |
AsciiDoc has two mechanisms for specifying non-default section markup |
templates: you can specify the template name explicitly (using the |
'template' attribute) or indirectly (using 'special section titles'). |
Specifying a <<X93,section template>> attribute explicitly is |
preferred. Auto-magical 'special section titles' have the following |
drawbacks: |
|
- They are non-obvious, you have to know the exact matching |
title for each special section on a language by language basis. |
- Section titles are predefined and can only be customised with a |
configuration change. |
- The implementation is complicated by multiple languages: every |
special section title has to be defined for each language (in each |
of the `lang-*.conf` files). |
|
Specifying special section template names explicitly does add more |
noise to the source document (the 'template' attribute declaration), |
but the intention is obvious and the syntax is consistent with other |
AsciiDoc elements c.f. bibliographic, Q&A and glossary lists. |
|
Special section titles have been deprecated but are retained for |
backward compatibility. |
|
********************************************************************* |
|
Inline Elements |
~~~~~~~~~~~~~~~ |
<<X34,Inline document elements>> are used to format text and to |
perform various types of text substitution. Inline elements and inline |
element syntax is defined in the asciidoc(1) configuration files. |
|
Here is a list of AsciiDoc inline elements in the (default) order in |
which they are processed: |
|
Special characters:: |
These character sequences escape special characters used by |
the backend markup (typically `<`, `>`, and `&` characters). |
See `[specialcharacters]` configuration file sections. |
|
Quotes:: |
Elements that markup words and phrases; usually for character |
formatting. See `[quotes]` configuration file sections. |
|
Special Words:: |
Word or word phrase patterns singled out for markup without |
the need for further annotation. See `[specialwords]` |
configuration file sections. |
|
Replacements:: |
Each replacement defines a word or word phrase pattern to |
search for along with corresponding replacement text. See |
`[replacements]` configuration file sections. |
|
Attribute references:: |
Document attribute names enclosed in braces are replaced by |
the corresponding attribute value. |
|
Inline Macros:: |
Inline macros are replaced by the contents of parametrized |
configuration file sections. |
|
|
Document Processing |
------------------- |
The AsciiDoc source document is read and processed as follows: |
|
1. The document 'Header' is parsed, header parameter values are |
substituted into the configuration file `[header]` template section |
which is then written to the output file. |
2. Each document 'Section' is processed and its constituent elements |
translated to the output file. |
3. The configuration file `[footer]` template section is substituted |
and written to the output file. |
|
When a block element is encountered asciidoc(1) determines the type of |
block by checking in the following order (first to last): (section) |
Titles, BlockMacros, Lists, DelimitedBlocks, Tables, AttributeEntrys, |
AttributeLists, BlockTitles, Paragraphs. |
|
The default paragraph definition `[paradef-default]` is last element |
to be checked. |
|
Knowing the parsing order will help you devise unambiguous macro, list |
and block syntax rules. |
|
Inline substitutions within block elements are performed in the |
following default order: |
|
1. Special characters |
2. Quotes |
3. Special words |
4. Replacements |
5. Attributes |
6. Inline Macros |
7. Replacements2 |
|
The substitutions and substitution order performed on |
Title, Paragraph and DelimitedBlock elements is determined by |
configuration file parameters. |
|
|
Text Formatting |
--------------- |
[[X51]] |
Quoted Text |
~~~~~~~~~~~ |
Words and phrases can be formatted by enclosing inline text with |
quote characters: |
|
_Emphasized text_:: |
Word phrases \'enclosed in single quote characters' (acute |
accents) or \_underline characters_ are emphasized. |
|
*Strong text*:: |
Word phrases \*enclosed in asterisk characters* are rendered |
in a strong font (usually bold). |
|
[[X81]]+Monospaced text+:: |
Word phrases \+enclosed in plus characters+ are rendered in a |
monospaced font. Word phrases \`enclosed in backtick |
characters` (grave accents) are also rendered in a monospaced |
font but in this case the enclosed text is rendered literally |
and is not subject to further expansion (see <<X80,inline |
literal passthrough>>). |
|
`Single quoted text':: |
Phrases enclosed with a \`single grave accent to the left and |
a single acute accent to the right' are rendered in single |
quotation marks. |
|
``Double quoted text'':: |
Phrases enclosed with \\``two grave accents to the left and |
two acute accents to the right'' are rendered in quotation |
marks. |
|
#Unquoted text#:: |
Placing \#hashes around text# does nothing, it is a mechanism |
to allow inline attributes to be applied to otherwise |
unformatted text. |
|
New quote types can be defined by editing asciidoc(1) configuration |
files. See the <<X7,Configuration Files>> section for details. |
|
.Quoted text behavior |
- Quoting cannot be overlapped. |
- Different quoting types can be nested. |
- To suppress quoted text formatting place a backslash character |
immediately in front of the leading quote character(s). In the case |
of ambiguity between escaped and non-escaped text you will need to |
escape both leading and trailing quotes, in the case of |
multi-character quotes you may even need to escape individual |
characters. |
|
[[X96]] |
Quoted text attributes |
^^^^^^^^^^^^^^^^^^^^^^ |
Quoted text can be prefixed with an <<X21,attribute list>>. The first |
positional attribute ('role' attribute) is translated by AsciiDoc to |
an HTML 'span' element 'class' attribute or a DocBook 'phrase' element |
'role' attribute. |
|
DocBook XSL Stylesheets translate DocBook 'phrase' elements with |
'role' attributes to corresponding HTML 'span' elements with the same |
'class' attributes; CSS can then be used |
http://www.sagehill.net/docbookxsl/UsingCSS.html[to style the |
generated HTML]. Thus CSS styling can be applied to both DocBook and |
AsciiDoc generated HTML outputs. You can also specify multiple class |
names separated by spaces. |
|
CSS rules for text color, text background color, text size and text |
decorators are included in the distributed AsciiDoc CSS files and are |
used in conjunction with AsciiDoc 'xhtml11', 'html5' and 'docbook' |
outputs. The CSS class names are: |
|
- '<color>' (text foreground color). |
- '<color>-background' (text background color). |
- 'big' and 'small' (text size). |
- 'underline', 'overline' and 'line-through' (strike through) text |
decorators. |
|
Where '<color>' can be any of the |
http://en.wikipedia.org/wiki/Web_colors#HTML_color_names[sixteen HTML |
color names]. Examples: |
|
[red]#Obvious# and [big red yellow-background]*very obvious*. |
|
[underline]#Underline text#, [overline]#overline text# and |
[blue line-through]*bold blue and line-through*. |
|
is rendered as: |
|
[red]#Obvious# and [big red yellow-background]*very obvious*. |
|
[underline]#Underline text#, [overline]#overline text# and |
[bold blue line-through]*bold blue and line-through*. |
|
NOTE: Color and text decorator attributes are rendered for XHTML and |
HTML 5 outputs using CSS stylesheets. The mechanism to implement |
color and text decorator attributes is provided for DocBook toolchains |
via the DocBook 'phrase' element 'role' attribute, but the actual |
rendering is toolchain specific and is not part of the AsciiDoc |
distribution. |
|
[[X52]] |
Constrained and Unconstrained Quotes |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
There are actually two types of quotes: |
|
Constrained quotes |
++++++++++++++++++ |
Quoted must be bounded by white space or commonly adjoining |
punctuation characters. These are the most commonly used type of |
quote. |
|
Unconstrained quotes |
++++++++++++++++++++ |
Unconstrained quotes have no boundary constraints and can be placed |
anywhere within inline text. For consistency and to make them easier |
to remember unconstrained quotes are double-ups of the `_`, `*`, `+` |
and `#` constrained quotes: |
|
__unconstrained emphasized text__ |
**unconstrained strong text** |
++unconstrained monospaced text++ |
##unconstrained unquoted text## |
|
The following example emboldens the letter F: |
|
**F**ile Open... |
|
Superscripts and Subscripts |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Put \^carets on either^ side of the text to be superscripted, put |
\~tildes on either side~ of text to be subscripted. For example, the |
following line: |
|
e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^ |
and ~some sub text~ |
|
Is rendered like: |
|
e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^ |
and ~some sub text~ |
|
Superscripts and subscripts are implemented as <<X52,unconstrained |
quotes>> and they can be escaped with a leading backslash and prefixed |
with with an attribute list. |
|
Line Breaks |
~~~~~~~~~~~ |
A plus character preceded by at least one space character at the end |
of a non-blank line forces a line break. It generates a line break |
(`br`) tag for HTML outputs and a custom XML `asciidoc-br` processing |
instruction for DocBook outputs. The `asciidoc-br` processing |
instruction is handled by <<X43,a2x(1)>>. |
|
Page Breaks |
~~~~~~~~~~~ |
A line of three or more less-than (`<<<`) characters will generate a |
hard page break in DocBook and printed HTML outputs. It uses the CSS |
`page-break-after` property for HTML outputs and a custom XML |
`asciidoc-pagebreak` processing instruction for DocBook outputs. The |
`asciidoc-pagebreak` processing instruction is handled by |
<<X43,a2x(1)>>. Hard page breaks are sometimes handy but as a general |
rule you should let your page processor generate page breaks for you. |
|
Rulers |
~~~~~~ |
A line of three or more apostrophe characters will generate a ruler |
line. It generates a ruler (`hr`) tag for HTML outputs and a custom |
XML `asciidoc-hr` processing instruction for DocBook outputs. The |
`asciidoc-hr` processing instruction is handled by <<X43,a2x(1)>>. |
|
Tabs |
~~~~ |
By default tab characters input files will translated to 8 spaces. Tab |
expansion is set with the 'tabsize' entry in the configuration file |
`[miscellaneous]` section and can be overridden in included files by |
setting a 'tabsize' attribute in the `include` macro's attribute list. |
For example: |
|
include::addendum.txt[tabsize=2] |
|
The tab size can also be set using the attribute command-line option, |
for example `--attribute tabsize=4` |
|
Replacements |
~~~~~~~~~~~~ |
The following replacements are defined in the default AsciiDoc |
configuration: |
|
(C) copyright, (TM) trademark, (R) registered trademark, |
-- em dash, ... ellipsis, -> right arrow, <- left arrow, => right |
double arrow, <= left double arrow. |
|
Which are rendered as: |
|
(C) copyright, (TM) trademark, (R) registered trademark, |
-- em dash, ... ellipsis, -> right arrow, <- left arrow, => right |
double arrow, <= left double arrow. |
|
You can also include arbitrary entity references in the AsciiDoc |
source. Examples: |
|
➊ ¶ |
|
renders: |
|
➊ ¶ |
|
To render a replacement literally escape it with a leading back-slash. |
|
The <<X7,Configuration Files>> section explains how to configure your |
own replacements. |
|
Special Words |
~~~~~~~~~~~~~ |
Words defined in `[specialwords]` configuration file sections are |
automatically marked up without having to be explicitly notated. |
|
The <<X7,Configuration Files>> section explains how to add and replace |
special words. |
|
|
[[X17]] |
Titles |
------ |
Document and section titles can be in either of two formats: |
|
Two line titles |
~~~~~~~~~~~~~~~ |
A two line title consists of a title line, starting hard against the |
left margin, and an underline. Section underlines consist a repeated |
character pairs spanning the width of the preceding title (give or |
take up to two characters): |
|
The default title underlines for each of the document levels are: |
|
|
Level 0 (top level): ====================== |
Level 1: ---------------------- |
Level 2: ~~~~~~~~~~~~~~~~~~~~~~ |
Level 3: ^^^^^^^^^^^^^^^^^^^^^^ |
Level 4 (bottom level): ++++++++++++++++++++++ |
|
Examples: |
|
Level One Section Title |
----------------------- |
|
Level 2 Subsection Title |
~~~~~~~~~~~~~~~~~~~~~~~~ |
|
[[X46]] |
One line titles |
~~~~~~~~~~~~~~~ |
One line titles consist of a single line delimited on either side by |
one or more equals characters (the number of equals characters |
corresponds to the section level minus one). Here are some examples: |
|
= Document Title (level 0) = |
== Section title (level 1) == |
=== Section title (level 2) === |
==== Section title (level 3) ==== |
===== Section title (level 4) ===== |
|
[NOTE] |
===================================================================== |
- One or more spaces must fall between the title and the delimiters. |
- The trailing title delimiter is optional. |
- The one-line title syntax can be changed by editing the |
configuration file `[titles]` section `sect0`...`sect4` entries. |
===================================================================== |
|
Floating titles |
~~~~~~~~~~~~~~~ |
Setting the title's first positional attribute or 'style' attribute to |
'float' generates a free-floating title. A free-floating title is |
rendered just like a normal section title but is not formally |
associated with a text body and is not part of the regular section |
hierarchy so the normal ordering rules do not apply. Floating titles |
can also be used in contexts where section titles are illegal: for |
example sidebar and admonition blocks. Example: |
|
[float] |
The second day |
~~~~~~~~~~~~~~ |
|
Floating titles do not appear in a document's table of contents. |
|
|
[[X42]] |
Block Titles |
------------ |
A 'BlockTitle' element is a single line beginning with a period |
followed by the title text. A BlockTitle is applied to the immediately |
following Paragraph, DelimitedBlock, List, Table or BlockMacro. For |
example: |
|
........................ |
.Notes |
- Note 1. |
- Note 2. |
........................ |
|
is rendered as: |
|
.Notes |
- Note 1. |
- Note 2. |
|
|
[[X41]] |
BlockId Element |
--------------- |
A 'BlockId' is a single line block element containing a unique |
identifier enclosed in double square brackets. It is used to assign an |
identifier to the ensuing block element. For example: |
|
[[chapter-titles]] |
Chapter titles can be ... |
|
The preceding example identifies the ensuing paragraph so it can be |
referenced from other locations, for example with |
`<<chapter-titles,chapter titles>>`. |
|
'BlockId' elements can be applied to Title, Paragraph, List, |
DelimitedBlock, Table and BlockMacro elements. The BlockId element |
sets the `{id}` attribute for substitution in the subsequent block's |
markup template. If a second positional argument is supplied it sets |
the `{reftext}` attribute which is used to set the DocBook `xreflabel` |
attribute. |
|
The 'BlockId' element has the same syntax and serves the same function |
to the <<X30,anchor inline macro>>. |
|
[[X79]] |
AttributeList Element |
--------------------- |
An 'AttributeList' block element is an <<X21,attribute list>> on a |
line by itself: |
|
- 'AttributeList' attributes are only applied to the immediately |
following block element -- the attributes are made available to the |
block's markup template. |
- Multiple contiguous 'AttributeList' elements are additively combined |
in the order they appear.. |
- The first positional attribute in the list is often used to specify |
the ensuing element's <<X23,style>>. |
|
Attribute value substitution |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
By default, only substitutions that take place inside attribute list |
values are attribute references, this is because not all attributes |
are destined to be marked up and rendered as text (for example the |
table 'cols' attribute). To perform normal inline text substitutions |
(special characters, quotes, macros, replacements) on an attribute |
value you need to enclose it in single quotes. In the following quote |
block the second attribute value in the AttributeList is quoted to |
ensure the 'http' macro is expanded to a hyperlink. |
|
--------------------------------------------------------------------- |
[quote,'http://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]'] |
_____________________________________________________________________ |
Sir, a woman's preaching is like a dog's walking on his hind legs. It |
is not done well; but you are surprised to find it done at all. |
_____________________________________________________________________ |
--------------------------------------------------------------------- |
|
Common attributes |
~~~~~~~~~~~~~~~~~ |
Most block elements support the following attributes: |
|
[cols="1e,1,5a",frame="topbot",options="header"] |
|==================================================================== |
|Name |Backends |Description |
|
|id |html4, html5, xhtml11, docbook | |
Unique identifier typically serve as link targets. |
Can also be set by the 'BlockId' element. |
|
|role |html4, html5, xhtml11, docbook | |
Role contains a string used to classify or subclassify an element and |
can be applied to AsciiDoc block elements. The AsciiDoc 'role' |
attribute is translated to the 'role' attribute in DocBook outputs and |
is included in the 'class' attribute in HTML outputs, in this respect |
it behaves like the <<X96,quoted text role attribute>>. |
|
DocBook XSL Stylesheets translate DocBook 'role' attributes to HTML |
'class' attributes; CSS can then be used |
http://www.sagehill.net/docbookxsl/UsingCSS.html[to style the |
generated HTML]. |
|
|reftext |docbook | |
'reftext' is used to set the DocBook 'xreflabel' attribute. |
The 'reftext' attribute can an also be set by the 'BlockId' element. |
|
|==================================================================== |
|
|
Paragraphs |
---------- |
Paragraphs are blocks of text terminated by a blank line, the end of |
file, or the start of a delimited block or a list. There are three |
paragraph syntaxes: normal, indented (literal) and admonition which |
are rendered, by default, with the corresponding paragraph style. |
|
Each syntax has a default style, but you can explicitly apply any |
paragraph style to any paragraph syntax. You can also apply |
<<X104,delimited block>> styles to single paragraphs. |
|
The built-in paragraph styles are: 'normal', 'literal', 'verse', |
'quote', 'listing', 'TIP', 'NOTE', 'IMPORTANT', 'WARNING', 'CAUTION', |
'abstract', 'partintro', 'comment', 'example', 'sidebar', 'source', |
'music', 'latex', 'graphviz'. |
|
normal paragraph syntax |
~~~~~~~~~~~~~~~~~~~~~~~ |
Normal paragraph syntax consists of one or more non-blank lines of |
text. The first line must start hard against the left margin (no |
intervening white space). The default processing expectation is that |
of a normal paragraph of text. |
|
[[X85]] |
literal paragraph syntax |
~~~~~~~~~~~~~~~~~~~~~~~~ |
Literal paragraphs are rendered verbatim in a monospaced font without |
any distinguishing background or border. By default there is no text |
formatting or substitutions within Literal paragraphs apart from |
Special Characters and Callouts. |
|
The 'literal' style is applied implicitly to indented paragraphs i.e. |
where the first line of the paragraph is indented by one or more space |
or tab characters. For example: |
|
--------------------------------------------------------------------- |
Consul *necessitatibus* per id, |
consetetur, eu pro everti postulant |
homero verear ea mea, qui. |
--------------------------------------------------------------------- |
|
Renders: |
|
Consul *necessitatibus* per id, |
consetetur, eu pro everti postulant |
homero verear ea mea, qui. |
|
NOTE: Because <<X64,lists>> can be indented it's possible for your |
indented paragraph to be misinterpreted as a list -- in situations |
like this apply the 'literal' style to a normal paragraph. |
|
Instead of using a paragraph indent you could apply the 'literal' |
style explicitly, for example: |
|
--------------------------------------------------------------------- |
[literal] |
Consul *necessitatibus* per id, |
consetetur, eu pro everti postulant |
homero verear ea mea, qui. |
--------------------------------------------------------------------- |
|
Renders: |
|
[literal] |
Consul *necessitatibus* per id, |
consetetur, eu pro everti postulant |
homero verear ea mea, qui. |
|
[[X94]] |
quote and verse paragraph styles |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
The optional 'attribution' and 'citetitle' attributes (positional |
attributes 2 and 3) specify the author and source respectively. |
|
The 'verse' style retains the line breaks, for example: |
|
--------------------------------------------------------------------- |
[verse, William Blake, from Auguries of Innocence] |
To see a world in a grain of sand, |
And a heaven in a wild flower, |
Hold infinity in the palm of your hand, |
And eternity in an hour. |
--------------------------------------------------------------------- |
|
Which is rendered as: |
|
[verse, William Blake, from Auguries of Innocence] |
To see a world in a grain of sand, |
And a heaven in a wild flower, |
Hold infinity in the palm of your hand, |
And eternity in an hour. |
|
The 'quote' style flows the text at left and right margins, for |
example: |
|
--------------------------------------------------------------------- |
[quote, Bertrand Russell, The World of Mathematics (1956)] |
A good notation has subtlety and suggestiveness which at times makes |
it almost seem like a live teacher. |
--------------------------------------------------------------------- |
|
Which is rendered as: |
|
[quote, Bertrand Russell, The World of Mathematics (1956)] |
A good notation has subtlety and suggestiveness which at times makes |
it almost seem like a live teacher. |
|
[[X28]] |
Admonition Paragraphs |
~~~~~~~~~~~~~~~~~~~~~ |
'TIP', 'NOTE', 'IMPORTANT', 'WARNING' and 'CAUTION' admonishment |
paragraph styles are generated by placing `NOTE:`, `TIP:`, |
`IMPORTANT:`, `WARNING:` or `CAUTION:` as the first word of the |
paragraph. For example: |
|
NOTE: This is an example note. |
|
Alternatively, you can specify the paragraph admonition style |
explicitly using an <<X79,AttributeList element>>. For example: |
|
[NOTE] |
This is an example note. |
|
Renders: |
|
NOTE: This is an example note. |
|
TIP: If your admonition requires more than a single paragraph use an |
<<X22,admonition block>> instead. |
|
[[X47]] |
Admonition Icons and Captions |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
NOTE: Admonition customization with `icons`, `iconsdir`, `icon` and |
`caption` attributes does not apply when generating DocBook output. If |
you are going the DocBook route then the <<X43,a2x(1)>> `--no-icons` |
and `--icons-dir` options can be used to set the appropriate XSL |
Stylesheets parameters. |
|
By default the asciidoc(1) HTML backends generate text captions |
instead of admonition icon image links. To generate links to icon |
images define the <<X45,`icons`>> attribute, for example using the `-a |
icons` command-line option. |
|
The <<X44,`iconsdir`>> attribute sets the location of linked icon |
images. |
|
You can override the default icon image using the `icon` attribute to |
specify the path of the linked image. For example: |
|
[icon="./images/icons/wink.png"] |
NOTE: What lovely war. |
|
Use the `caption` attribute to customize the admonition captions (not |
applicable to `docbook` backend). The following example suppresses the |
icon image and customizes the caption of a 'NOTE' admonition |
(undefining the `icons` attribute with `icons=None` is only necessary |
if <<X45,admonition icons>> have been enabled): |
|
[icons=None, caption="My Special Note"] |
NOTE: This is my special note. |
|
This subsection also applies to <<X22,Admonition Blocks>>. |
|
|
[[X104]] |
Delimited Blocks |
---------------- |
Delimited blocks are blocks of text enveloped by leading and trailing |
delimiter lines (normally a series of four or more repeated |
characters). The behavior of Delimited Blocks is specified by entries |
in configuration file `[blockdef-*]` sections. |
|
Predefined Delimited Blocks |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
AsciiDoc ships with a number of predefined DelimitedBlocks (see the |
`asciidoc.conf` configuration file in the asciidoc(1) program |
directory): |
|
Predefined delimited block underlines: |
|
CommentBlock: ////////////////////////// |
PassthroughBlock: ++++++++++++++++++++++++++ |
ListingBlock: -------------------------- |
LiteralBlock: .......................... |
SidebarBlock: ************************** |
QuoteBlock: __________________________ |
ExampleBlock: ========================== |
OpenBlock: -- |
|
.Default DelimitedBlock substitutions |
[cols="2e,7*^",frame="topbot",options="header,autowidth"] |
|===================================================== |
| |Attributes |Callouts |Macros | Quotes |Replacements |
|Special chars |Special words |
|
|PassthroughBlock |Yes |No |Yes |No |No |No |No |
|ListingBlock |No |Yes |No |No |No |Yes |No |
|LiteralBlock |No |Yes |No |No |No |Yes |No |
|SidebarBlock |Yes |No |Yes |Yes |Yes |Yes |Yes |
|QuoteBlock |Yes |No |Yes |Yes |Yes |Yes |Yes |
|ExampleBlock |Yes |No |Yes |Yes |Yes |Yes |Yes |
|OpenBlock |Yes |No |Yes |Yes |Yes |Yes |Yes |
|===================================================== |
|
Listing Blocks |
~~~~~~~~~~~~~~ |
'ListingBlocks' are rendered verbatim in a monospaced font, they |
retain line and whitespace formatting and are often distinguished by a |
background or border. There is no text formatting or substitutions |
within Listing blocks apart from Special Characters and Callouts. |
Listing blocks are often used for computer output and file listings. |
|
Here's an example: |
|
[listing] |
...................................... |
-------------------------------------- |
#include <stdio.h> |
|
int main() { |
printf("Hello World!\n"); |
exit(0); |
} |
-------------------------------------- |
...................................... |
|
Which will be rendered like: |
|
-------------------------------------- |
#include <stdio.h> |
|
int main() { |
printf("Hello World!\n"); |
exit(0); |
} |
-------------------------------------- |
|
By convention <<X59,filter blocks>> use the listing block syntax and |
are implemented as distinct listing block styles. |
|
[[X65]] |
Literal Blocks |
~~~~~~~~~~~~~~ |
'LiteralBlocks' are rendered just like <<X85,literal paragraphs>>. |
Example: |
|
--------------------------------------------------------------------- |
................................... |
Consul *necessitatibus* per id, |
consetetur, eu pro everti postulant |
homero verear ea mea, qui. |
................................... |
--------------------------------------------------------------------- |
|
Renders: |
................................... |
Consul *necessitatibus* per id, |
consetetur, eu pro everti postulant |
homero verear ea mea, qui. |
................................... |
|
If the 'listing' style is applied to a LiteralBlock it will be |
rendered as a ListingBlock (this is handy if you have a listing |
containing a ListingBlock). |
|
Sidebar Blocks |
~~~~~~~~~~~~~~ |
A sidebar is a short piece of text presented outside the narrative |
flow of the main text. The sidebar is normally presented inside a |
bordered box to set it apart from the main text. |
|
The sidebar body is treated like a normal section body. |
|
Here's an example: |
|
--------------------------------------------------------------------- |
.An Example Sidebar |
************************************************ |
Any AsciiDoc SectionBody element (apart from |
SidebarBlocks) can be placed inside a sidebar. |
************************************************ |
--------------------------------------------------------------------- |
|
Which will be rendered like: |
|
.An Example Sidebar |
************************************************ |
Any AsciiDoc SectionBody element (apart from |
SidebarBlocks) can be placed inside a sidebar. |
************************************************ |
|
[[X26]] |
Comment Blocks |
~~~~~~~~~~~~~~ |
The contents of 'CommentBlocks' are not processed; they are useful for |
annotations and for excluding new or outdated content that you don't |
want displayed. CommentBlocks are never written to output files. |
Example: |
|
--------------------------------------------------------------------- |
////////////////////////////////////////// |
CommentBlock contents are not processed by |
asciidoc(1). |
////////////////////////////////////////// |
--------------------------------------------------------------------- |
|
See also <<X25,Comment Lines>>. |
|
NOTE: System macros are executed inside comment blocks. |
|
[[X76]] |
Passthrough Blocks |
~~~~~~~~~~~~~~~~~~ |
By default the block contents is subject only to 'attributes' and |
'macros' substitutions (use an explicit 'subs' attribute to apply |
different substitutions). PassthroughBlock content will often be |
backend specific. Here's an example: |
|
--------------------------------------------------------------------- |
[subs="quotes"] |
++++++++++++++++++++++++++++++++++++++ |
<table border="1"><tr> |
<td>*Cell 1*</td> |
<td>*Cell 2*</td> |
</tr></table> |
++++++++++++++++++++++++++++++++++++++ |
--------------------------------------------------------------------- |
|
The following styles can be applied to passthrough blocks: |
|
pass:: |
No substitutions are performed. This is equivalent to `subs="none"`. |
|
asciimath, latexmath:: |
By default no substitutions are performed, the contents are rendered |
as <<X78,mathematical formulas>>. |
|
Quote Blocks |
~~~~~~~~~~~~ |
'QuoteBlocks' are used for quoted passages of text. There are two |
styles: 'quote' and 'verse'. The style behavior is identical to |
<<X94,quote and verse paragraphs>> except that blocks can contain |
multiple paragraphs and, in the case of the 'quote' style, other |
section elements. The first positional attribute sets the style, if |
no attributes are specified the 'quote' style is used. The optional |
'attribution' and 'citetitle' attributes (positional attributes 2 and |
3) specify the quote's author and source. For example: |
|
--------------------------------------------------------------------- |
[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes] |
____________________________________________________________________ |
As he spoke there was the sharp sound of horses' hoofs and |
grating wheels against the curb, followed by a sharp pull at the |
bell. Holmes whistled. |
|
"A pair, by the sound," said he. "Yes," he continued, glancing |
out of the window. "A nice little brougham and a pair of |
beauties. A hundred and fifty guineas apiece. There's money in |
this case, Watson, if there is nothing else." |
____________________________________________________________________ |
--------------------------------------------------------------------- |
|
Which is rendered as: |
|
[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes] |
____________________________________________________________________ |
As he spoke there was the sharp sound of horses' hoofs and |
grating wheels against the curb, followed by a sharp pull at the |
bell. Holmes whistled. |
|
"A pair, by the sound," said he. "Yes," he continued, glancing |
out of the window. "A nice little brougham and a pair of |
beauties. A hundred and fifty guineas apiece. There's money in |
this case, Watson, if there is nothing else." |
____________________________________________________________________ |
|
[[X48]] |
Example Blocks |
~~~~~~~~~~~~~~ |
'ExampleBlocks' encapsulate the DocBook Example element and are used |
for, well, examples. Example blocks can be titled by preceding them |
with a 'BlockTitle'. DocBook toolchains will normally automatically |
number examples and generate a 'List of Examples' backmatter section. |
|
Example blocks are delimited by lines of equals characters and can |
contain any block elements apart from Titles, BlockTitles and |
Sidebars) inside an example block. For example: |
|
--------------------------------------------------------------------- |
.An example |
===================================================================== |
Qui in magna commodo, est labitur dolorum an. Est ne magna primis |
adolescens. |
===================================================================== |
--------------------------------------------------------------------- |
|
Renders: |
|
.An example |
===================================================================== |
Qui in magna commodo, est labitur dolorum an. Est ne magna primis |
adolescens. |
===================================================================== |
|
A title prefix that can be inserted with the `caption` attribute |
(HTML backends). For example: |
|
--------------------------------------------------------------------- |
[caption="Example 1: "] |
.An example with a custom caption |
===================================================================== |
Qui in magna commodo, est labitur dolorum an. Est ne magna primis |
adolescens. |
===================================================================== |
--------------------------------------------------------------------- |
|
[[X22]] |
Admonition Blocks |
~~~~~~~~~~~~~~~~~ |
The 'ExampleBlock' definition includes a set of admonition |
<<X23,styles>> ('NOTE', 'TIP', 'IMPORTANT', 'WARNING', 'CAUTION') for |
generating admonition blocks (admonitions containing more than a |
<<X28,single paragraph>>). Just precede the 'ExampleBlock' with an |
attribute list specifying the admonition style name. For example: |
|
--------------------------------------------------------------------- |
[NOTE] |
.A NOTE admonition block |
===================================================================== |
Qui in magna commodo, est labitur dolorum an. Est ne magna primis |
adolescens. |
|
. Fusce euismod commodo velit. |
. Vivamus fringilla mi eu lacus. |
.. Fusce euismod commodo velit. |
.. Vivamus fringilla mi eu lacus. |
. Donec eget arcu bibendum |
nunc consequat lobortis. |
===================================================================== |
--------------------------------------------------------------------- |
|
Renders: |
|
[NOTE] |
.A NOTE admonition block |
===================================================================== |
Qui in magna commodo, est labitur dolorum an. Est ne magna primis |
adolescens. |
|
. Fusce euismod commodo velit. |
. Vivamus fringilla mi eu lacus. |
.. Fusce euismod commodo velit. |
.. Vivamus fringilla mi eu lacus. |
. Donec eget arcu bibendum |
nunc consequat lobortis. |
===================================================================== |
|
See also <<X47,Admonition Icons and Captions>>. |
|
[[X29]] |
Open Blocks |
~~~~~~~~~~~ |
Open blocks are special: |
|
- The open block delimiter is line containing two hyphen characters |
(instead of four or more repeated characters). |
|
- They can be used to group block elements for <<X15,List item |
continuation>>. |
|
- Open blocks can be styled to behave like any other type of delimited |
block. The following built-in styles can be applied to open |
blocks: 'literal', 'verse', 'quote', 'listing', 'TIP', 'NOTE', |
'IMPORTANT', 'WARNING', 'CAUTION', 'abstract', 'partintro', |
'comment', 'example', 'sidebar', 'source', 'music', 'latex', |
'graphviz'. For example, the following open block and listing block |
are functionally identical: |
|
[listing] |
-- |
Lorum ipsum ... |
-- |
|
--------------- |
Lorum ipsum ... |
--------------- |
|
- An unstyled open block groups section elements but otherwise does |
nothing. |
|
Open blocks are used to generate document abstracts and book part |
introductions: |
|
- Apply the 'abstract' style to generate an abstract, for example: |
|
[abstract] |
-- |
In this paper we will ... |
-- |
|
. Apply the 'partintro' style to generate a book part introduction for |
a multi-part book, for example: |
|
[partintro] |
.Optional part introduction title |
-- |
Optional part introduction goes here. |
-- |
|
|
[[X64]] |
Lists |
----- |
.List types |
- Bulleted lists. Also known as itemized or unordered lists. |
- Numbered lists. Also called ordered lists. |
- Labeled lists. Sometimes called variable or definition lists. |
- Callout lists (a list of callout annotations). |
|
.List behavior |
- List item indentation is optional and does not determine nesting, |
indentation does however make the source more readable. |
- Another list or a literal paragraph immediately following a list |
item will be implicitly included in the list item; use <<X15, list |
item continuation>> to explicitly append other block elements to a |
list item. |
- A comment block or a comment line block macro element will terminate |
a list -- use inline comment lines to put comments inside lists. |
- The `listindex` <<X60,intrinsic attribute>> is the current list item |
index (1..). If this attribute is used outside a list then it's value |
is the number of items in the most recently closed list. Useful for |
displaying the number of items in a list. |
|
Bulleted Lists |
~~~~~~~~~~~~~~ |
Bulleted list items start with a single dash or one to five asterisks |
followed by some white space then some text. Bulleted list syntaxes |
are: |
|
................... |
- List item. |
* List item. |
** List item. |
*** List item. |
**** List item. |
***** List item. |
................... |
|
Numbered Lists |
~~~~~~~~~~~~~~ |
List item numbers are explicit or implicit. |
|
.Explicit numbering |
List items begin with a number followed by some white space then the |
item text. The numbers can be decimal (arabic), roman (upper or lower |
case) or alpha (upper or lower case). Decimal and alpha numbers are |
terminated with a period, roman numbers are terminated with a closing |
parenthesis. The different terminators are necessary to ensure 'i', |
'v' and 'x' roman numbers are are distinguishable from 'x', 'v' and |
'x' alpha numbers. Examples: |
|
..................................................................... |
1. Arabic (decimal) numbered list item. |
a. Lower case alpha (letter) numbered list item. |
F. Upper case alpha (letter) numbered list item. |
iii) Lower case roman numbered list item. |
IX) Upper case roman numbered list item. |
..................................................................... |
|
.Implicit numbering |
List items begin one to five period characters, followed by some white |
space then the item text. Examples: |
|
..................................................................... |
. Arabic (decimal) numbered list item. |
.. Lower case alpha (letter) numbered list item. |
... Lower case roman numbered list item. |
.... Upper case alpha (letter) numbered list item. |
..... Upper case roman numbered list item. |
..................................................................... |
|
You can use the 'style' attribute (also the first positional |
attribute) to specify an alternative numbering style. The numbered |
list style can be one of the following values: 'arabic', 'loweralpha', |
'upperalpha', 'lowerroman', 'upperroman'. |
|
Here are some examples of bulleted and numbered lists: |
|
--------------------------------------------------------------------- |
- Praesent eget purus quis magna eleifend eleifend. |
1. Fusce euismod commodo velit. |
a. Fusce euismod commodo velit. |
b. Vivamus fringilla mi eu lacus. |
c. Donec eget arcu bibendum nunc consequat lobortis. |
2. Vivamus fringilla mi eu lacus. |
i) Fusce euismod commodo velit. |
ii) Vivamus fringilla mi eu lacus. |
3. Donec eget arcu bibendum nunc consequat lobortis. |
4. Nam fermentum mattis ante. |
- Lorem ipsum dolor sit amet, consectetuer adipiscing elit. |
* Fusce euismod commodo velit. |
** Qui in magna commodo, est labitur dolorum an. Est ne magna primis |
adolescens. Sit munere ponderum dignissim et. Minim luptatum et |
vel. |
** Vivamus fringilla mi eu lacus. |
* Donec eget arcu bibendum nunc consequat lobortis. |
- Nulla porttitor vulputate libero. |
. Fusce euismod commodo velit. |
. Vivamus fringilla mi eu lacus. |
[upperroman] |
.. Fusce euismod commodo velit. |
.. Vivamus fringilla mi eu lacus. |
. Donec eget arcu bibendum nunc consequat lobortis. |
--------------------------------------------------------------------- |
|
Which render as: |
|
- Praesent eget purus quis magna eleifend eleifend. |
1. Fusce euismod commodo velit. |
a. Fusce euismod commodo velit. |
b. Vivamus fringilla mi eu lacus. |
c. Donec eget arcu bibendum nunc consequat lobortis. |
2. Vivamus fringilla mi eu lacus. |
i) Fusce euismod commodo velit. |
ii) Vivamus fringilla mi eu lacus. |
3. Donec eget arcu bibendum nunc consequat lobortis. |
4. Nam fermentum mattis ante. |
- Lorem ipsum dolor sit amet, consectetuer adipiscing elit. |
* Fusce euismod commodo velit. |
** Qui in magna commodo, est labitur dolorum an. Est ne magna primis |
adolescens. Sit munere ponderum dignissim et. Minim luptatum et |
vel. |
** Vivamus fringilla mi eu lacus. |
* Donec eget arcu bibendum nunc consequat lobortis. |
- Nulla porttitor vulputate libero. |
. Fusce euismod commodo velit. |
. Vivamus fringilla mi eu lacus. |
[upperroman] |
.. Fusce euismod commodo velit. |
.. Vivamus fringilla mi eu lacus. |
. Donec eget arcu bibendum nunc consequat lobortis. |
|
A predefined 'compact' option is available to bulleted and numbered |
lists -- this translates to the DocBook 'spacing="compact"' lists |
attribute which may or may not be processed by the DocBook toolchain. |
Example: |
|
[options="compact"] |
- Compact list item. |
- Another compact list item. |
|
TIP: To apply the 'compact' option globally define a document-wide |
'compact-option' attribute, e.g. using the `-a compact-option` |
command-line option. |
|
You can set the list start number using the 'start' attribute (works |
for HTML outputs and DocBook outputs processed by DocBook XSL |
Stylesheets). Example: |
|
[start=7] |
. List item 7. |
. List item 8. |
|
Labeled Lists |
~~~~~~~~~~~~~ |
Labeled list items consist of one or more text labels followed by the |
text of the list item. |
|
An item label begins a line with an alphanumeric character hard |
against the left margin and ends with two, three or four colons or two |
semi-colons. A list item can have multiple labels, one per line. |
|
The list item text consists of one or more lines of text starting |
after the last label (either on the same line or a new line) and can |
be followed by nested List or ListParagraph elements. Item text can be |
optionally indented. |
|
Here are some examples: |
|
--------------------------------------------------------------------- |
In:: |
Lorem:: |
Fusce euismod commodo velit. |
|
Fusce euismod commodo velit. |
|
Ipsum:: Vivamus fringilla mi eu lacus. |
* Vivamus fringilla mi eu lacus. |
* Donec eget arcu bibendum nunc consequat lobortis. |
Dolor:: |
Donec eget arcu bibendum nunc consequat lobortis. |
Suspendisse;; |
A massa id sem aliquam auctor. |
Morbi;; |
Pretium nulla vel lorem. |
In;; |
Dictum mauris in urna. |
Vivamus::: Fringilla mi eu lacus. |
Donec::: Eget arcu bibendum nunc consequat lobortis. |
--------------------------------------------------------------------- |
|
Which render as: |
|
In:: |
Lorem:: |
Fusce euismod commodo velit. |
|
Fusce euismod commodo velit. |
|
Ipsum:: Vivamus fringilla mi eu lacus. |
* Vivamus fringilla mi eu lacus. |
* Donec eget arcu bibendum nunc consequat lobortis. |
Dolor:: |
Donec eget arcu bibendum nunc consequat lobortis. |
Suspendisse;; |
A massa id sem aliquam auctor. |
Morbi;; |
Pretium nulla vel lorem. |
In;; |
Dictum mauris in urna. |
Vivamus::: Fringilla mi eu lacus. |
Donec::: Eget arcu bibendum nunc consequat lobortis. |
|
Horizontal labeled list style |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
The 'horizontal' labeled list style (also the first positional |
attribute) places the list text side-by-side with the label instead of |
under the label. Here is an example: |
|
--------------------------------------------------------------------- |
[horizontal] |
*Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est |
labitur dolorum an. Est ne magna primis adolescens. |
|
Fusce euismod commodo velit. |
|
*Ipsum*:: Vivamus fringilla mi eu lacus. |
- Vivamus fringilla mi eu lacus. |
- Donec eget arcu bibendum nunc consequat lobortis. |
|
*Dolor*:: |
- Vivamus fringilla mi eu lacus. |
- Donec eget arcu bibendum nunc consequat lobortis. |
|
--------------------------------------------------------------------- |
|
Which render as: |
|
[horizontal] |
*Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est |
labitur dolorum an. Est ne magna primis adolescens. |
|
Fusce euismod commodo velit. |
|
*Ipsum*:: Vivamus fringilla mi eu lacus. |
- Vivamus fringilla mi eu lacus. |
- Donec eget arcu bibendum nunc consequat lobortis. |
|
*Dolor*:: |
- Vivamus fringilla mi eu lacus. |
- Donec eget arcu bibendum nunc consequat lobortis. |
|
[NOTE] |
===================================================================== |
- Current PDF toolchains do not make a good job of determining |
the relative column widths for horizontal labeled lists. |
- Nested horizontal labeled lists will generate DocBook validation |
errors because the 'DocBook XML V4.2' DTD does not permit nested |
informal tables (although <<X13,DocBook XSL Stylesheets>> and |
<<X31,dblatex>> process them correctly). |
- The label width can be set as a percentage of the total width by |
setting the 'width' attribute e.g. `width="10%"` |
===================================================================== |
|
Question and Answer Lists |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
AsciiDoc comes pre-configured with a 'qanda' style labeled list for generating |
DocBook question and answer (Q&A) lists. Example: |
|
--------------------------------------------------------------------- |
[qanda] |
Question one:: |
Answer one. |
Question two:: |
Answer two. |
--------------------------------------------------------------------- |
|
Renders: |
|
[qanda] |
Question one:: |
Answer one. |
Question two:: |
Answer two. |
|
Glossary Lists |
~~~~~~~~~~~~~~ |
AsciiDoc comes pre-configured with a 'glossary' style labeled list for |
generating DocBook glossary lists. Example: |
|
--------------------------------------------------------------------- |
[glossary] |
A glossary term:: |
The corresponding definition. |
A second glossary term:: |
The corresponding definition. |
--------------------------------------------------------------------- |
|
For working examples see the `article.txt` and `book.txt` documents in |
the AsciiDoc `./doc` distribution directory. |
|
NOTE: To generate valid DocBook output glossary lists must be located |
in a section that uses the 'glossary' <<X93,section markup template>>. |
|
Bibliography Lists |
~~~~~~~~~~~~~~~~~~ |
AsciiDoc comes with a predefined 'bibliography' bulleted list style |
generating DocBook bibliography entries. Example: |
|
--------------------------------------------------------------------- |
[bibliography] |
.Optional list title |
- [[[taoup]]] Eric Steven Raymond. 'The Art of UNIX |
Programming'. Addison-Wesley. ISBN 0-13-142901-9. |
- [[[walsh-muellner]]] Norman Walsh & Leonard Muellner. |
'DocBook - The Definitive Guide'. O'Reilly & Associates. |
1999. ISBN 1-56592-580-7. |
--------------------------------------------------------------------- |
|
The `[[[<reference>]]]` syntax is a bibliography entry anchor, it |
generates an anchor named `<reference>` and additionally displays |
`[<reference>]` at the anchor position. For example `[[[taoup]]]` |
generates an anchor named `taoup` that displays `[taoup]` at the |
anchor position. Cite the reference from elsewhere your document using |
`<<taoup>>`, this displays a hyperlink (`[taoup]`) to the |
corresponding bibliography entry anchor. |
|
For working examples see the `article.txt` and `book.txt` documents in |
the AsciiDoc `./doc` distribution directory. |
|
NOTE: To generate valid DocBook output bibliography lists must be |
located in a <<X93,bibliography section>>. |
|
[[X15]] |
List Item Continuation |
~~~~~~~~~~~~~~~~~~~~~~ |
Another list or a literal paragraph immediately following a list item |
is implicitly appended to the list item; to append other block |
elements to a list item you need to explicitly join them to the list |
item with a 'list continuation' (a separator line containing a single |
plus character). Multiple block elements can be appended to a list |
item using list continuations (provided they are legal list item |
children in the backend markup). |
|
Here are some examples of list item continuations: list item one |
contains multiple continuations; list item two is continued with an |
<<X29,OpenBlock>> containing multiple elements: |
|
--------------------------------------------------------------------- |
1. List item one. |
+ |
List item one continued with a second paragraph followed by an |
Indented block. |
+ |
................. |
$ ls *.sh |
$ mv *.sh ~/tmp |
................. |
+ |
List item continued with a third paragraph. |
|
2. List item two continued with an open block. |
+ |
-- |
This paragraph is part of the preceding list item. |
|
a. This list is nested and does not require explicit item continuation. |
+ |
This paragraph is part of the preceding list item. |
|
b. List item b. |
|
This paragraph belongs to item two of the outer list. |
-- |
--------------------------------------------------------------------- |
|
Renders: |
|
1. List item one. |
+ |
List item one continued with a second paragraph followed by an |
Indented block. |
+ |
................. |
$ ls *.sh |
$ mv *.sh ~/tmp |
................. |
+ |
List item continued with a third paragraph. |
|
2. List item two continued with an open block. |
+ |
-- |
This paragraph is part of the preceding list item. |
|
a. This list is nested and does not require explicit item continuation. |
+ |
This paragraph is part of the preceding list item. |
|
b. List item b. |
|
This paragraph belongs to item two of the outer list. |
-- |
|
|
[[X92]] |
Footnotes |
--------- |
The shipped AsciiDoc configuration includes three footnote inline |
macros: |
|
`footnote:[<text>]`:: |
Generates a footnote with text `<text>`. |
|
`footnoteref:[<id>,<text>]`:: |
Generates a footnote with a reference ID `<id>` and text `<text>`. |
|
`footnoteref:[<id>]`:: |
Generates a reference to the footnote with ID `<id>`. |
|
The footnote text can span multiple lines. |
|
The 'xhtml11' and 'html5' backends render footnotes dynamically using |
JavaScript; 'html4' outputs do not use JavaScript and leave the |
footnotes inline; 'docbook' footnotes are processed by the downstream |
DocBook toolchain. |
|
Example footnotes: |
|
A footnote footnote:[An example footnote.]; |
a second footnote with a reference ID footnoteref:[note2,Second footnote.]; |
finally a reference to the second footnote footnoteref:[note2]. |
|
Renders: |
|
A footnote footnote:[An example footnote.]; |
a second footnote with a reference ID footnoteref:[note2,Second footnote.]; |
finally a reference to the second footnote footnoteref:[note2]. |
|
|
Indexes |
------- |
The shipped AsciiDoc configuration includes the inline macros for |
generating DocBook index entries. |
|
`indexterm:[<primary>,<secondary>,<tertiary>]`:: |
`(((<primary>,<secondary>,<tertiary>)))`:: |
This inline macro generates an index term (the `<secondary>` and |
`<tertiary>` positional attributes are optional). Example: |
`indexterm:[Tigers,Big cats]` (or, using the alternative syntax |
`(((Tigers,Big cats)))`. Index terms that have secondary and |
tertiary entries also generate separate index terms for the |
secondary and tertiary entries. The index terms appear in the |
index, not the primary text flow. |
|
`indexterm2:[<primary>]`:: |
`((<primary>))`:: |
This inline macro generates an index term that appears in both the |
index and the primary text flow. The `<primary>` should not be |
padded to the left or right with white space characters. |
|
For working examples see the `article.txt` and `book.txt` documents in |
the AsciiDoc `./doc` distribution directory. |
|
NOTE: Index entries only really make sense if you are generating |
DocBook markup -- DocBook conversion programs automatically generate |
an index at the point an 'Index' section appears in source document. |
|
|
[[X105]] |
Callouts |
-------- |
Callouts are a mechanism for annotating verbatim text (for example: |
source code, computer output and user input). Callout markers are |
placed inside the annotated text while the actual annotations are |
presented in a callout list after the annotated text. Here's an |
example: |
|
--------------------------------------------------------------------- |
.MS-DOS directory listing |
----------------------------------------------------- |
10/17/97 9:04 <DIR> bin |
10/16/97 14:11 <DIR> DOS \<1> |
10/16/97 14:40 <DIR> Program Files |
10/16/97 14:46 <DIR> TEMP |
10/17/97 9:04 <DIR> tmp |
10/16/97 14:37 <DIR> WINNT |
10/16/97 14:25 119 AUTOEXEC.BAT \<2> |
2/13/94 6:21 54,619 COMMAND.COM \<2> |
10/16/97 14:25 115 CONFIG.SYS \<2> |
11/16/97 17:17 61,865,984 pagefile.sys |
2/13/94 6:21 9,349 WINA20.386 \<3> |
----------------------------------------------------- |
|
\<1> This directory holds MS-DOS. |
\<2> System startup code for DOS. |
\<3> Some sort of Windows 3.1 hack. |
--------------------------------------------------------------------- |
|
Which renders: |
|
.MS-DOS directory listing |
----------------------------------------------------- |
10/17/97 9:04 <DIR> bin |
10/16/97 14:11 <DIR> DOS <1> |
10/16/97 14:40 <DIR> Program Files |
10/16/97 14:46 <DIR> TEMP |
10/17/97 9:04 <DIR> tmp |
10/16/97 14:37 <DIR> WINNT |
10/16/97 14:25 119 AUTOEXEC.BAT <2> |
2/13/94 6:21 54,619 COMMAND.COM <2> |
10/16/97 14:25 115 CONFIG.SYS <2> |
11/16/97 17:17 61,865,984 pagefile.sys |
2/13/94 6:21 9,349 WINA20.386 <3> |
----------------------------------------------------- |
|
<1> This directory holds MS-DOS. |
<2> System startup code for DOS. |
<3> Some sort of Windows 3.1 hack. |
|
.Explanation |
- The callout marks are whole numbers enclosed in angle brackets -- |
they refer to the correspondingly numbered item in the following |
callout list. |
- By default callout marks are confined to 'LiteralParagraphs', |
'LiteralBlocks' and 'ListingBlocks' (although this is a |
configuration file option and can be changed). |
- Callout list item numbering is fairly relaxed -- list items can |
start with `<n>`, `n>` or `>` where `n` is the optional list item |
number (in the latter case list items starting with a single `>` |
character are implicitly numbered starting at one). |
- Callout lists should not be nested. |
- Callout lists start list items hard against the left margin. |
- If you want to present a number inside angle brackets you'll need to |
escape it with a backslash to prevent it being interpreted as a |
callout mark. |
|
NOTE: Define the AsciiDoc 'icons' attribute (for example using the `-a |
icons` command-line option) to display callout icons. |
|
Implementation Notes |
~~~~~~~~~~~~~~~~~~~~ |
Callout marks are generated by the 'callout' inline macro while |
callout lists are generated using the 'callout' list definition. The |
'callout' macro and 'callout' list are special in that they work |
together. The 'callout' inline macro is not enabled by the normal |
'macros' substitutions option, instead it has its own 'callouts' |
substitution option. |
|
The following attributes are available during inline callout macro |
substitution: |
|
`{index}`:: |
The callout list item index inside the angle brackets. |
`{coid}`:: |
An identifier formatted like `CO<listnumber>-<index>` that |
uniquely identifies the callout mark. For example `CO2-4` |
identifies the fourth callout mark in the second set of callout |
marks. |
|
The `{coids}` attribute can be used during callout list item |
substitution -- it is a space delimited list of callout IDs that refer |
to the explanatory list item. |
|
Including callouts in included code |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
You can annotate working code examples with callouts -- just remember |
to put the callouts inside source code comments. This example displays |
the `test.py` source file (containing a single callout) using the |
'source' (code highlighter) filter: |
|
.AsciiDoc source |
--------------------------------------------------------------------- |
[source,python] |
------------------------------------------- |
\include::test.py[] |
------------------------------------------- |
|
\<1> Print statement. |
--------------------------------------------------------------------- |
|
.Included `test.py` source |
--------------------------------------------------------------------- |
print 'Hello World!' # \<1> |
--------------------------------------------------------------------- |
|
|
Macros |
------ |
Macros are a mechanism for substituting parametrized text into output |
documents. |
|
Macros have a 'name', a single 'target' argument and an 'attribute |
list'. The usual syntax is `<name>:<target>[<attrlist>]` (for |
inline macros) and `<name>::<target>[<attrlist>]` (for block |
macros). Here are some examples: |
|
http://www.docbook.org/[DocBook.org] |
include::chapt1.txt[tabsize=2] |
mailto:srackham@gmail.com[] |
|
.Macro behavior |
- `<name>` is the macro name. It can only contain letters, digits or |
dash characters and cannot start with a dash. |
- The optional `<target>` cannot contain white space characters. |
- `<attrlist>` is a <<X21,list of attributes>> enclosed in square |
brackets. |
- `]` characters inside attribute lists must be escaped with a |
backslash. |
- Expansion of macro references can normally be escaped by prefixing a |
backslash character (see the AsciiDoc 'FAQ' for examples of |
exceptions to this rule). |
- Attribute references in block macros are expanded. |
- The substitutions performed prior to Inline macro macro expansion |
are determined by the inline context. |
- Macros are processed in the order they appear in the configuration |
file(s). |
- Calls to inline macros can be nested inside different inline macros |
(an inline macro call cannot contain a nested call to itself). |
- In addition to `<name>`, `<target>` and `<attrlist>` the |
`<passtext>` and `<subslist>` named groups are available to |
<<X77,passthrough macros>>. A macro is a passthrough macro if the |
definition includes a `<passtext>` named group. |
|
Inline Macros |
~~~~~~~~~~~~~ |
Inline Macros occur in an inline element context. Predefined Inline |
macros include 'URLs', 'image' and 'link' macros. |
|
URLs |
^^^^ |
'http', 'https', 'ftp', 'file', 'mailto' and 'callto' URLs are |
rendered using predefined inline macros. |
|
- If you don't need a custom link caption you can enter the 'http', |
'https', 'ftp', 'file' URLs and email addresses without any special |
macro syntax. |
- If the `<attrlist>` is empty the URL is displayed. |
|
Here are some examples: |
|
http://www.docbook.org/[DocBook.org] |
http://www.docbook.org/ |
mailto:joe.bloggs@foobar.com[email Joe Bloggs] |
joe.bloggs@foobar.com |
|
Which are rendered: |
|
http://www.docbook.org/[DocBook.org] |
|
http://www.docbook.org/ |
|
mailto:joe.bloggs@foobar.com[email Joe Bloggs] |
|
joe.bloggs@foobar.com |
|
If the `<target>` necessitates space characters use `%20`, for example |
`large%20image.png`. |
|
Internal Cross References |
^^^^^^^^^^^^^^^^^^^^^^^^^ |
Two AsciiDoc inline macros are provided for creating hypertext links |
within an AsciiDoc document. You can use either the standard macro |
syntax or the (preferred) alternative. |
|
[[X30]] |
anchor |
++++++ |
Used to specify hypertext link targets: |
|
[[<id>,<xreflabel>]] |
anchor:<id>[<xreflabel>] |
|
The `<id>` is a unique string that conforms to the output markup's |
anchor syntax. The optional `<xreflabel>` is the text to be displayed |
by captionless 'xref' macros that refer to this anchor. The optional |
`<xreflabel>` is only really useful when generating DocBook output. |
Example anchor: |
|
[[X1]] |
|
You may have noticed that the syntax of this inline element is the |
same as that of the <<X41,BlockId block element>>, this is no |
coincidence since they are functionally equivalent. |
|
xref |
++++ |
Creates a hypertext link to a document anchor. |
|
<<<id>,<caption>>> |
xref:<id>[<caption>] |
|
The `<id>` refers to an anchor ID. The optional `<caption>` is the |
link's displayed text. Example: |
|
<<X21,attribute lists>> |
|
If `<caption>` is not specified then the displayed text is |
auto-generated: |
|
- The AsciiDoc 'xhtml11' and 'html5' backends display the `<id>` |
enclosed in square brackets. |
- If DocBook is produced the DocBook toolchain is responsible for the |
displayed text which will normally be the referenced figure, table |
or section title number followed by the element's title text. |
|
Here is an example: |
|
--------------------------------------------------------------------- |
[[tiger_image]] |
.Tyger tyger |
image::tiger.png[] |
|
This can be seen in <<tiger_image>>. |
--------------------------------------------------------------------- |
|
Linking to Local Documents |
^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Hypertext links to files on the local file system are specified using |
the 'link' inline macro. |
|
link:<target>[<caption>] |
|
The 'link' macro generates relative URLs. The link macro `<target>` is |
the target file name (relative to the file system location of the |
referring document). The optional `<caption>` is the link's displayed |
text. If `<caption>` is not specified then `<target>` is displayed. |
Example: |
|
link:downloads/foo.zip[download foo.zip] |
|
You can use the `<filename>#<id>` syntax to refer to an anchor within |
a target document but this usually only makes sense when targeting |
HTML documents. |
|
[[X9]] |
Images |
^^^^^^ |
Inline images are inserted into the output document using the 'image' |
macro. The inline syntax is: |
|
image:<target>[<attributes>] |
|
The contents of the image file `<target>` is displayed. To display the |
image its file format must be supported by the target backend |
application. HTML and DocBook applications normally support PNG or JPG |
files. |
|
`<target>` file name paths are relative to the location of the |
referring document. |
|
[[X55]] |
.Image macro attributes |
- The optional 'alt' attribute is also the first positional attribute, |
it specifies alternative text which is displayed if the output |
application is unable to display the image file (see also |
http://htmlhelp.com/feature/art3.htm[Use of ALT texts in IMGs]). For |
example: |
|
image:images/logo.png[Company Logo] |
|
- The optional 'title' attribute provides a title for the image. The |
<<X49,block image macro>> renders the title alongside the image. |
The inline image macro displays the title as a popup ``tooltip'' in |
visual browsers (AsciiDoc HTML outputs only). |
|
- The optional `width` and `height` attributes scale the image size |
and can be used in any combination. The units are pixels. The |
following example scales the previous example to a height of 32 |
pixels: |
|
image:images/logo.png["Company Logo",height=32] |
|
- The optional `link` attribute is used to link the image to an |
external document. The following example links a screenshot |
thumbnail to a full size version: |
|
image:screen-thumbnail.png[height=32,link="screen.png"] |
|
- The optional `scaledwidth` attribute is only used in DocBook block |
images (specifically for PDF documents). The following example |
scales the images to 75% of the available print width: |
|
image::images/logo.png[scaledwidth="75%",alt="Company Logo"] |
|
- The image `scale` attribute sets the DocBook `imagedata` element |
`scale` attribute. |
|
- The optional `align` attribute is used for horizontal image |
alignment. Allowed values are `center`, `left` and `right`. For |
example: |
|
image::images/tiger.png["Tiger image",align="left"] |
|
- The optional `float` attribute floats the image `left` or `right` on |
the page (works with HTML outputs only, has no effect on DocBook |
outputs). `float` and `align` attributes are mutually exclusive. |
Use the `unfloat::[]` block macro to stop floating. |
|
Comment Lines |
^^^^^^^^^^^^^ |
See <<X25,comment block macro>>. |
|
Block Macros |
~~~~~~~~~~~~ |
A Block macro reference must be contained in a single line separated |
either side by a blank line or a block delimiter. |
|
Block macros behave just like Inline macros, with the following |
differences: |
|
- They occur in a block context. |
- The default syntax is `<name>::<target>[<attrlist>]` (two |
colons, not one). |
- Markup template section names end in `-blockmacro` instead of |
`-inlinemacro`. |
|
Block Identifier |
^^^^^^^^^^^^^^^^ |
The Block Identifier macro sets the `id` attribute and has the same |
syntax as the <<X30,anchor inline macro>> since it performs |
essentially the same function -- block templates use the `id` |
attribute as a block element ID. For example: |
|
[[X30]] |
|
This is equivalent to the `[id="X30"]` <<X79,AttributeList element>>). |
|
[[X49]] |
Images |
^^^^^^ |
The 'image' block macro is used to display images in a block context. |
The syntax is: |
|
image::<target>[<attributes>] |
|
The block `image` macro has the same <<X55,macro attributes>> as it's |
<<X9,inline image macro>> counterpart. |
|
Block images can be titled by preceding the 'image' macro with a |
'BlockTitle'. DocBook toolchains normally number titled block images |
and optionally list them in an automatically generated 'List of |
Figures' backmatter section. |
|
This example: |
|
.Main circuit board |
image::images/layout.png[J14P main circuit board] |
|
is equivalent to: |
|
image::images/layout.png["J14P main circuit board", |
title="Main circuit board"] |
|
A title prefix that can be inserted with the `caption` attribute |
(HTML backends). For example: |
|
.Main circuit board |
[caption="Figure 2: "] |
image::images/layout.png[J14P main circuit board] |
|
[[X66]] |
.Embedding images in XHTML documents |
********************************************************************* |
If you define the `data-uri` attribute then images will be embedded in |
XHTML outputs using the |
http://en.wikipedia.org/wiki/Data:_URI_scheme[data URI scheme]. You |
can use the 'data-uri' attribute with the 'xhtml11' and 'html5' |
backends to produce single-file XHTML documents with embedded images |
and CSS, for example: |
|
$ asciidoc -a data-uri mydocument.txt |
|
[NOTE] |
====== |
- All current popular browsers support data URIs, although versions |
of Internet Explorer prior to version 8 do not. |
- Some browsers limit the size of data URIs. |
====== |
********************************************************************* |
|
[[X25]] |
Comment Lines |
^^^^^^^^^^^^^ |
Single lines starting with two forward slashes hard up against the |
left margin are treated as comments. Comment lines do not appear in |
the output unless the 'showcomments' attribute is defined. Comment |
lines have been implemented as both block and inline macros so a |
comment line can appear as a stand-alone block or within block elements |
that support inline macro expansion. Example comment line: |
|
// This is a comment. |
|
If the 'showcomments' attribute is defined comment lines are written |
to the output: |
|
- In DocBook the comment lines are enclosed by the 'remark' element |
(which may or may not be rendered by your toolchain). |
- The 'showcomments' attribute does not expose <<X26,Comment Blocks>>. |
Comment Blocks are never passed to the output. |
|
System Macros |
~~~~~~~~~~~~~ |
System macros are block macros that perform a predefined task and are |
hardwired into the asciidoc(1) program. |
|
- You can escape system macros with a leading backslash character |
(as you can with other macros). |
- The syntax and tasks performed by system macros is built into |
asciidoc(1) so they don't appear in configuration files. You can |
however customize the syntax by adding entries to a configuration |
file `[macros]` section. |
|
[[X63]] |
Include Macros |
^^^^^^^^^^^^^^ |
The `include` and `include1` system macros to include the contents of |
a named file into the source document. |
|
The `include` macro includes a file as if it were part of the parent |
document -- tabs are expanded and system macros processed. The |
contents of `include1` files are not subject to tab expansion or |
system macro processing nor are attribute or lower priority |
substitutions performed. The `include1` macro's intended use is to |
include verbatim embedded CSS or scripts into configuration file |
headers. Example: |
|
------------------------------------ |
\include::chapter1.txt[tabsize=4] |
------------------------------------ |
|
.Include macro behavior |
- If the included file name is specified with a relative path then the |
path is relative to the location of the referring document. |
- Include macros can appear inside configuration files. |
- Files included from within 'DelimitedBlocks' are read to completion |
to avoid false end-of-block underline termination. |
- Attribute references are expanded inside the include 'target'; if an |
attribute is undefined then the included file is silently skipped. |
- The 'tabsize' macro attribute sets the number of space characters to |
be used for tab expansion in the included file (not applicable to |
`include1` macro). |
- The 'depth' macro attribute sets the maximum permitted number of |
subsequent nested includes (not applicable to `include1` macro which |
does not process nested includes). Setting 'depth' to '1' disables |
nesting inside the included file. By default, nesting is limited to |
a depth of ten. |
- If the he 'warnings' attribute is set to 'False' (or any other |
Python literal that evaluates to boolean false) then no warning |
message is printed if the included file does not exist. By default |
'warnings' are enabled. |
- 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. To inhibit nested substitution in |
included files it is preferable to use the `include` macro and set |
the attribute `depth=1`. |
|
Conditional Inclusion Macros |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Lines of text in the source document can be selectively included or |
excluded from processing based on the existence (or not) of a document |
attribute. |
|
Document text between the `ifdef` and `endif` macros is included if a |
document attribute is defined: |
|
ifdef::<attribute>[] |
: |
endif::<attribute>[] |
|
Document text between the `ifndef` and `endif` macros is not included |
if a document attribute is defined: |
|
ifndef::<attribute>[] |
: |
endif::<attribute>[] |
|
`<attribute>` is an attribute name which is optional in the trailing |
`endif` macro. |
|
If you only want to process a single line of text then the text can be |
put inside the square brackets and the `endif` macro omitted, for |
example: |
|
ifdef::revnumber[Version number 42] |
|
Is equivalent to: |
|
ifdef::revnumber[] |
Version number 42 |
endif::revnumber[] |
|
'ifdef' and 'ifndef' macros also accept multiple attribute names: |
|
- Multiple ',' separated attribute names evaluate to defined if one |
or more of the attributes is defined, otherwise it's value is |
undefined. |
- Multiple '+' separated attribute names evaluate to defined if all |
of the attributes is defined, otherwise it's value is undefined. |
|
Document text between the `ifeval` and `endif` macros is included if |
the Python expression inside the square brackets is true. Example: |
|
ifeval::[{rs458}==2] |
: |
endif::[] |
|
- Document attribute references are expanded before the expression is |
evaluated. |
- If an attribute reference is undefined then the expression is |
considered false. |
|
Take a look at the `*.conf` configuration files in the AsciiDoc |
distribution for examples of conditional inclusion macro usage. |
|
Executable system macros |
^^^^^^^^^^^^^^^^^^^^^^^^ |
The 'eval', 'sys' and 'sys2' block macros exhibit the same behavior as |
their same named <<X24, system attribute references>>. The difference |
is that system macros occur in a block macro context whereas system |
attributes are confined to inline contexts where attribute |
substitution is enabled. |
|
The following example displays a long directory listing inside a |
literal block: |
|
------------------ |
sys::[ls -l *.txt] |
------------------ |
|
NOTE: There are no block macro versions of the 'eval3' and 'sys3' |
system attributes. |
|
Template System Macro |
^^^^^^^^^^^^^^^^^^^^^ |
The `template` block macro allows the inclusion of one configuration |
file template section within another. The following example includes |
the `[admonitionblock]` section in the `[admonitionparagraph]` |
section: |
|
[admonitionparagraph] |
template::[admonitionblock] |
|
.Template macro behavior |
- The `template::[]` macro is useful for factoring configuration file |
markup. |
- `template::[]` macros cannot be nested. |
- `template::[]` macro expansion is applied after all configuration |
files have been read. |
|
|
[[X77]] |
Passthrough macros |
~~~~~~~~~~~~~~~~~~ |
Passthrough macros are analogous to <<X76,passthrough blocks>> and are |
used to pass text directly to the output. The substitution performed |
on the text is determined by the macro definition but can be overridden |
by the `<subslist>`. The usual syntax is |
`<name>:<subslist>[<passtext>]` (for inline macros) and |
`<name>::<subslist>[<passtext>]` (for block macros). Passthroughs, by |
definition, take precedence over all other text substitutions. |
|
pass:: |
Inline and block. Passes text unmodified (apart from explicitly |
specified substitutions). Examples: |
|
pass:[<q>To be or not to be</q>] |
pass:attributes,quotes[<u>the '{author}'</u>] |
|
asciimath, latexmath:: |
Inline and block. Passes text unmodified. Used for |
<<X78,mathematical formulas>>. |
|
\+++:: |
Inline and block. The triple-plus passthrough is functionally |
identical to the 'pass' macro but you don't have to escape `]` |
characters and you can prefix with quoted attributes in the inline |
version. Example: |
|
Red [red]+++`sum_(i=1)\^n i=(n(n+1))/2`$+++ AsciiMathML formula |
|
$$:: |
Inline and block. The double-dollar passthrough is functionally |
identical to the triple-plus passthrough with one exception: special |
characters are escaped. Example: |
|
$$`[[a,b],[c,d]]((n),(k))`$$ |
|
[[X80]]`:: |
Text quoted with single backtick characters constitutes an 'inline |
literal' passthrough. The enclosed text is rendered in a monospaced |
font and is only subject to special character substitution. This |
makes sense since monospace text is usually intended to be rendered |
literally and often contains characters that would otherwise have to |
be escaped. If you need monospaced text containing inline |
substitutions use a <<X81,plus character instead of a backtick>>. |
|
Macro Definitions |
~~~~~~~~~~~~~~~~~ |
Each entry in the configuration `[macros]` section is a macro |
definition which can take one of the following forms: |
|
`<pattern>=<name>[<subslist]`:: Inline macro definition. |
`<pattern>=#<name>[<subslist]`:: Block macro definition. |
`<pattern>=+<name>[<subslist]`:: System macro definition. |
`<pattern>`:: Delete the existing macro with this `<pattern>`. |
|
`<pattern>` is a Python regular expression and `<name>` is the name of |
a markup template. If `<name>` is omitted then it is the value of the |
regular expression match group named 'name'. The optional |
`[<subslist]` is a comma-separated list of substitution names enclosed |
in `[]` brackets, it sets the default substitutions for passthrough |
text, if omitted then no passthrough substitutions are performed. |
|
.Pattern named groups |
The following named groups can be used in macro `<pattern>` regular |
expressions and are available as markup template attributes: |
|
name:: |
The macro name. |
|
target:: |
The macro target. |
|
attrlist:: |
The macro attribute list. |
|
passtext:: |
Contents of this group are passed unmodified to the output subject |
only to 'subslist' substitutions. |
|
subslist:: |
Processed as a comma-separated list of substitution names for |
'passtext' substitution, overrides the the macro definition |
'subslist'. |
|
.Here's what happens during macro substitution |
- Each contextually relevant macro 'pattern' from the `[macros]` |
section is matched against the input source line. |
- If a match is found the text to be substituted is loaded from a |
configuration markup template section named like |
`<name>-inlinemacro` or `<name>-blockmacro` (depending on the macro |
type). |
- Global and macro attribute list attributes are substituted in the |
macro's markup template. |
- The substituted template replaces the macro reference in the output |
document. |
|
|
[[X98]] |
HTML 5 audio and video block macros |
----------------------------------- |
The 'html5' backend 'audio' and 'video' block macros generate the HTML |
5 'audio' and 'video' elements respectively. They follow the usual |
AsciiDoc block macro syntax `<name>::<target>[<attrlist>]` where: |
|
[horizontal] |
`<name>`:: 'audio' or 'video'. |
`<target>`:: The URL or file name of the video or audio file. |
`<attrlist>`:: A list of named attributes (see below). |
|
.Audio macro attributes |
[options="header",cols="1,5",frame="topbot"] |
|==================================================================== |
|Name | Value |
|options |
|A comma separated list of one or more of the following items: |
'autoplay', 'loop' which correspond to the same-named HTML 5 'audio' |
element boolean attributes. By default the player 'controls' are |
enabled, include the 'nocontrols' option value to hide them. |
|==================================================================== |
|
.Video macro attributes |
[options="header",cols="1,5",frame="topbot"] |
|==================================================================== |
|Name | Value |
|height | The height of the player in pixels. |
|width | The width of the player in pixels. |
|poster | The URL or file name of an image representing the video. |
|options |
|A comma separated list of one or more of the following items: |
'autoplay', 'loop' and 'nocontrols'. The 'autoplay' and 'loop' options |
correspond to the same-named HTML 5 'video' element boolean |
attributes. By default the player 'controls' are enabled, include the |
'nocontrols' option value to hide them. |
|==================================================================== |
|
Examples: |
|
--------------------------------------------------------------------- |
audio::images/example.ogg[] |
|
video::gizmo.ogv[width=200,options="nocontrols,autoplay"] |
|
.Example video |
video::gizmo.ogv[] |
|
video::http://www.808.dk/pics/video/gizmo.ogv[] |
--------------------------------------------------------------------- |
|
If your needs are more complex put raw HTML 5 in a markup block, for |
example (from http://www.808.dk/?code-html-5-video): |
|
--------------------------------------------------------------------- |
++++ |
<video poster="pics/video/gizmo.jpg" id="video" style="cursor: pointer;" > |
<source src="pics/video/gizmo.mp4" /> |
<source src="pics/video/gizmo.webm" type="video/webm" /> |
<source src="pics/video/gizmo.ogv" type="video/ogg" /> |
Video not playing? <a href="pics/video/gizmo.mp4">Download file</a> instead. |
</video> |
|
<script type="text/javascript"> |
var video = document.getElementById('video'); |
video.addEventListener('click',function(){ |
video.play(); |
},false); |
</script> |
++++ |
--------------------------------------------------------------------- |
|
|
Tables |
------ |
The AsciiDoc table syntax looks and behaves like other delimited block |
types and supports standard <<X73,block configuration entries>>. |
Formatting is easy to read and, just as importantly, easy to enter. |
|
- Cells and columns can be formatted using built-in customizable styles. |
- Horizontal and vertical cell alignment can be set on columns and |
cell. |
- Horizontal and vertical cell spanning is supported. |
|
.Use tables sparingly |
********************************************************************* |
When technical users first start creating documents, tables (complete |
with column spanning and table nesting) are often considered very |
important. The reality is that tables are seldom used, even in |
technical documentation. |
|
Try this exercise: thumb through your library of technical books, |
you'll be surprised just how seldom tables are actually used, even |
less seldom are tables containing block elements (such as paragraphs |
or lists) or spanned cells. This is no accident, like figures, tables |
are outside the normal document flow -- tables are for consulting not |
for reading. |
|
Tables are designed for, and should normally only be used for, |
displaying column oriented tabular data. |
********************************************************************* |
|
Example tables |
~~~~~~~~~~~~~~ |
|
.Simple table |
[width="15%"] |
|======= |
|1 |2 |A |
|3 |4 |B |
|5 |6 |C |
|======= |
|
.AsciiDoc source |
--------------------------------------------------------------------- |
[width="15%"] |
|======= |
|1 |2 |A |
|3 |4 |B |
|5 |6 |C |
|======= |
--------------------------------------------------------------------- |
|
.Columns formatted with strong, monospaced and emphasis styles |
[width="50%",cols=">s,^m,e",frame="topbot",options="header,footer"] |
|========================== |
| 2+|Columns 2 and 3 |
|1 |Item 1 |Item 1 |
|2 |Item 2 |Item 2 |
|3 |Item 3 |Item 3 |
|4 |Item 4 |Item 4 |
|footer 1|footer 2|footer 3 |
|========================== |
|
.AsciiDoc source |
--------------------------------------------------------------------- |
.An example table |
[width="50%",cols=">s,^m,e",frame="topbot",options="header,footer"] |
|========================== |
| 2+|Columns 2 and 3 |
|1 |Item 1 |Item 1 |
|2 |Item 2 |Item 2 |
|3 |Item 3 |Item 3 |
|4 |Item 4 |Item 4 |
|footer 1|footer 2|footer 3 |
|========================== |
--------------------------------------------------------------------- |
|
.Horizontal and vertical source data |
[width="80%",cols="3,^2,^2,10",options="header"] |
|========================================================= |
|Date |Duration |Avg HR |Notes |
|
|22-Aug-08 |10:24 | 157 | |
Worked out MSHR (max sustainable heart rate) by going hard |
for this interval. |
|
|22-Aug-08 |23:03 | 152 | |
Back-to-back with previous interval. |
|
|24-Aug-08 |40:00 | 145 | |
Moderately hard interspersed with 3x 3min intervals (2min |
hard + 1min really hard taking the HR up to 160). |
|
|========================================================= |
|
Short cells can be entered horizontally, longer cells vertically. The |
default behavior is to strip leading and trailing blank lines within a |
cell. These characteristics aid readability and data entry. |
|
.AsciiDoc source |
--------------------------------------------------------------------- |
.Windtrainer workouts |
[width="80%",cols="3,^2,^2,10",options="header"] |
|========================================================= |
|Date |Duration |Avg HR |Notes |
|
|22-Aug-08 |10:24 | 157 | |
Worked out MSHR (max sustainable heart rate) by going hard |
for this interval. |
|
|22-Aug-08 |23:03 | 152 | |
Back-to-back with previous interval. |
|
|24-Aug-08 |40:00 | 145 | |
Moderately hard interspersed with 3x 3min intervals (2min |
hard + 1min really hard taking the HR up to 160). |
|
|========================================================= |
--------------------------------------------------------------------- |
|
.A table with externally sourced CSV data |
[format="csv",cols="^1,4*2",options="header"] |
|=================================================== |
ID,Customer Name,Contact Name,Customer Address,Phone |
include::customers.csv[] |
|=================================================== |
|
.AsciiDoc source |
--------------------------------------------------------------------- |
[format="csv",cols="^1,4*2",options="header"] |
|=================================================== |
ID,Customer Name,Contact Name,Customer Address,Phone |
\include::customers.csv[] |
|=================================================== |
--------------------------------------------------------------------- |
|
|
.Cell spans, alignments and styles |
[cols="e,m,^,>s",width="25%"] |
|============================ |
|1 >s|2 |3 |4 |
^|5 2.2+^.^|6 .3+<.>m|7 |
^|8 |
|9 2+>|10 |
|============================ |
|
.AsciiDoc source |
--------------------------------------------------------------------- |
[cols="e,m,^,>s",width="25%"] |
|============================ |
|1 >s|2 |3 |4 |
^|5 2.2+^.^|6 .3+<.>m|7 |
^|8 |
|9 2+>|10 |
|============================ |
--------------------------------------------------------------------- |
|
[[X68]] |
Table input data formats |
~~~~~~~~~~~~~~~~~~~~~~~~ |
AsciiDoc table data can be 'psv', 'dsv' or 'csv' formatted. The |
default table format is 'psv'. |
|
AsciiDoc 'psv' ('Prefix Separated Values') and 'dsv' ('Delimiter |
Separated Values') formats are cell oriented -- the table is treated |
as a sequence of cells -- there are no explicit row separators. |
|
- 'psv' prefixes each cell with a separator whereas 'dsv' delimits |
cells with a separator. |
- 'psv' and 'dsv' separators are Python regular expressions. |
- The default 'psv' separator contains <<X84, cell specifier>> related |
named regular expression groups. |
- The default 'dsv' separator is `:|\n` (a colon or a new line |
character). |
- 'psv' and 'dsv' cell separators can be escaped by preceding them |
with a backslash character. |
|
Here are four 'psv' cells (the second item spans two columns; the |
last contains an escaped separator): |
|
|One 2+|Two and three |A \| separator character |
|
'csv' is the quasi-standard row oriented 'Comma Separated Values |
(CSV)' format commonly used to import and export spreadsheet and |
database data. |
|
[[X69]] |
Table attributes |
~~~~~~~~~~~~~~~~ |
Tables can be customized by the following attributes: |
|
format:: |
'psv' (default), 'dsv' or 'csv' (See <<X68, Table Data Formats>>). |
|
separator:: |
The cell separator. A Python regular expression ('psv' and 'dsv' |
formats) or a single character ('csv' format). |
|
frame:: |
Defines the table border and can take the following values: 'topbot' |
(top and bottom), 'all' (all sides), 'none' and 'sides' (left and |
right sides). The default value is 'all'. |
|
grid:: |
Defines which ruler lines are drawn between table rows and columns. |
The 'grid' attribute value can be any of the following values: 'none', |
'cols', 'rows' and 'all'. The default value is 'all'. |
|
align:: |
Use the 'align' attribute to horizontally align the table on the |
page (works with HTML outputs only, has no effect on DocBook outputs). |
The following values are valid: 'left', 'right', and 'center'. |
|
float:: |
Use the 'float' attribute to float the table 'left' or 'right' on the |
page (works with HTML outputs only, has no effect on DocBook outputs). |
Floating only makes sense in conjunction with a table 'width' |
attribute value of less than 100% (otherwise the table will take up |
all the available space). 'float' and 'align' attributes are mutually |
exclusive. Use the `unfloat::[]` block macro to stop floating. |
|
halign:: |
Use the 'halign' attribute to horizontally align all cells in a table. |
The following values are valid: 'left', 'right', and 'center' |
(defaults to 'left'). Overridden by <<X70,Column specifiers>> and |
<<X84,Cell specifiers>>. |
|
valign:: |
Use the 'valign' attribute to vertically align all cells in a table. |
The following values are valid: 'top', 'bottom', and 'middle' |
(defaults to 'top'). Overridden by <<X70,Column specifiers>> and |
<<X84,Cell specifiers>>. |
|
options:: |
The 'options' attribute can contain comma separated values, for |
example: 'header', 'footer'. By default header and footer rows are |
omitted. See <<X74,attribute options>> for a complete list of |
available table options. |
|
cols:: |
The 'cols' attribute is a comma separated list of <<X70,column |
specifiers>>. For example `cols="2<p,2*,4p,>"`. |
|
- If 'cols' is present it must specify all columns. |
- If the 'cols' attribute is not specified the number of columns is |
calculated as the number of data items in the *first line* of the |
table. |
- The degenerate form for the 'cols' attribute is an integer |
specifying the number of columns e.g. `cols=4`. |
|
width:: |
The 'width' attribute is expressed as a percentage value |
('"1%"'...'"99%"'). The width specifies the table width relative to |
the available width. HTML backends use this value to set the table |
width attribute. It's a bit more complicated with DocBook, see the |
<<X89,DocBook table widths>> sidebar. |
|
filter:: |
The 'filter' attribute defines an external shell command that is |
invoked for each cell. The built-in 'asciidoc' table style is |
implemented using a filter. |
|
[[X89]] |
.DocBook table widths |
********************************************************************** |
The AsciiDoc docbook backend generates CALS tables. CALS tables do not |
support a table width attribute -- table width can only be controlled |
by specifying absolute column widths. |
|
Specifying absolute column widths is not media independent because |
different presentation media have different physical dimensions. To |
get round this limitation both |
http://www.sagehill.net/docbookxsl/Tables.html#TableWidth[DocBook XSL |
Stylesheets] and |
http://dblatex.sourceforge.net/doc/manual/ch03s05.html#sec-table-width[dblatex] |
have implemented table width processing instructions for setting the |
table width as a percentage of the available width. AsciiDoc emits |
these processing instructions if the 'width' attribute is set along |
with proportional column widths (the AsciiDoc docbook backend |
'pageunits' attribute defaults to '*'). |
|
To generate DocBook tables with absolute column widths set the |
'pageunits' attribute to a CALS absolute unit such as 'pt' and set the |
'pagewidth' attribute to match the width of the presentation media. |
********************************************************************** |
|
[[X70]] |
Column Specifiers |
~~~~~~~~~~~~~~~~~ |
Column specifiers define how columns are rendered and appear in the |
table <<X69,cols attribute>>. A column specifier consists of an |
optional column multiplier followed by optional alignment, width and |
style values and is formatted like: |
|
[<multiplier>*][<align>][<width>][<style>] |
|
- All components are optional. The multiplier must be first and the |
style last. The order of `<align>` or `<width>` is not important. |
- Column `<width>` can be either an integer proportional value (1...) |
or a percentage (1%...100%). The default value is 1. To ensure |
portability across different backends, there is no provision for |
absolute column widths (not to be confused with output column width |
<<X72,markup attributes>> which are available in both percentage and |
absolute units). |
- The '<align>' column alignment specifier is formatted like: |
|
[<horizontal>][.<vertical>] |
+ |
Where `<horizontal>` and `<vertical>` are one of the following |
characters: `<`, `^` or `>` which represent 'left', 'center' and |
'right' horizontal alignment or 'top', 'middle' and 'bottom' vertical |
alignment respectively. |
|
- A `<multiplier>` can be used to specify repeated columns e.g. |
`cols="4*<"` specifies four left-justified columns. The default |
multiplier value is 1. |
- The `<style>` name specifies a <<X71,table style>> to used to markup |
column cells (you can use the full style names if you wish but the |
first letter is normally sufficient). |
- Column specific styles are not applied to header rows. |
|
[[X84]] |
Cell Specifiers |
~~~~~~~~~~~~~~~ |
Cell specifiers allow individual cells in 'psv' formatted tables to be |
spanned, multiplied, aligned and styled. Cell specifiers prefix 'psv' |
`|` delimiters and are formatted like: |
|
[<span>*|+][<align>][<style>] |
|
- '<span>' specifies horizontal and vertical cell spans ('+' operator) or |
the number of times the cell is replicated ('*' operator). '<span>' |
is formatted like: |
|
[<colspan>][.<rowspan>] |
+ |
Where `<colspan>` and `<rowspan>` are integers specifying the number of |
columns and rows to span. |
|
- `<align>` specifies horizontal and vertical cell alignment an is the |
same as in <<X70,column specifiers>>. |
- A `<style>` value is the first letter of <<X71,table style>> name. |
|
For example, the following 'psv' formatted cell will span two columns |
and the text will be centered and emphasized: |
|
`2+^e| Cell text` |
|
[[X71]] |
Table styles |
~~~~~~~~~~~~ |
Table styles can be applied to the entire table (by setting the |
'style' attribute in the table's attribute list) or on a per column |
basis (by specifying the style in the table's <<X69,cols attribute>>). |
Table data can be formatted using the following predefined styles: |
|
default:: |
The default style: AsciiDoc inline text formatting; blank lines are |
treated as paragraph breaks. |
|
emphasis:: |
Like default but all text is emphasised. |
|
monospaced:: |
Like default but all text is in a monospaced font. |
|
strong:: |
Like default but all text is bold. |
|
header:: |
Apply the same style as the table header. Normally used to create a |
vertical header in the first column. |
|
asciidoc:: |
With this style table cells can contain any of the AsciiDoc elements |
that are allowed inside document sections. This style runs asciidoc(1) |
as a filter to process cell contents. See also <<X83,Docbook table |
limitations>>. |
|
literal:: |
No text formatting; monospaced font; all line breaks are retained |
(the same as the AsciiDoc <<X65,LiteralBlock>> element). |
|
verse:: |
All line breaks are retained (just like the AsciiDoc <<X94,verse |
paragraph style>>). |
|
[[X72]] |
Markup attributes |
~~~~~~~~~~~~~~~~~ |
AsciiDoc makes a number of attributes available to table markup |
templates and tags. Column specific attributes are available when |
substituting the 'colspec' cell data tags. |
|
pageunits:: |
DocBook backend only. Specifies table column absolute width units. |
Defaults to '*'. |
|
pagewidth:: |
DocBook backend only. The nominal output page width in 'pageunit' |
units. Used to calculate CALS tables absolute column and table |
widths. Defaults to '425'. |
|
tableabswidth:: |
Integer value calculated from 'width' and 'pagewidth' attributes. |
In 'pageunit' units. |
|
tablepcwidth:: |
Table width expressed as a percentage of the available width. Integer |
value (0..100). |
|
colabswidth:: |
Integer value calculated from 'cols' column width, 'width' and |
'pagewidth' attributes. In 'pageunit' units. |
|
colpcwidth:: |
Column width expressed as a percentage of the table width. Integer |
value (0..100). |
|
colcount:: |
Total number of table columns. |
|
rowcount:: |
Total number of table rows. |
|
halign:: |
Horizontal cell content alignment: 'left', 'right' or 'center'. |
|
valign:: |
Vertical cell content alignment: 'top', 'bottom' or 'middle'. |
|
colnumber, colstart:: |
The number of the leftmost column occupied by the cell (1...). |
|
colend:: |
The number of the rightmost column occupied by the cell (1...). |
|
colspan:: |
Number of columns the cell should span. |
|
rowspan:: |
Number of rows the cell should span (1...). |
|
morerows:: |
Number of additional rows the cell should span (0...). |
|
Nested tables |
~~~~~~~~~~~~~ |
An alternative 'psv' separator character '!' can be used (instead of |
'|') in nested tables. This allows a single level of table nesting. |
Columns containing nested tables must use the 'asciidoc' style. An |
example can be found in `./examples/website/newtables.txt`. |
|
[[X83]] |
DocBook table limitations |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
Fully implementing tables is not trivial, some DocBook toolchains do |
better than others. AsciiDoc HTML table outputs are rendered |
correctly in all the popular browsers -- if your DocBook generated |
tables don't look right compare them with the output generated by the |
AsciiDoc 'xhtml11' backend or try a different DocBook toolchain. Here |
is a list of things to be aware of: |
|
- Although nested tables are not legal in DocBook 4 the FOP and |
dblatex toolchains will process them correctly. If you use `a2x(1)` |
you will need to include the `--no-xmllint` option to suppress |
DocBook validation errors. |
+ |
NOTE: In theory you can nest DocBook 4 tables one level using the |
'entrytbl' element, but not all toolchains process 'entrytbl'. |
|
- DocBook only allows a subset of block elements inside table cells so |
not all AsciiDoc elements produce valid DocBook inside table cells. |
If you get validation errors running `a2x(1)` try the `--no-xmllint` |
option, toolchains will often process nested block elements such as |
sidebar blocks and floating titles correctly even though, strictly |
speaking, they are not legal. |
|
- Text formatting in cells using the 'monospaced' table style will |
raise validation errors because the DocBook 'literal' element was |
not designed to support formatted text (using the 'literal' element |
is a kludge on the part of AsciiDoc as there is no easy way to set |
the font style in DocBook. |
|
- Cell alignments are ignored for 'verse', 'literal' or 'asciidoc' |
table styles. |
|
|
[[X1]] |
Manpage Documents |
----------------- |
Sooner or later, if you program in a UNIX environment, you're going |
to have to write a man page. |
|
By observing a couple of additional conventions (detailed below) you |
can write AsciiDoc files that will generate HTML and PDF man pages |
plus the native manpage roff format. The easiest way to generate roff |
manpages from AsciiDoc source is to use the a2x(1) command. The |
following example generates a roff formatted manpage file called |
`asciidoc.1` (a2x(1) uses asciidoc(1) to convert `asciidoc.1.txt` to |
DocBook which it then converts to roff using DocBook XSL Stylesheets): |
|
a2x --doctype manpage --format manpage asciidoc.1.txt |
|
.Viewing and printing manpage files |
********************************************************************** |
Use the `man(1)` command to view the manpage file: |
|
$ man -l asciidoc.1 |
|
To print a high quality man page to a postscript printer: |
|
$ man -l -Tps asciidoc.1 | lpr |
|
You could also create a PDF version of the man page by converting |
PostScript to PDF using `ps2pdf(1)`: |
|
$ man -l -Tps asciidoc.1 | ps2pdf - asciidoc.1.pdf |
|
The `ps2pdf(1)` command is included in the Ghostscript distribution. |
********************************************************************** |
|
To find out more about man pages view the `man(7)` manpage |
(`man 7 man` and `man man-pages` commands). |
|
|
Document Header |
~~~~~~~~~~~~~~~ |
A manpage 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. |
|
The NAME Section |
~~~~~~~~~~~~~~~~ |
The first manpage section is mandatory, must be titled 'NAME' and must |
contain a single paragraph (usually a single line) consisting 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 |
|
The SYNOPSIS Section |
~~~~~~~~~~~~~~~~~~~~ |
The second manpage section is mandatory and must be titled 'SYNOPSIS'. |
|
refmiscinfo attributes |
~~~~~~~~~~~~~~~~~~~~~~ |
In addition to the automatically created man page <<X60,intrinsic |
attributes>> you can assign DocBook |
http://www.docbook.org/tdg5/en/html/refmiscinfo.html[refmiscinfo] |
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 |
|
|
[[X78]] |
Mathematical Formulas |
--------------------- |
The 'asciimath' and 'latexmath' <<X77,passthrough macros>> along with |
'asciimath' and 'latexmath' <<X76,passthrough blocks>> 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 MathML' in XHTML outputs. 'LaTeX Math' applies to DocBook |
outputs that are processed by <<X31,dblatex>> and is normally used to |
generate PDF files. 'LaTeXMathML' is very much a subset of 'LaTeX |
Math' and applies to XHTML documents. |
|
LaTeX Math |
~~~~~~~~~~ |
ftp://ftp.ams.org/pub/tex/doc/amsmath/short-math-guide.pdf[LaTeX |
math] can be included in documents that are processed by |
<<X31,dblatex(1)>>. Example inline formula: |
|
latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$] |
|
For more examples see the {website}[AsciiDoc website] or the |
distributed `doc/latexmath.txt` file. |
|
ASCIIMathML |
~~~~~~~~~~~ |
///////////////////////////////////////////////////////////////////// |
The older ASCIIMathML 1.47 version is used instead of version 2 |
because: |
|
1. Version 2 doesn't work when embedded. |
2. Version 2 is much larger. |
///////////////////////////////////////////////////////////////////// |
|
http://www1.chapman.edu/~jipsen/mathml/asciimath.html[ASCIIMathML] |
formulas can be included in XHTML documents generated using the |
'xhtml11' and 'html5' backends. To enable 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 the {website}[AsciiDoc website] or the |
distributed `doc/asciimathml.txt` file. |
|
LaTeXMathML |
~~~~~~~~~~~ |
///////////////////////////////////////////////////////////////////// |
There is an http://math.etsu.edu/LaTeXMathML/[extended LaTeXMathML |
version] by Jeff Knisley, in addition to a JavaScript file it requires |
the inclusion of a CSS file. |
///////////////////////////////////////////////////////////////////// |
|
'LaTeXMathML' allows LaTeX Math style formulas to be included in XHTML |
documents generated using the AsciiDoc 'xhtml11' and 'html5' backends. |
AsciiDoc uses the |
http://www.maths.nottingham.ac.uk/personal/drw/lm.html[original |
LaTeXMathML] by Douglas Woodall. 'LaTeXMathML' is derived from |
ASCIIMathML 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 the {website}[AsciiDoc website] or the |
distributed `doc/latexmathml.txt` file. |
|
MathML |
~~~~~~ |
http://www.w3.org/Math/[MathML] is a low level XML markup for |
mathematics. AsciiDoc has no macros for MathML but users familiar with |
this markup could use passthrough macros and passthrough blocks to |
include MathML in output documents. |
|
|
[[X7]] |
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. |
|
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 configuration. |
|
TIP: The best way to learn about configuration files is to read the |
default configuration files in the AsciiDoc distribution in |
conjunction 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 reserved by the backend markup. |
tags:: |
Backend markup tags. |
quotes:: |
Definitions for quoted inline character formatting. |
specialwords:: |
Lists of words and phrases singled out for special markup. |
replacements, replacements2, replacements3:: |
Find and 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. |
|
Each line of text in these sections is a 'section entry'. Section |
entries share the following syntax: |
|
name=value:: |
The entry value is set to value. |
name=:: |
The entry value is set to a zero length string. |
name!:: |
The entry is undefined (deleted from the configuration). This |
syntax only applies to 'attributes' and 'miscellaneous' |
sections. |
|
.Section 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, tag entry names and markup template section names |
consist of one or more alphanumeric, underscore or 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). |
|
|
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 (useful when piping included files through block |
filters). Included files can override this option using the |
'tabsize' attribute. |
pagewidth, pageunits:: |
These global table related options are documented in the |
<<X4,Table Configuration File Definitions>> sub-section. |
|
NOTE: `[miscellaneous]` configuration file entries can be set using |
the asciidoc(1) `-a` (`--attribute`) command-line option. |
|
Titles section |
~~~~~~~~~~~~~~ |
sectiontitle:: |
Two line section title pattern. The entry value is a Python |
regular expression containing the named group 'title'. |
|
underlines:: |
A comma separated list 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="==","--","~~","^^","++" |
|
sect0...sect4:: |
One line section title patterns. The entry value is a Python |
regular expression containing the named group 'title'. |
|
blocktitle:: |
<<X42,BlockTitle element>> pattern. The entry value is a |
Python regular expression containing the named group 'title'. |
|
subs:: |
A comma separated list of substitutions that are performed on |
the document header and section titles. Defaults to 'normal' |
substitution. |
|
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. |
|
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. |
|
To delete a attribute insert a `name!` entry in a downstream |
configuration file or use the asciidoc(1) `--attribute name!` |
command-line option (an attribute name suffixed with a `!` character |
deletes the attribute) |
|
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 and greater than characters). The following example causes |
all occurrences of the `<` character to be replaced by `<`. |
|
<=< |
|
Quoted Text section |
~~~~~~~~~~~~~~~~~~~ |
Quoting is used primarily for text formatting. The `[quotes]` section |
defines AsciiDoc quoting characters and their corresponding 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 |
|
[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] |
^= |
~= |
|
<<X52,Unconstrained quotes>> are differentiated from constrained |
quotes by prefixing the tag name with a hash character, for example: |
|
__=#emphasis |
|
.Quoted text behavior |
- Quote characters must be non-alphanumeric. |
- To minimize quoting ambiguity try not to use the same quote |
characters in different quote types. |
|
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 any occurrence 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. |
|
.Special 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{nbsp}[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. |
|
[[X10]] |
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 'replacement2' are applied |
in <<X102,normal>> substitution contexts whereas 'replacements3' needs |
to be configured explicitly and should only be used in backend |
configuration files. |
|
.Replacement 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 expression you need to |
be careful to escape regular expression special characters. |
- Replacements are performed in the same order they appear in the |
configuration file replacements section. |
|
Markup Template Sections |
~~~~~~~~~~~~~~~~~~~~~~~~ |
Markup template sections supply backend markup for translating |
AsciiDoc elements. Since the text is normally backend dependent |
you'll find these sections in the backend specific configuration |
files. Template sections differ from other sections in that they |
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. |
|
[[X27]] |
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 configuration |
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. |
5. Explicit configuration files specified using: |
- The `conf-files` attribute (one or more file names separated by a |
`|` character). These files are loaded in the order they are |
specified and prior to files specified using 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 they |
appear on the command-line. |
6. <<X100,Backend plugin>> configuration files are loaded from |
subdirectories named like `backends/<backend>` in locations 1, 2 |
and 3. |
7. <<X59,Filter>> configuration 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` in location 4. |
- The document header is parsed at this point and we can assume the |
'backend' and 'doctype' have now been defined. |
- Backend plugin `<backend>.conf` and `<backend>-<doctype>.conf` files |
from locations 6. If a backend plugin is 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 specified by the asciidoc(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. |
|
[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. |
|
|
Document Attributes |
------------------- |
A document attribute is comprised of a 'name' and a textual 'value' |
and is used for textual substitution in AsciiDoc documents and |
configuration files. An attribute reference (an attribute name |
enclosed in braces) is replaced by the corresponding attribute |
value. Attribute names are case insensitive and can only 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. |
|
|
[[X18]] |
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: |
|
: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>!: |
|
.AttributeEntry 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 the <<X77,pass:[] |
inline macro>> 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 this <<X95,document header>>: |
|
--------------------------------------------------------------------- |
AsciiDoc User Manual |
==================== |
Stuart Rackham <srackham@gmail.com> |
5.1.1, April 23, 2004 |
--------------------------------------------------------------------- |
|
Setting configuration entries |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
A variant of the Attribute Entry syntax allows configuration file |
section entries and markup template sections to be set from within an |
AsciiDoc document: |
|
:<section_name>.[<entry_name>]: <entry_value> |
|
Where `<section_name>` is the configuration section name, |
`<entry_name>` is the name of the entry and `<entry_value>` is the |
optional entry value. This example sets the default labeled list |
style to 'horizontal': |
|
:listdef-labeled.style: horizontal |
|
It is exactly equivalent to a configuration file containing: |
|
[listdef-labeled] |
style=horizontal |
|
- If the `<entry_name>` is omitted then the entire section is |
substituted with the `<entry_value>`. This feature should only be |
used to set markup template sections. The following example sets the |
'xref2' inline macro markup template: |
|
:xref2-inlinemacro.: <a href="#{1}">{2?{2}}</a> |
|
- No substitution is performed on configuration file attribute entries |
and they cannot be undefined. |
- This feature can only be used in attribute entries -- configuration |
attributes cannot be set using the asciidoc(1) command `--attribute` |
option. |
|
[[X62]] |
.Attribute entries promote clarity and eliminate repetition |
********************************************************************* |
URLs and file names in AsciiDoc macros are often quite long -- they |
break paragraph flow and readability suffers. The problem is |
compounded by redundancy if the same name is used repeatedly. |
Attribute entries can be used to make your documents easier to read |
and write, here are some examples: |
|
:1: http://freshmeat.net/projects/asciidoc/ |
:homepage: http://methods.co.nz/asciidoc/[AsciiDoc home page] |
:new: image:./images/smallnew.png[] |
:footnote1: footnote:[A meaningless latin term] |
|
Using previously defined attributes: See the {1}[Freshmeat summary] |
or the {homepage} for something new {new}. Lorem ispum {footnote1}. |
|
.Note |
- The attribute entry definition must precede it's usage. |
- You are not limited to URLs or file names, entire macro calls or |
arbitrary lines of text can be abbreviated. |
- Shared attributes entries could be grouped into a separate file and |
<<X63,included>> in multiple documents. |
********************************************************************* |
|
|
[[X21]] |
Attribute Lists |
--------------- |
- An attribute list is a comma separated list of attribute values. |
- The entire list is enclosed in square brackets. |
- Attribute lists are used to pass parameters to macros, blocks (using |
the <<X79,AttributeList element>>) and inline quotes. |
|
The list consists of zero or more positional attribute values followed |
by zero or more named attribute values. Here are three examples: a |
single unquoted positional attribute; three unquoted positional |
attribute values; one positional attribute followed by two named |
attributes; the unquoted attribute value in the final example contains |
comma (`,`) and double-quote (`"`) character entities: |
|
[Hello] |
[quote, Bertrand Russell, The World of Mathematics (1956)] |
["22 times", backcolor="#0e0e0e", options="noborders,wide"] |
[A footnote, "with an image" image:smallnew.png[]] |
|
.Attribute list behavior |
- If one or more attribute values contains a comma the all string |
values must be quoted (enclosed in double quotation mark |
characters). |
- If the list contains any named or quoted attributes then all string |
attribute values must be quoted. |
- To include a double quotation mark (") character in a quoted |
attribute value the the quotation mark must be escaped with a |
backslash. |
- List attributes take precedence over existing attributes. |
- List attributes can only be referenced in configuration file markup |
templates and tags, they are not available elsewhere in the |
document. |
- Setting a named attribute to `None` undefines the attribute. |
- Positional attributes are referred to as `{1}`,`{2}`,`{3}`,... |
- Attribute `{0}` refers to the entire list (excluding the enclosing |
square brackets). |
- Named attribute names cannot contain dash characters. |
|
[[X75]] |
Options attribute |
~~~~~~~~~~~~~~~~~ |
If the attribute list contains an attribute named `options` it is |
processed as a comma separated list of option names: |
|
- Each name generates an attribute named like `<option>-option` (where |
`<option>` is the option name) with an empty string value. For |
example `[options="opt1,opt2,opt3"]` is equivalent to setting the |
following three attributes |
`[opt1-option="",opt2-option="",opt2-option=""]`. |
- If you define a an option attribute globally (for example with an |
<<X18,attribute entry>>) then it will apply to all elements in the |
document. |
- AsciiDoc implements a number of predefined options which are listed |
in the <<X74,Attribute Options appendix>>. |
|
Macro Attribute lists |
~~~~~~~~~~~~~~~~~~~~~ |
Macros calls are suffixed with an attribute list. The list may be |
empty but it cannot be omitted. List entries are used to pass |
attribute values to macro markup templates. |
|
|
Attribute References |
-------------------- |
An attribute reference is an attribute name (possibly followed by an |
additional parameters) enclosed in curly braces. When an attribute |
reference is encountered it is evaluated and replaced by its |
corresponding text value. If the attribute is undefined the line |
containing the attribute is dropped. |
|
There are three types of attribute reference: 'Simple', 'Conditional' |
and 'System'. |
|
.Attribute reference evaluation |
- You can suppress attribute reference expansion by placing a |
backslash character immediately in front of the opening brace |
character. |
- By default attribute references are not expanded in |
'LiteralParagraphs', 'ListingBlocks' or 'LiteralBlocks'. |
- Attribute substitution proceeds line by line in reverse line order. |
- Attribute reference evaluation is performed in the following order: |
'Simple' then 'Conditional' and finally 'System'. |
|
Simple Attributes References |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Simple attribute references take the form `{<name>}`. If the |
attribute name is defined its text value is substituted otherwise the |
line containing the reference is dropped from the output. |
|
Conditional Attribute References |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Additional parameters are used in conjunction with attribute names to |
calculate a substitution value. Conditional attribute references take |
the following forms: |
|
`{<names>=<value>}`:: |
`<value>` is substituted if the attribute `<names>` is |
undefined otherwise its value is substituted. `<value>` can |
contain simple attribute references. |
|
`{<names>?<value>}`:: |
`<value>` is substituted if the attribute `<names>` is defined |
otherwise an empty string is substituted. `<value>` can |
contain simple attribute references. |
|
`{<names>!<value>}`:: |
`<value>` is substituted if the attribute `<names>` is |
undefined otherwise an empty string is substituted. `<value>` |
can contain simple attribute references. |
|
`{<names>#<value>}`:: |
`<value>` is substituted if the attribute `<names>` is defined |
otherwise the undefined attribute entry causes the containing |
line to be dropped. `<value>` can contain simple attribute |
references. |
|
`{<names>%<value>}`:: |
`<value>` is substituted if the attribute `<names>` is not |
defined otherwise the containing line is dropped. `<value>` |
can contain simple attribute references. |
|
`{<names>@<regexp>:<value1>[:<value2>]}`:: |
`<value1>` is substituted if the value of attribute `<names>` |
matches the regular expression `<regexp>` otherwise `<value2>` |
is substituted. If attribute `<names>` is not defined the |
containing line is dropped. If `<value2>` is omitted an empty |
string is assumed. The values and the regular expression can |
contain simple attribute references. To embed colons in the |
values or the regular expression escape them with backslashes. |
|
`{<names>$<regexp>:<value1>[:<value2>]}`:: |
Same behavior as the previous ternary attribute except for |
the following cases: |
|
`{<names>$<regexp>:<value>}`;; |
Substitutes `<value>` if `<names>` matches `<regexp>` |
otherwise the result is undefined and the containing |
line is dropped. |
|
`{<names>$<regexp>::<value>}`;; |
Substitutes `<value>` if `<names>` does not match |
`<regexp>` otherwise the result is undefined and the |
containing line is dropped. |
|
The attribute `<names>` parameter normally consists of a single |
attribute name but it can be any one of the following: |
|
- A single attribute name which evaluates to the attributes value. |
- Multiple ',' separated attribute names which evaluates to an empty |
string if one or more of the attributes is defined, otherwise it's |
value is undefined. |
- Multiple '+' separated attribute names which evaluates to an empty |
string if all of the attributes are defined, otherwise it's value is |
undefined. |
|
Conditional attributes with single attribute names are evaluated first |
so they can be used inside the multi-attribute conditional `<value>`. |
|
Conditional attribute examples |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Conditional attributes are mainly used in AsciiDoc configuration |
files -- see the distribution `.conf` files for examples. |
|
Attribute equality test:: |
If `{backend}` is 'docbook45' or 'xhtml11' the example evaluates to |
``DocBook 4.5 or XHTML 1.1 backend'' otherwise it evaluates to |
``some other backend'': |
|
{backend@docbook45|xhtml11:DocBook 4.5 or XHTML 1.1 backend:some other backend} |
|
Attribute value map:: |
This example maps the `frame` attribute values [`topbot`, `all`, |
`none`, `sides`] to [`hsides`, `border`, `void`, `vsides`]: |
|
{frame@topbot:hsides}{frame@all:border}{frame@none:void}{frame@sides:vsides} |
|
|
[[X24]] |
System Attribute References |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
System attribute references generate the attribute text value by |
executing a predefined action that is parametrized by one or more |
arguments. The syntax is `{<action>:<arguments>}`. |
|
`{counter:<attrname>[:<seed>]}`:: |
Increments the document attribute (if the attribute is |
undefined it is set to `1`). Returns the new attribute value. |
|
- Counters generate global (document wide) attributes. |
- The optional `<seed>` specifies the counter's initial value; |
it can be a number or a single letter; defaults to '1'. |
- `<seed>` can contain simple and conditional attribute |
references. |
- The 'counter' system attribute will not be executed if the |
containing line is dropped by the prior evaluation of an |
undefined attribute. |
|
`{counter2:<attrname>[:<seed>]}`:: |
Same as `counter` except the it always returns a blank string. |
|
`{eval:<expression>}`:: |
Substitutes the result of the Python `<expression>`. |
|
- If `<expression>` evaluates to `None` or `False` the |
reference is deemed undefined and the line containing the |
reference is dropped from the output. |
- If the expression evaluates to `True` the attribute |
evaluates to an empty string. |
- `<expression>` can contain simple and conditional attribute |
references. |
- The 'eval' system attribute can be nested inside other |
system attributes. |
|
`{eval3:<command>}`:: |
Passthrough version of `{eval:<expression>}` -- the generated |
output is written directly to the output without any further |
substitutions. |
|
`{include:<filename>}`:: |
Substitutes contents of the file named `<filename>`. |
|
- The included file is read at the time of attribute |
substitution. |
- If the file does not exist a warning is emitted and the line |
containing the reference is dropped from the output file. |
- Tabs are expanded based on the current 'tabsize' attribute |
value. |
|
`{set:<attrname>[!][:<value>]}`:: |
Sets or unsets document attribute. Normally only used in |
configuration file markup templates (use |
<<X18,AttributeEntries>> in AsciiDoc documents). |
|
- If the attribute name is followed by an exclamation mark |
the attribute becomes undefined. |
- If `<value>` is omitted the attribute is set to a blank |
string. |
- `<value>` can contain simple and conditional attribute |
references. |
- Returns a blank string unless the attribute is undefined in |
which case the return value is undefined and the enclosing |
line will be dropped. |
|
`{set2:<attrname>[!][:<value>]}`:: |
Same as `set` except that the attribute scope is local to the |
template. |
|
`{sys:<command>}`:: |
Substitutes the stdout generated by the execution of the shell |
`<command>`. |
|
`{sys2:<command>}`:: |
Substitutes the stdout and stderr generated by the execution |
of the shell `<command>`. |
|
`{sys3:<command>}`:: |
Passthrough version of `{sys:<command>}` -- the generated |
output is written directly to the output without any further |
substitutions. |
|
`{template:<template>}`:: |
Substitutes the contents of the configuration file section |
named `<template>`. Attribute references contained in the |
template are substituted. |
|
.System reference behavior |
- System attribute arguments can contain non-system attribute |
references. |
- Closing brace characters inside system attribute arguments must be |
escaped with a backslash. |
|
[[X60]] |
Intrinsic Attributes |
-------------------- |
Intrinsic attributes are simple attributes that are created |
automatically from: AsciiDoc document header parameters; asciidoc(1) |
command-line arguments; attributes defined in the default |
configuration files; the execution context. Here's the list of |
predefined intrinsic attributes: |
|
{amp} ampersand (&) character entity |
{asciidoc-args} used to pass inherited arguments to asciidoc filters |
{asciidoc-confdir} the asciidoc(1) global configuration directory |
{asciidoc-dir} the asciidoc(1) application directory |
{asciidoc-file} the full path name of the asciidoc(1) script |
{asciidoc-version} the version of asciidoc(1) |
{author} author's full name |
{authored} empty string '' if {author} or {email} defined, |
{authorinitials} author initials (from document header) |
{backend-<backend>} empty string '' |
{<backend>-<doctype>} empty string '' |
{backend} document backend specified by `-b` option |
{backend-confdir} the directory containing the <backend>.conf file |
{backslash} backslash character |
{basebackend-<base>} empty string '' |
{basebackend} html or docbook |
{blockname} current block name (note 8). |
{brvbar} broken vertical bar (|) character |
{docdate} document last modified date |
{docdir} document input directory name (note 5) |
{docfile} document file name (note 5) |
{docname} document file name without extension (note 6) |
{doctime} document last modified time |
{doctitle} document title (from document header) |
{doctype-<doctype>} empty string '' |
{doctype} document type specified by `-d` option |
{email} author's email address (from document header) |
{empty} empty string '' |
{encoding} specifies input and output encoding |
{filetype-<fileext>} empty string '' |
{filetype} output file name file extension |
{firstname} author first name (from document header) |
{gt} greater than (>) character entity |
{id} running block id generated by BlockId elements |
{indir} input file directory name (note 2,5) |
{infile} input file name (note 2,5) |
{lastname} author last name (from document header) |
{ldquo} Left double quote character (note 7) |
{level} title level 1..4 (in section titles) |
{listindex} the list index (1..) of the most recent list item |
{localdate} the current date |
{localtime} the current time |
{lsquo} Left single quote character (note 7) |
{lt} less than (<) character entity |
{manname} manpage name (defined in NAME section) |
{manpurpose} manpage (defined in NAME section) |
{mantitle} document title minus the manpage volume number |
{manvolnum} manpage volume number (1..8) (from document header) |
{middlename} author middle name (from document header) |
{nbsp} non-breaking space character entity |
{notitle} do not display the document title |
{outdir} document output directory name (note 2) |
{outfile} output file name (note 2) |
{python} the full path name of the Python interpreter executable |
{rdquo} Right double quote character (note 7) |
{reftext} running block xreflabel generated by BlockId elements |
{revdate} document revision date (from document header) |
{revnumber} document revision number (from document header) |
{rsquo} Right single quote character (note 7) |
{sectnum} formatted section number (in section titles) |
{sp} space character |
{showcomments} send comment lines to the output |
{title} section title (in titled elements) |
{two-colons} Two colon characters |
{two-semicolons} Two semicolon characters |
{user-dir} the ~/.asciidoc directory (if it exists) |
{verbose} defined as '' if --verbose command option specified |
{wj} Word-joiner |
{zwsp} Zero-width space character entity |
|
[NOTE] |
====== |
1. Intrinsic attributes are global so avoid defining custom attributes |
with the same names. |
2. `{outfile}`, `{outdir}`, `{infile}`, `{indir}` attributes are |
effectively read-only (you can set them but it won't affect the |
input or output file paths). |
3. See also the <<X88,Backend Attributes>> section for attributes |
that relate to AsciiDoc XHTML file generation. |
4. The entries that translate to blank strings are designed to be used |
for conditional text inclusion. You can also use the `ifdef`, |
`ifndef` and `endif` System macros for conditional inclusion. |
footnote:[Conditional inclusion using `ifdef` and `ifndef` macros |
differs from attribute conditional inclusion in that the former |
occurs when the file is read while the latter occurs when the |
contents are written.] |
5. `{docfile}` and `{docdir}` refer to root document specified on the |
asciidoc(1) command-line; `{infile}` and `{indir}` refer to the |
current input file which may be the root document or an included |
file. When the input is being read from the standard input |
(`stdin`) these attributes are undefined. |
6. If the input file is the standard input and the output file is not |
the standard output then `{docname}` is the output file name sans |
file extension. |
7. See |
http://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks[non-English |
usage of quotation marks]. |
8. The `{blockname}` attribute identifies the style of the current |
block. It applies to delimited blocks, lists and tables. Here is a |
list of `{blockname}` values (does not include filters or custom |
block and style names): |
|
delimited blocks:: comment, sidebar, open, pass, literal, verse, |
listing, quote, example, note, tip, important, caution, warning, |
abstract, partintro |
|
lists:: arabic, loweralpha, upperalpha, lowerroman, upperroman, |
labeled, labeled3, labeled4, qanda, horizontal, bibliography, |
glossary |
|
tables:: table |
|
====== |
|
|
[[X73]] |
Block Element Definitions |
------------------------- |
The syntax and behavior of Paragraph, DelimitedBlock, List and Table |
block elements is determined by block definitions contained in |
<<X7,AsciiDoc configuration file>> sections. |
|
Each definition consists of a section title followed by one or more |
section entries. Each entry defines a block parameter controlling some |
aspect of the block's behavior. Here's an example: |
|
--------------------------------------------------------------------- |
[blockdef-listing] |
delimiter=^-{4,}$ |
template=listingblock |
presubs=specialcharacters,callouts |
--------------------------------------------------------------------- |
|
Configuration file block definition sections are processed |
incrementally after each configuration file is loaded. Block |
definition section entries are merged into the block definition, this |
allows block parameters to be overridden and extended by later |
<<X27,loading configuration files>>. |
|
AsciiDoc Paragraph, DelimitedBlock, List and Table block elements |
share a common subset of configuration file parameters: |
|
delimiter:: |
A Python regular expression that matches the first line of a block |
element -- in the case of DelimitedBlocks and Tables it also matches |
the last line. |
|
template:: |
The name of the configuration file markup template section that will |
envelope the block contents. The pipe ('|') character is substituted |
for the block contents. List elements use a set of (list specific) |
tag parameters instead of a single template. The template name can |
contain attribute references allowing dynamic template selection a |
the time of template substitution. |
|
options:: |
A comma delimited list of element specific option names. In addition |
to being used internally, options are available during markup tag |
and template substitution as attributes with an empty string value |
named like `<option>-option` (where `<option>` is the option name). |
See <<X74,attribute options>> for a complete list of available |
options. |
|
subs, presubs, postsubs:: |
* 'presubs' and 'postsubs' are lists of comma separated substitutions that are |
performed on the block contents. 'presubs' is applied first, |
'postsubs' (if specified) second. |
|
* 'subs' is an alias for 'presubs'. |
|
* If a 'filter' is allowed (Paragraphs, DelimitedBlocks and Tables) |
and has been specified then 'presubs' and 'postsubs' substitutions |
are performed before and after the filter is run respectively. |
|
* Allowed values: 'specialcharacters', 'quotes', 'specialwords', |
'replacements', 'macros', 'attributes', 'callouts'. |
|
* [[X102]]The following composite values are also allowed: |
|
'none';; |
No substitutions. |
'normal';; |
The following substitutions in the following order: |
'specialcharacters', 'quotes', 'attributes', 'specialwords', |
'replacements', 'macros', 'replacements2'. |
'verbatim';; |
The following substitutions in the following order: |
'specialcharacters' and 'callouts'. |
|
* 'normal' and 'verbatim' substitutions can be redefined by with |
`subsnormal` and `subsverbatim` entries in a configuration file |
`[miscellaneous]` section. |
|
* The substitutions are processed in the order in which they are |
listed and can appear more than once. |
|
filter:: |
This optional entry specifies an executable shell command for |
processing block content (Paragraphs, DelimitedBlocks and Tables). |
The filter command can contain attribute references. |
|
posattrs:: |
Optional comma separated list of positional attribute names. This |
list maps positional attributes (in the block's <<X21,attribute |
list>>) to named block attributes. The following example, from the |
QuoteBlock definition, maps the first and section positional |
attributes: |
|
posattrs=attribution,citetitle |
|
style:: |
This optional parameter specifies the default style name. |
|
|
<stylename>-style:: |
Optional style definition (see <<X23,Styles>> below). |
|
The following block parameters behave like document attributes and can |
be set in block attribute lists and style definitions: 'template', |
'options', 'subs', 'presubs', 'postsubs', 'filter'. |
|
[[X23]] |
Styles |
~~~~~~ |
A style is a set of block parameter bundled as a single named |
parameter. The following example defines a style named 'verbatim': |
|
verbatim-style=template="literalblock",subs="verbatim" |
|
If a block's <<X21,attribute list>> contains a 'style' attribute then |
the corresponding style parameters are be merged into the default |
block definition parameters. |
|
- All style parameter names must be suffixed with `-style` and the |
style parameter value is in the form of a list of <<X21,named |
attributes>>. |
- The 'template' style parameter is mandatory, other parameters can be |
omitted in which case they inherit their values from the default |
block definition parameters. |
- Multi-item style parameters ('subs','presubs','postsubs','posattrs') |
must be specified using Python tuple syntax (rather than a simple |
list of values as they in separate entries) e.g. |
`postsubs=("callouts",)` not `postsubs="callouts"`. |
|
Paragraphs |
~~~~~~~~~~ |
Paragraph translation is controlled by `[paradef-*]` configuration |
file section entries. Users can define new types of paragraphs and |
modify the behavior of existing types by editing AsciiDoc |
configuration files. |
|
Here is the shipped Default paragraph definition: |
|
-------------------------------------------------------------------- |
[paradef-default] |
delimiter=(?P<text>\S.*) |
template=paragraph |
-------------------------------------------------------------------- |
|
The normal paragraph definition has a couple of special properties: |
|
1. It must exist and be defined in a configuration file section named |
`[paradef-default]`. |
2. Irrespective of its position in the configuration files default |
paragraph document matches are attempted only after trying all |
other paragraph types. |
|
Paragraph specific block parameter notes: |
|
delimiter:: |
This regular expression must contain the named group 'text' which |
matches the text on the first line. Paragraphs are terminated by a |
blank line, the end of file, or the start of a DelimitedBlock. |
|
options:: |
The 'listelement' option specifies that paragraphs of this type will |
automatically be considered part of immediately preceding list |
items. The 'skip' option causes the paragraph to be treated as a |
comment (see <<X26,CommentBlocks>>). |
|
.Paragraph processing proceeds as follows: |
1. The paragraph text is aligned to the left margin. |
2. Optional 'presubs' inline substitutions are performed on the |
paragraph text. |
3. If a filter command is specified it is executed and the paragraph |
text piped to its standard input; the filter output replaces the |
paragraph text. |
4. Optional 'postsubs' inline substitutions are performed on the |
paragraph text. |
5. The paragraph text is enveloped by the paragraph's markup template |
and written to the output file. |
|
Delimited Blocks |
~~~~~~~~~~~~~~~~ |
DelimitedBlock 'options' values are: |
|
sectionbody:: |
The block contents are processed as a SectionBody. |
|
skip:: |
The block is treated as a comment (see <<X26,CommentBlocks>>). |
Preceding <<X21,attribute lists>> and <<X42,block titles>> are not |
consumed. |
|
'presubs', 'postsubs' and 'filter' entries are ignored when |
'sectionbody' or 'skip' options are set. |
|
DelimitedBlock processing proceeds as follows: |
|
1. Optional 'presubs' substitutions are performed on the block |
contents. |
2. If a filter is specified it is executed and the block's contents |
piped to its standard input. The filter output replaces the block |
contents. |
3. Optional 'postsubs' substitutions are performed on the block |
contents. |
4. The block contents is enveloped by the block's markup template and |
written to the output file. |
|
TIP: Attribute expansion is performed on the block filter command |
before it is executed, this is useful for passing arguments to the |
filter. |
|
Lists |
~~~~~ |
List behavior and syntax is determined by `[listdef-*]` configuration |
file sections. The user can change existing list behavior and add new |
list types by editing configuration files. |
|
List specific block definition notes: |
|
type:: |
This is either 'bulleted','numbered','labeled' or 'callout'. |
|
delimiter:: |
A Python regular expression that matches the first line of a |
list element entry. This expression can contain the named groups |
'text' (bulleted groups), 'index' and 'text' (numbered lists), |
'label' and 'text' (labeled lists). |
|
tags:: |
The `<name>` of the `[listtags-<name>]` configuration file section |
containing list markup tag definitions. The tag entries ('list', |
'entry', 'label', 'term', 'text') map the AsciiDoc list structure to |
backend markup; see the 'listtags' sections in the AsciiDoc |
distributed backend `.conf` configuration files for examples. |
|
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. |
|
[[X4]] |
Table behavior is also influenced by the following `[miscellaneous]` |
configuration file entries: |
|
pagewidth:: |
This integer value is the printable width of the output media. See |
<<X69,table attributes>>. |
|
pageunits:: |
The units of width in output markup width attribute values. |
|
.Table definition behavior |
- The output markup generation is specifically designed to work with |
the HTML and CALS (DocBook) table models, but should be adaptable to |
most XML table schema. |
- Table definitions can be ``mixed in'' from multiple cascading |
configuration files. |
- New table definitions inherit the default table and table tags |
definitions (`[tabledef-default]` and `[tabletags-default]`) so you |
only need to override those conf file entries that require |
modification. |
|
|
[[X59]] |
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 |
configuration file definitions. |
|
There's nothing special about the filters, they're just standard UNIX |
filters: 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 unconditionally load a |
filter. |
|
Attribute substitution is performed on the filter command prior to |
execution -- attributes can be used to pass 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. |
|
Filter Search Paths |
~~~~~~~~~~~~~~~~~~~ |
If the filter command does not specify a directory path then |
asciidoc(1) recursively searches for the executable filter command: |
|
- 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. |
|
Filter Configuration Files |
~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Filters are normally accompanied by a configuration file containing a |
Paragraph or DelimitedBlock definition along with corresponding markup |
templates. |
|
While it is possible to create new 'Paragraph' or 'DelimitedBlock' |
definitions the preferred way to implement a filter is to add a |
<<X23,style>> to the existing Paragraph and ListingBlock definitions |
(all filters shipped with AsciiDoc use this technique). The filter is |
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. |
|
[[X56]] |
Example Filter |
~~~~~~~~~~~~~~ |
AsciiDoc comes with a toy filter for highlighting source code keywords |
and comments. See also the `./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 the {website}source-highlight-filter.html[source code highlighter |
filter]. |
|
Built-in filters |
~~~~~~~~~~~~~~~~ |
The AsciiDoc distribution includes 'source', 'music', 'latex' and |
'graphviz' filters, details are on the |
{website}index.html#_filters[AsciiDoc website]. |
|
[cols="1e,5",frame="topbot",options="header"] |
.Built-in filters list |
|==================================================================== |
|Filter name |Description |
|
|music |
|A {website}music-filter.html[music filter] is included in the |
distribution `./filters/` directory. It translates music in |
http://lilypond.org/[LilyPond] or http://abcnotation.org.uk/[ABC] |
notation to standard classical notation. |
|
|source |
|A {website}source-highlight-filter.html[source code highlight filter] |
is included in the distribution `./filters/` directory. |
|
|latex |
|The {website}latex-filter.html[AsciiDoc LaTeX filter] translates |
LaTeX source to a PNG image that is automatically inserted into the |
AsciiDoc output documents. |
|
|graphviz |
|Gouichi Iisaka has written a http://www.graphviz.org/[Graphviz] |
filter for AsciiDoc. Graphviz generates diagrams from a textual |
specification. Gouichi Iisaka's Graphviz filter is included in the |
AsciiDoc distribution. Here are some |
{website}asciidoc-graphviz-sample.html[AsciiDoc Graphviz examples]. |
|
|==================================================================== |
|
[[X58]] |
Filter plugins |
~~~~~~~~~~~~~~ |
Filter <<X101,plugins>> are 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 filer <<X101,plugins>>. |
|
- Filter plugins <<X27,take precedence>> 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. |
|
|
[[X101]] |
Plugins |
------- |
The AsciiDoc plugin architecture is an extension mechanism that allows |
additional <<X100,backends>>, <<X58,filters>> and <<X99,themes>> 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' and |
'build' 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 |
{website}plugins.html[AsciiDoc website]. |
|
|
[[X36]] |
Help Commands |
------------- |
The asciidoc(1) command has a `--help` option which prints help topics |
to stdout. The default topic 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. |
|
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). The <<X27,help file location>> 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 other |
<<X7,configuration files>>. The `help.conf` files are stored in the |
same locations and loaded in the same order as other configuration |
files. |
|
When the `--help` command-line option is specified AsciiDoc loads the |
appropriate help files 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. |
|
|
Tips and Tricks |
--------------- |
|
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. <<X20,Tips for 'vim' users>> |
follow. |
|
[[X20]] |
Vim Commands for Formatting AsciiDoc |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
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 the <<X61, Example `~/.vimrc` file>>). |
- 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. |
===================================================================== |
|
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 the <<X61, Example `~/.vimrc` file>>). |
|
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}`. |
|
Indent Paragraphs |
^^^^^^^^^^^^^^^^^ |
Indent whole paragraphs by indenting the fist line with the desired |
indent and then executing the `gq}` command. |
|
[[X61]] |
Example `~/.vimrc` File |
^^^^^^^^^^^^^^^^^^^^^^^ |
--------------------------------------------------------------------- |
" Use bold bright fonts. |
set background=dark |
|
" Show tabs and trailing characters. |
set listchars=tab:»·,trail:· |
set list |
|
" Don't highlight searched text. |
highlight clear Search |
|
" Don't move to matched text while search pattern is being entered. |
set noincsearch |
|
" Reformat paragraphs and list. |
nnoremap R gq} |
|
" Delete trailing white space and Dos-returns and to expand tabs to spaces. |
nnoremap S :set et<CR>:retab!<CR>:%s/[\r \t]\+$//<CR> |
|
autocmd BufRead,BufNewFile *.txt,README,TODO,CHANGELOG,NOTES |
\ 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:> |
--------------------------------------------------------------------- |
|
Troubleshooting |
~~~~~~~~~~~~~~~ |
AsciiDoc diagnostic features are detailed in the <<X82,Diagnostics |
appendix>>. |
|
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 |
AsciiDoc <<X54,encoding attribute>> for the correct character set |
(typically ISO-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)` (integrated into `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_. |
|
Ambiguous underlines:: |
A DelimitedBlock 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 & Ben Inc.' mydoc.txt |
|
Attribute lists:: |
If any named attribute entries are present then all string |
attribute values must be quoted. For example: |
|
["Desktop screenshot",width=32] |
|
[[X90]] |
Combining separate documents |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
You have a number of stand-alone AsciiDoc documents that you want to |
process as a single document. Simply processing them with a series of |
`include` macros won't work because the documents contain (level 0) |
document titles. The solution is to create a top level wrapper |
document and use the `leveloffset` attribute to push them all down one |
level. For example: |
|
[listing] |
..................................................................... |
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 now be 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. |
- You won'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. |
|
Processing document sections separately |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
You have divided your AsciiDoc document into separate files (one per |
top level section) which are combined and 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 also want to process the section files as separate documents. |
This is easy because asciidoc(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. |
|
Processing document snippets |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Use the `-s` (`--no-header-footer`) command-line option to suppress |
header and footer 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> |
|
Badges in HTML page footers |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
See the `[footer]` section in the AsciiDoc distribution `xhtml11.conf` |
configuration file. |
|
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's http://tidy.sourceforge.net/[HTML Tidy] program |
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 |
|
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 |
DTD variations. The included sections override corresponding entries |
from preceding sections. |
|
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 a single file. AsciiDoc has options to create |
stand-alone documents containing embedded images, stylesheets and |
scripts. The following AsciiDoc command creates a single file |
containing <<X66,embedded images>>, 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: {website}article-standalone.html[] |
|
Shipping stand-alone AsciiDoc source |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Reproducing presentation 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`) option excludes the use of implicit |
configuration files, ensuring that only entries from the |
`mydoc-html.conf` configuration are used. |
|
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. |
|
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[] |
--------------------------------------------------------------------- |
|
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 online http://validator.w3.org/#validate_by_uri+with_options[W3C |
Markup Validation Service] is the defacto standard when it comes to |
validating HTML (it validates all HTML standards including HTML5). |
|
|
:numbered!: |
|
[glossary] |
Glossary |
-------- |
[glossary] |
[[X8]] Block element:: |
An AsciiDoc block element is a document entity composed of one or |
more whole lines of text. |
|
[[X34]] 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. Formal elements |
are normally listed in 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. |
|
|
[appendix] |
Migration Notes |
--------------- |
[[X53]] |
Version 7 to version 8 |
~~~~~~~~~~~~~~~~~~~~~~ |
- A new set of quotes has been introduced which may match inline text |
in existing documents -- if they do you'll need to escape the |
matched text with backslashes. |
- The index entry 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` respectively. The |
default behavior has also changed -- 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 disable unconstrained quotes, the new alternative |
constrained quotes syntax and the new index entry syntax then you can |
define the attribute `asciidoc7compatible` (for example by using the |
`-a asciidoc7compatible` command-line option). |
|
[[X38]] |
[appendix] |
Packager Notes |
-------------- |
Read the `README` and `INSTALL` files (in the distribution root |
directory) for install prerequisites and procedures. The distribution |
`Makefile.in` (used by `configure` to generate the `Makefile`) is the |
canonical installation procedure. |
|
|
[[X39]] |
[appendix] |
AsciiDoc Safe Mode |
------------------- |
AsciiDoc 'safe mode' skips potentially dangerous scripted sections in |
AsciiDoc source files by inhibiting the execution of arbitrary code or |
the inclusion of arbitrary files. |
|
The safe mode is disabled by default, it can be enabled with the |
asciidoc(1) `--safe` command-line option. |
|
.Safe 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. |
===================================================================== |
|
|
[appendix] |
Using AsciiDoc with non-English Languages |
----------------------------------------- |
AsciiDoc can process UTF-8 character 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 outputting HTML directly from asciidoc(1) you'll |
need to set the various `*_caption` attributes to match 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 also |
<<X27,Configuration File Names and Locations>>. |
|
|
[appendix] |
Vim Syntax Highlighter |
---------------------- |
Syntax highlighting is incredibly useful, in addition to making |
reading AsciiDoc documents much easier syntax highlighting also helps |
you catch AsciiDoc syntax errors as you write your documents. |
|
The AsciiDoc `./vim/` distribution directory contains Vim syntax |
highlighter and filetype detection scripts for AsciiDoc. Syntax |
highlighting makes it much easier to spot AsciiDoc syntax errors. |
|
If Vim is installed on your system the AsciiDoc installer |
(`install.sh`) will automatically install the vim scripts in the Vim |
global configuration directory (`/etc/vim`). |
|
You can also turn on syntax highlighting by adding the following line |
to the end of you AsciiDoc source files: |
|
// vim: set syntax=asciidoc: |
|
TIP: Bold fonts are often easier to read, use the Vim `:set |
background=dark` command to set bold bright fonts. |
|
NOTE: There are a number of alternative syntax highlighters for |
various editors listed on the {website}[AsciiDoc website]. |
|
Limitations |
~~~~~~~~~~~ |
The current implementation does a reasonable job but on occasions gets |
things wrong: |
|
- Nested quoted text formatting is highlighted according to the outer |
format. |
- If a closing Example Block delimiter is sometimes mistaken for a |
title underline. A workaround is to insert a blank line before the |
closing delimiter. |
- Lines within a paragraph starting with equals characters may be |
highlighted as single-line titles. |
- Lines within a paragraph beginning with a period may be highlighted |
as block titles. |
|
|
[[X74]] |
[appendix] |
Attribute Options |
----------------- |
Here is the list of predefined <<X75,attribute list options>>: |
|
|
[cols="2e,2,2,5",frame="topbot",options="header"] |
|==================================================================== |
|Option|Backends|AsciiDoc Elements|Description |
|
|autowidth |xhtml11, html5, html4 |table| |
The column widths are determined by the browser, not the AsciiDoc |
'cols' attribute. If there is no 'width' attribute the table width is |
also left up to the browser. |
|
|unbreakable |xhtml11, html5 |block elements| |
'unbreakable' attempts to keep the block element together on a single |
printed page c.f. the 'breakable' and 'unbreakable' docbook (XSL/FO) |
options below. |
|
|breakable, unbreakable |docbook (XSL/FO) |table, example, block image| |
The 'breakable' options allows block elements to break across page |
boundaries; 'unbreakable' attempts to keep the block element together |
on a single page. If neither option is specified the default XSL |
stylesheet behavior prevails. |
|
|compact |docbook, xhtml11, html5 |bulleted list, numbered list| |
Minimizes vertical space in the list |
|
|footer |docbook, xhtml11, html5, html4 |table| |
The last row of the table is rendered as a footer. |
|
|header |docbook, xhtml11, html5, html4 |table| |
The first row of the table is rendered as a header. |
|
|pgwide |docbook (XSL/FO) |table, block image, horizontal labeled list| |
Specifies that the element should be rendered across the full text |
width of the page irrespective of the current indentation. |
|
|strong |xhtml11, html5, html4 |labeled lists| |
Emboldens label text. |
|==================================================================== |
|
|
[[X82]] |
[appendix] |
Diagnostics |
----------- |
The `asciidoc(1)` `--verbose` command-line option prints additional |
information to stderr: files processed, filters processed, warnings, |
system attribute evaluation. |
|
A special attribute named 'trace' enables the output of |
element-by-element diagnostic messages detailing output markup |
generation to stderr. The 'trace' attribute can be set on the |
command-line or from within the document using <<X18,Attribute |
Entries>> (the latter allows tracing to be confined to specific |
portions of the document). |
|
- Trace messages print the source file name and line number and the |
trace name followed by related markup. |
- 'trace names' are normally the names of AsciiDoc elements (see the |
list below). |
- The trace message is only printed if the 'trace' attribute value |
matches the start of a 'trace name'. The 'trace' attribute value can |
be any Python regular expression. If a trace value is not specified |
all trace messages will be printed (this can result in large amounts |
of output if applied to the whole document). |
|
- In the case of inline substitutions: |
* The text before and after the substitution is printed; the before |
text is preceded by a line containing `<<<` and the after text by |
a line containing `>>>`. |
* The 'subs' trace value is an alias for all inline substitutions. |
|
.Trace names |
..................................................................... |
<blockname> block close |
<blockname> block open |
<subs> |
dropped line (a line containing an undefined attribute reference). |
floating title |
footer |
header |
list close |
list entry close |
list entry open |
list item close |
list item open |
list label close |
list label open |
list open |
macro block (a block macro) |
name (man page NAME section) |
paragraph |
preamble close |
preamble open |
push blockname |
pop blockname |
section close |
section open: level <level> |
subs (all inline substitutions) |
table |
..................................................................... |
|
Where: |
|
- `<level>` is section level number '0...4'. |
- `<blockname>` is a delimited block name: 'comment', 'sidebar', |
'open', 'pass', 'listing', 'literal', 'quote', 'example'. |
- `<subs>` is an inline substitution type: |
'specialcharacters','quotes','specialwords', 'replacements', |
'attributes','macros','callouts', 'replacements2', 'replacements3'. |
|
Command-line examples: |
|
. Trace the entire document. |
|
$ asciidoc -a trace mydoc.txt |
|
. Trace messages whose names start with `quotes` or `macros`: |
|
$ asciidoc -a 'trace=quotes|macros' mydoc.txt |
|
. Print the first line of each trace message: |
|
$ asciidoc -a trace mydoc.txt 2>&1 | grep ^TRACE: |
|
Attribute Entry examples: |
|
. Begin printing all trace messages: |
|
:trace: |
|
. Print only matched trace messages: |
|
:trace: quotes|macros |
|
. Turn trace messages off: |
|
:trace!: |
|
|
[[X88]] |
[appendix] |
Backend Attributes |
------------------ |
This table contains a list of optional attributes that influence the |
generated outputs. |
|
[cols="1e,1,5a",frame="topbot",options="header"] |
|==================================================================== |
|Name |Backends |Description |
|
|badges |xhtml11, html5 | |
Link badges ('XHTML 1.1' and 'CSS') in document footers. By default |
badges are omitted ('badges' is undefined). |
|
NOTE: The path names of images, icons and scripts are relative path |
names to the output document not the source document. |
|
|data-uri |xhtml11, html5 | |
Embed images using the <<X66,data: uri scheme>>. |
|
|css-signature |html5, xhtml11 | |
Set a 'CSS signature' for the document (sets the 'id' attribute of the |
HTML 'body' element). CSS signatures provide a mechanism that allows |
users to personalize the document appearance. The term 'CSS signature' |
was http://archivist.incutio.com/viewlist/css-discuss/13291[coined by |
Eric Meyer]. |
|
|
|disable-javascript |xhtml11, html5 | |
If the `disable-javascript` attribute is defined the `asciidoc.js` |
JavaScript is not embedded or linked to the output document. By |
default AsciiDoc automatically embeds or links the `asciidoc.js` |
JavaScript to the output document. The script dynamically generates |
<<X91,table of contents>> and <<X92,footnotes>>. |
|
|[[X97]] docinfo, docinfo1, docinfo2 |All backends | |
These three attributes control which <<X87,document information |
files>> will be included in the the header of the output file: |
|
docinfo:: Include `<filename>-docinfo.<ext>` |
docinfo1:: Include `docinfo.<ext>` |
docinfo2:: Include `docinfo.<ext>` and `<filename>-docinfo.<ext>` |
|
Where `<filename>` is the file name (sans extension) of the AsciiDoc |
input file and `<ext>` is `.html` for HTML outputs or `.xml` for |
DocBook outputs. If the input file is the standard input then the |
output file name is used. The following example will include the |
`mydoc-docinfo.xml` docinfo file in the DocBook `mydoc.xml` output |
file: |
|
$ asciidoc -a docinfo -b docbook mydoc.txt |
|
This next example will include `docinfo.html` and `mydoc-docinfo.html` |
docinfo files in the HTML output file: |
|
$ asciidoc -a docinfo2 -b html4 mydoc.txt |
|
|
|[[X54]]encoding |html4, html5, xhtml11, docbook | |
Set the input and output document character set encoding. For example |
the `--attribute encoding=ISO-8859-1` command-line option will set the |
character set encoding to `ISO-8859-1`. |
|
- The default encoding is UTF-8. |
- This attribute specifies the character set in the output document. |
- The encoding name must correspond to a Python codec name or alias. |
- The 'encoding' attribute can be set using an AttributeEntry inside |
the document header. For example: |
|
:encoding: ISO-8859-1 |
|
|[[X45]]icons |xhtml11, html5 | |
Link admonition paragraph and admonition block icon images and badge |
images. By default 'icons' is undefined and text is used in place of |
icon images. |
|
|[[X44]]iconsdir |html4, html5, xhtml11, docbook | |
The name of the directory containing linked admonition icons, |
navigation icons and the `callouts` sub-directory (the `callouts` |
sub-directory contains <<X105,callout>> number images). 'iconsdir' |
defaults to `./images/icons`. |
|
|imagesdir |html4, html5, xhtml11, docbook | |
If this attribute is defined it is prepended to the target image file |
name paths in inline and block image macros. |
|
|keywords, description, title |html4, html5, xhtml11 | |
The 'keywords' and 'description' attributes set the correspondingly |
named HTML meta tag contents; the 'title' attribute sets the HTML |
title tag contents. Their principle use is for SEO (Search Engine |
Optimisation). All three are optional, but if they are used they must |
appear in the document header (or on the command-line). If 'title' is |
not specified the AsciiDoc document title is used. |
|
|linkcss |html5, xhtml11 | |
Link CSS stylesheets and JavaScripts. By default 'linkcss' is |
undefined in which case stylesheets and scripts are automatically |
embedded in the output document. |
|
|[[X103]]max-width |html5, xhtml11 | |
Set the document maximum display width (sets the 'body' element CSS |
'max-width' property). |
|
|numbered |html4, html5, xhtml11, docbook (XSL Stylesheets) | |
Adds section numbers to section titles. The 'docbook' backend ignores |
'numbered' attribute entries after the document header. |
|
|plaintext | All backends | |
If this global attribute is defined all inline substitutions are |
suppressed and block indents are retained. This option is useful when |
dealing with large amounts of imported plain text. |
|
|quirks |xhtml11 | |
Include the `xhtml11-quirks.conf` configuration file and |
`xhtml11-quirks.css` <<X35,stylesheet>> to work around IE6 browser |
incompatibilities. This feature is deprecated and its use is |
discouraged -- documents are still viewable in IE6 without it. |
|
|revremark |docbook | |
A short summary of changes in this document revision. Must be defined |
prior to the first document section. The document also needs to be |
dated to output this attribute. |
|
|scriptsdir |html5, xhtml11 | |
The name of the directory containing linked JavaScripts. |
See <<X35,HTML stylesheets and JavaScript locations>>. |
|
|sgml |docbook45 | |
The `--backend=docbook45` command-line option produces DocBook 4.5 |
XML. You can produce the older DocBook SGML format using the |
`--attribute sgml` command-line option. |
|
|stylesdir |html5, xhtml11 | |
The name of the directory containing linked or embedded |
<<X35,stylesheets>>. |
See <<X35,HTML stylesheets and JavaScript locations>>. |
|
|stylesheet |html5, xhtml11 | |
The file name of an optional additional CSS <<X35,stylesheet>>. |
|
|theme |html5, xhtml11 | |
Use alternative stylesheet (see <<X35,Stylesheets>>). |
|
|[[X91]]toc |html5, xhtml11, docbook (XSL Stylesheets) | |
Adds a table of contents to the start of an article or book document. |
The `toc` attribute can be specified using the `--attribute toc` |
command-line option or a `:toc:` attribute entry in the document |
header. The 'toc' attribute is defined by default when the 'docbook' |
backend is used. To disable table of contents generation undefine the |
'toc' attribute by putting a `:toc!:` attribute entry in the document |
header or from the command-line with an `--attribute toc!` option. |
|
*xhtml11 and html5 backends* |
|
- JavaScript needs to be enabled in your browser. |
- The following example generates a numbered table of contents using a |
JavaScript embedded in the `mydoc.html` output document: |
|
$ asciidoc -a toc -a numbered mydoc.txt |
|
|toc2 |html5, xhtml11 | |
Adds a scrollable table of contents in the left hand margin of an |
article or book document. Use the 'max-width' attribute to change the |
content width. In all other respects behaves the same as the 'toc' |
attribute. |
|
|toc-placement |html5, xhtml11 | |
When set to 'auto' (the default value) asciidoc(1) will place the |
table of contents in the document header. When 'toc-placement' is set |
to 'manual' the TOC can be positioned anywhere in the document by |
placing the `toc::[]` block macro at the point you want the TOC to |
appear. |
|
NOTE: If you use 'toc-placement' then you also have to define the |
<<X91,toc>> attribute. |
|
|toc-title |html5, xhtml11 | |
Sets the table of contents title (defaults to 'Table of Contents'). |
|
|toclevels |html5, xhtml11 | |
Sets the number of title levels (1..4) reported in the table of |
contents (see the 'toc' attribute above). Defaults to 2 and must be |
used with the 'toc' attribute. Example usage: |
|
$ asciidoc -a toc -a toclevels=3 doc/asciidoc.txt |
|
|==================================================================== |
|
|
[appendix] |
License |
------- |
AsciiDoc is free software; you can redistribute it and/or modify it |
under the terms of the 'GNU General Public License version 2' (GPLv2) |
as published by the Free Software Foundation. |
|
AsciiDoc is distributed in the hope that it will be useful, but |
WITHOUT ANY WARRANTY; without even the implied warranty of |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
General Public License version 2 for more details. |
|
AsciiDoc Highlighter sponsored by O'Reilly Media |
|
Copyright (C) 2002-2011 Stuart Rackham. |