diff options
Diffstat (limited to '')
| -rw-r--r-- | source-builder/sb/asciidoc/examples/website/userguide.txt | 6038 |
1 files changed, 0 insertions, 6038 deletions
diff --git a/source-builder/sb/asciidoc/examples/website/userguide.txt b/source-builder/sb/asciidoc/examples/website/userguide.txt deleted file mode 100644 index b7a98f0..0000000 --- a/source-builder/sb/asciidoc/examples/website/userguide.txt +++ /dev/null @@ -1,6038 +0,0 @@ -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. - -Copyright (C) 2002-2011 Stuart Rackham. |