asciidoc/doc/asciidoc.txt in mizuho-0.9.6 vs asciidoc/doc/asciidoc.txt in mizuho-0.9.8

- old
+ new

@@ -1,108 +1,100 @@ 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 short documents, -articles, books and UNIX man pages. AsciiDoc files can be translated -to HTML and DocBook markups using the asciidoc(1) command. 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. +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. - -Introduction ------------- +.This document ********************************************************************** This is an overly large document, it probably needs to be refactored -into a Tutorial, FAQ, Quick Reference and Formal Reference. +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` +Started>> section and take a look at the example AsciiDoc (`*.txt`) source files in the distribution `doc` directory. ********************************************************************** -Plain text is the most universal electronic document format, no matter -what computing environment you use, you can always read and write -plain text documentation. But for many applications plain text is not -a viable presentation format. HTML, PDF and roff (roff is used for -man pages) are the most widely used UNIX presentation formats. -DocBook is a popular UNIX documentation markup format which can be -translated to HTML, PDF and other presentation formats. +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, DVI, LaTeX, -PostScript, man page, HTML and text formats. +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 files are unencumbered by markup and are easily viewed, -proofed and edited. +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. -You write an AsciiDoc document the same way you would write a normal -text document, there are no markup tags or arcane notations. Built-in -AsciiDoc formatting rules have been kept to a minimum and are -reasonably obvious. - 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 create your own configuration files to translate AsciiDoc +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 or man pages to HTML or DocBook backend +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 marked up text 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. - +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,Appendix B: Packager -Notes>>. +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 http://www.methods.co.nz/asciidoc/. Press the 'Page Source' - sidebar menu item to view corresponding AsciiDoc source. -- Read the `.txt` source files in the distribution `./doc` directory - in conjunction with the corresponding HTML and DocBook XML files. + 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. +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 @@ -111,37 +103,48 @@ 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; in addition there is the -option to add level 0 book part sections. +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 markup supports standard DocBook frontmatter and backmatter -<<X16,special sections>> (dedication, preface, bibliography, glossary, -index, colophon) plus footnotes and index entries. +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 UNIX manual pages. AsciiDoc manpage documents -observe special header title and section naming conventions -- see the -<<X1,Manpage Documents>> section for details. +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]] @@ -149,184 +152,150 @@ ----------------- 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. +configuration files. Backend specific attributes are listed in the +<<X88,Backend Attributes>> section. -AsciiDoc ships with the following predefined backend output formats: +docbook45:: + Outputs DocBook XML 4.5 markup. -docbook -~~~~~~~ -AsciiDoc generates the following DocBook document types: article, book -and refentry (corresponding to the AsciiDoc 'article', 'book' and -'manpage' document types). +html4:: + This backend generates plain HTML 4.01 Transitional markup. -DocBook documents are not designed to be viewed directly. Most Linux -distributions come with conversion tools (collectively called a -toolchain) for <<X12,converting DocBook files>> to presentation -formats such as Postscript, HTML, PDF, DVI, PostScript, LaTeX, roff -(the native man page format), HTMLHelp, JavaHelp and text. +xhtml11:: + This backend generates XHTML 1.1 markup styled with CSS2. Output + files have an `.html` extension. -- The `--backend=docbook` command-line option produces DocBook XML. - You can produce the older DocBook SGML format using the - `--attribute sgml` command-line option. -- Use the optional <<X54,`encoding`>> attribute to set the character - set encoding. -- Use the optional `imagesdir` attribute to prepend to the target file - name paths in image inline and block macros. Defaults to a blank - string. -- The AsciiDoc 'Preamble' element generates a DocBook book 'preface' - element although it's more usual to use an explicit 'Preface' - special section (see the `./doc/book.txt` example book). +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. -[[X33]] -xhtml11 -~~~~~~~ -The default asciidoc(1) backend is `xhtml11` which generates XHTML 1.1 -markup styled with CSS2. Default output file have a `.html` extension. -'xhtml11' document generation is influenced by the following -optional attributes (the default behavior is to generate XHTML with no -section numbers, embedded CSS and no linked admonition icon images): +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]. -numbered:: - Adds section numbers to section titles. +wordpress:: + A minor variant of the 'html4' backend to support + http://srackham.wordpress.com/blogpost1/[blogpost]. -toc:: - Adds a table of contents to the start of the document. +latex:: + Experimental LaTeX backend. - - JavaScript needs to be enabled in your browser for this to work. - - By default AsciiDoc automatically embeds the required `toc.js` - JavaScript in the output document -- use the 'linkcss' attribute - to link the script. - - The following example generates a numbered table of contents by - embedding the `toc.js` script in the `mydoc.html` output document - (to link the script to the output document use the 'linkcss' and - 'scriptsdir' attributes): +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'). - $ asciidoc -a toc -a numbered mydoc.txt +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: -toclevels:: - 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: + backend-alias-html=xhtml11 + backend-alias-docbook=docbook45 - $ asciidoc -a toc -a toclevels=3 doc/asciidoc.txt +DocBook +~~~~~~~ +AsciiDoc generates 'article', 'book' and 'refentry' +http://www.docbook.org/[DocBook] documents (corresponding to the +AsciiDoc 'article', 'book' and 'manpage' document types). -toc_title:: - Sets the table of contents title (defaults to 'Table of Contents'). +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). -linkcss:: - Link CSS stylesheets and JavaScripts (see the 'stylesdir' and - 'scriptsdir' attributes below). By default 'linkcss' is undefined in - which case stylesheets and scripts are automatically embedded in the - output document. +[[X35]] +HTML Stylesheets +~~~~~~~~~~~~~~~~ +The 'xhtml11' and 'html5' backends include or link CSS files into +their outputs. The CSS2 stylesheets are located in the distribution +`./stylesheets/` directory. -scriptsdir:: - The name of the directory containing linked JavaScripts. Defaults to - `.` (the same directory as the linking document). +`./stylesheets/asciidoc.css`:: + The main stylesheet. -stylesdir:: - The name of the directory containing linked stylesheets. Defaults to - `.` (the same directory as the linking document). +`./stylesheets/asciidoc-manpage.css`:: + Tweaks for manpage document type generation. -stylesheet:: - The file name of an optional additional CSS stylesheet. If you are - embedding the stylesheet specify the actual file name; if you are - linking CSS specify the file name relative to the directory - specified by the 'stylesdir' attribute. +Use the 'theme' attribute to select an alternative set of stylesheets. +For example, the command-line option `-a theme=foo` will use +stylesheets `foo.css`, `foo-manpage.css` instead of the default +stylesheets. -[[X45]] -icons:: - 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. +Use the 'stylesheet' attribute to include an additional stylesheet in +XHTML documents. For example, the command-line option `-a +stylesheet=newsletter.css` will use stylesheets `newsletter.css`. -[[X44]] -iconsdir:: - The name of the directory containing linked admonition and - navigation icons. Defaults to `./images/icons`. +[[X99]] +HTML Stylesheets and JavaScript file locations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +'xhtml11' and 'html5' backends use CSS stylesheets and JavaScripts. +CSS and JavaScript files are either embedded in the output document +(when it is generated by AsciiDoc) or linked to the output document +(when it is viewed). -imagesdir:: - This attribute is prepended to the target image file name paths in - image inline and block macros. Defaults to a blank string. +- If the AsciiDoc 'linkcss' attribute is defined CSS and JavaScript + files are linked 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 located when + AsciiDoc generates the output document, linked files are located + when the user views the output document. -theme:: - Use alternative stylesheets (see <<X35,Stylesheets>>). +.Stylesheet file locations +[cols="3*",frame="topbot",options="header"] +|==================================================================== +|'stylesdir' attribute +|Linked location ('linkcss' attribute defined) +|Embedded location ('linkcss' attribute undefined) -badges:: - Link badges ('XHTML 1.1', 'CSS' and 'Get Firefox!') in document - footers. By default badges are omitted ('badges' is undefined). +|Undefined (default). +|Same directory as the output document. +|`stylesheets` subdirectory in the AsciiDoc configuration directory +(the directory containing the backend conf file). -NOTE: The path names of images, icons and scripts are relative to the -output document not the source document. +|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). -[[X54]] -encoding:: - 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 but it must come at the start of the document - before the document title. For example: +.JavaScript file locations +[cols="3*",frame="topbot",options="header"] +|==================================================================== +|'scriptsdir' attribute +|Linked location ('linkcss' attribute defined) +|Embedded location ('linkcss' attribute undefined) - :encoding: ISO-8859-1 +|Undefined (default). +|Same directory as the output document. +|`javascripts` subdirectory in the AsciiDoc configuration directory +(the directory containing the backend conf file). -quirks:: - Use the `xhtml11-quirks.css` stylesheet to work around IE6 browser - incompatibilities (this is the default behavior). +|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). -data-uri:: - Embed images referenced by 'image' macros using the <<X66,data: uri - scheme>>. +|==================================================================== -[[X35]] -Stylesheets -^^^^^^^^^^^ -AsciiDoc XHTML output is styled using CSS2 stylesheets from the -distribution `./stylesheets/` directory. -[IMPORTANT] -===================================================================== -All browsers have CSS quirks, but Microsoft's IE6 has so many -omissions and errors that the `xhtml11-quirks.css` stylesheet and -`xhtml11-quirks.conf` configuration files are included during XHTML -backend processing to to implement workarounds for IE6. If you don't -use IE6 then the quirks stylesheet and configuration files can be -omitted using the `--attribute quirks!` command-line option. -===================================================================== - -Default 'xhtml11' stylesheets: - -`./stylesheets/xhtml11.css`:: - The main stylesheet. - -`./stylesheets/xhtml11-manpage.css`:: - Tweaks for manpage document type generation. - -`./stylesheets/xhtml11-quirks.css`:: - Stylesheet modifications to work around IE6 browser - incompatibilities. - -Use the 'theme' attribute to select an alternative set of stylesheets. -For example, the command-line option `-a theme=foo` will use -stylesheets `foo.css`, `foo-manpage.css` and `foo-quirks.css` instead -of the default stylesheets. - -Use the 'stylesheet' attribute to include an additional stylesheet in -XHTML documents. For example, the command-line option `-a -stylesheet=newsletter.css` will use stylesheets `newsletter.css`. - -html4 -~~~~~ -This backend generates plain (unstyled) HTML 4.01 Transitional markup. - - 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. @@ -338,18 +307,18 @@ 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 +The AsciiDoc block structure can be informally summarized as follows footnote:[This is a rough structural guide, not a rigorous syntax -definition] as follows: +definition]: Document ::= (Header?,Preamble?,Section*) - Header ::= (Title,(AuthorLine,RevisionLine?)?) - AuthorLine ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?) - RevisionLine ::= (Revision?,Date) + 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) @@ -373,85 +342,224 @@ - 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 is optional but must start on the first line of the -document and must begin with a document <<X17,title>>. Optional Author -and Revision lines immediately follow the title. The header can be -preceded by a CommentBlock or comment lines. +The Header contains document meta-data, typically title plus optional +authorship and revision information: -The author line contains the author's name optionally followed by the -author's email address. The author's name consists of a first name -followed by optional middle and last names separated by white space. -Multi-word first, middle and last names can be entered in the header -author line using the underscore as a word separator. The email -address comes last and must be enclosed in angle <> brackets. Author -names cannot contain angle <> bracket characters. +- 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). -The optional document header revision line should immediately follow -the author line. The revision line can be one of two formats: +Here's an example AsciiDoc document header: -. An alphanumeric document revision number followed by a date: - * The revision number and date must be separated by a comma. - * The revision number is optional but must contain at least one - numeric character. + 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. -. An RCS/CSV/SVN $Id$ marker. + * 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. -The document heading is separated from the remainder of the document -by one or more blank lines. +Examples: -Here's an example AsciiDoc document header: - - Writing Documentation using AsciiDoc - ==================================== - Stuart Rackham <srackham@gmail.com> 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. +-- -You can override or set header parameters by passing 'revision', -'data', 'email', 'author', 'authorinitials', 'firstname' and -'lastname' attributes using the asciidoc(1) `-a` (`--attribute`) -command-line option. For example: +. 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. - $ asciidoc -a date=2004/07/27 article.txt +Example: -Attributes can also be added to the header for substitution in the -header template with <<X18,Attribute Entry>> elements. + $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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +'docinfo' files are a mechanism for optionally including additional +meta-data in the header of the output document. + +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 file 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 ~~~~~~~~ -AsciiDoc supports five section levels 0 to 4 (although only book -documents are allowed to contain level 0 sections). Section levels are -delineated by the section <<X17,titles>>. +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: -Sections are translated using configuration file markup templates. To -determine which configuration file template to use AsciiDoc first -searches for special section titles in the <<X16,`[specialsections]`>> -configuration entries, if not found it uses the `[sect<level>]` -template. +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>>. -The `-n` (`--section-numbers`) command-line option auto-numbers HTML -outputs (DocBook line numbering is handled automatically by the -DocBook toolchain commands). +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). -Section IDs are auto-generated from section titles if the `sectids` -attribute is defined (the default behavior). The primary purpose of -this feature is to ensure persistence of table of contents links: -missing section IDs are generated dynamically by the JavaScript TOC -generator *after* the page is loaded. This means, for example, that if -you go to a bookmarked dynamically generated TOC address the page will -load but the browser will ignore the (as yet ungenerated) section ID. +[[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. @@ -462,78 +570,94 @@ auto-generated section ID exists. For 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 Sections -^^^^^^^^^^^^^^^^ -In addition to normal sections, documents can contain optional -frontmatter and backmatter sections -- for example: preface, -bibliography, table of contents, index. +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: -The AsciiDoc configuration file `[specialsections]` section specifies -special section titles and the corresponding backend markup templates. + <title>=<template> -`[specialsections]` entries are formatted like: +`<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. - <pattern>=<name> +.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: -`<pattern>` is a Python regular expression and `<name>` is the name of -a configuration file markup template section. If the `<pattern>` -matches an AsciiDoc document section title then the backend output is -marked up using the `<name>` 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. +- 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). -AsciiDoc comes preconfigured with the following special section -titles: +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. - Preface (book documents only) - Abstract (article documents only) - Dedication (book documents only) - Glossary - Bibliography|References - Colophon (book documents only) - Index - Appendix [A-Z][:.] <title> +Special section titles have been deprecated but are retained for +backward compatibility. +********************************************************************* + Inline Elements ~~~~~~~~~~~~~~~ -<<X34,Inline document elements>> are used to markup character -formatting and various types of text substitution. Inline elements and -inline element syntax is defined in the asciidoc(1) configuration -files. +<<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 "&"). See - `[specialcharacters]` configuration file sections. + the backend markup (typically `<`, `>`, and `&` characters). + See `[specialcharacters]` configuration file sections. Quotes:: - Characters that markup words and phrases; usually for - character formatting. See `[quotes]` configuration file - sections. + 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 + Each replacement defines a word or word phrase pattern to search for along with corresponding replacement text. See `[replacements]` configuration file sections. -Attributes:: - Document attribute names enclosed in braces (attribute - references) are replaced by the corresponding attribute value. +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. @@ -591,14 +715,17 @@ *Strong text*:: Word phrases \*enclosed in asterisk characters* are rendered in a strong font (usually bold). -+Monospaced text+:: - Word phrases \`enclosed in backtick characters` (grave - accents) or \+plus characters+ are rendered in a monospaced - font. +[[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. @@ -609,57 +736,80 @@ marks. #Unquoted text#:: Placing \#hashes around text# does nothing, it is a mechanism to allow inline attributes to be applied to otherwise - unformatted text (see example below). + unformatted text. -The alternative underline and plus characters, while marginally less -readable, are arguably a better choice than the backtick and -apostrophe characters as they are not normally used for, and so not -confused with, punctuation. +New quote types can be defined by editing asciidoc(1) configuration +files. See the <<X7,Configuration Files>> section for details. -Quoted text can be prefixed with an <<X21,attribute list>>. Currently -the only use made of this feature is to allow the font color, -background color and size to be specified (XHTML/HTML only, not -DocBook) using the first three positional attribute arguments. The -first argument is the text color; the second the background color; the -third is the font size. Colors are valid CSS colors and the font size -is a number which treated as em units. Here are some examples: - ---------------------------------------------------------------------- -[red]#Red text#. -[,yellow]*bold text on a yellow background*. -[blue,#b0e0e6]+Monospaced blue text on a light blue background+ -[,,2]#Double sized text#. ---------------------------------------------------------------------- - -New quotes 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. -- A configuration file `[quotes]` entry can be subsequently undefined - by setting it to a blank value. +[[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 + [bold 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: Text attributes are not applicable to PDF or HTML 4 outputs. + [[X52]] Constrained and Unconstrained Quotes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ There are actually two types of quotes: Constrained quotes ++++++++++++++++++ -Quote text that must be bounded by white space, for example a phrase -or a word. These are the most common type of quote and are the ones -discussed previously. +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 @@ -673,20 +823,10 @@ The following example emboldens the letter F: **F**ile Open... -[TIP] -===================================================================== -The `__`, `**`, `++` and `##` unconstrained quotes have to be -double-escaped (because of their similarity to the single character -constrained quotes) -- here's how to escape the previous example: - - \*\*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: @@ -698,39 +838,37 @@ e^&#960;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>> so they can be escaped with a leading backslash and prefixed +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)>> if you use FOP. +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)>> if you use FOP. Hard page breaks are sometimes handy -but as a general rule you should let your page processor generate page -breaks for you. +<<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)>> if -you use FOP. +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 @@ -789,11 +927,11 @@ 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 three characters): +take up to two characters): The default title underlines for each of the document levels are: Level 0 (top level): ====================== @@ -813,33 +951,50 @@ [[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 -(levels 2 and 3 illustrate the optional trailing equals characters -syntax): +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 +[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]] -BlockTitles ------------ -A BlockTitle element is a single line beginning with a period followed -by a title. The title is applied to the next Paragraph, -DelimitedBlock, List, Table or BlockMacro. For example: +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. @@ -855,109 +1010,216 @@ [[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 use by referring links. For -example: +identifier to the ensuing block element. For example: [[chapter-titles]] Chapter titles can be ... -The preceding example identifies the following paragraph so it can be -linked from other location, for example with -`\<<chapter-titles,chapter titles>>`. +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 is -really just an AttributeList with a special syntax which sets the -`\{id}` attribute for substitution in the subsequent block's markup -template. +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 a similar -function to the <<X30,anchor inline macro>>. +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 terminated by a blank line, the end of file, or the -start of a DelimitedBlock. +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, if you wish, explicitly +apply any paragraph style to any paragraph syntax. The common +paragraph styles are 'normal', 'literal', 'verse', 'quote', 'listing', +'TIP', 'NOTE', 'IMPORTANT', 'WARNING' and 'CAUTION'. -Paragraph markup is specified by configuration file `[paradef*]` -sections. AsciiDoc ships with the following predefined paragraph -types: +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. -Default Paragraph -~~~~~~~~~~~~~~~~~ -A Default paragraph (`[paradef-default]`) 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 processing expectation -of the default paragraph type 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 'verse' paragraph <<X23,style>> preserves line boundaries and is -useful for lyrics and poems. For example: +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: --------------------------------------------------------------------- -[verse] + 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: -[verse] +[literal] Consul *necessitatibus* per id, consetetur, eu pro everti postulant homero verear ea mea, qui. -Literal Paragraph -~~~~~~~~~~~~~~~~~ -A Literal paragraph (`[paradef-literal]`) consists of one or more -lines of text, where the first line is indented by one or more space -or tab characters. Literal paragraphs are rendered verbatim in a -monospaced font usually without any distinguishing background or -border. There is no text formatting or substitutions within Literal -paragraphs apart from Special Characters and Callouts. For example: +[[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: + --------------------------------------------------------------------- - Consul *necessitatibus* per id, - consetetur, eu pro everti postulant - homero verear ea mea, qui. +[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. --------------------------------------------------------------------- -Renders: +Which is rendered as: - Consul *necessitatibus* per id, - consetetur, eu pro everti postulant - homero verear ea mea, qui. +[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. -NOTE: Because <<X64,lists>> can be indented it's possible for your -Literal paragraph to be misinterpreted as a list -- in situations like -this use a <<X65,LiteralBlock>> in place of a 'LiteralParagraph'. +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' paragraph -definitions support the corresponding DocBook admonishment elements -- -just write a normal paragraph but place `NOTE:`, `TIP:`, `IMPORTANT:`, -`WARNING:` or `CAUTION:` as the first word of the paragraph. For -example: +'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. -or the alternative syntax: +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 is more than a single paragraph use an +TIP: If your admonition requires more than a single paragraph use an <<X22,admonition block>> instead. [[X47]] Admonition Icons and Captions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -965,12 +1227,12 @@ `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) `xhtml11` and `html4` backends generate -text captions instead of icon image links. To generate links to icon +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. @@ -981,13 +1243,13 @@ [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): +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>>. @@ -996,11 +1258,11 @@ 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. +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 @@ -1013,35 +1275,34 @@ ListingBlock: -------------------------- LiteralBlock: .......................... SidebarBlock: ************************** QuoteBlock: __________________________ ExampleBlock: ========================== - Filter blocks: ~~~~~~~~~~~~~~~~~~~~~~~~~~ + OpenBlock: -- -The <<X56,code>>, <<X57,source>> and <<X58,music>> filter blocks are -detailed in the <<X59,Filters>> section. - .Default DelimitedBlock substitutions -[cols="2,5*^",options="header"] -|================================================================== -| |Passthrough |Listing |Literal |Sidebar |Quote -|Callouts | No | Yes | Yes | No | No -|Attributes | Yes | No | No | Yes | Yes -|Inline Macros | Yes | No | No | Yes | Yes -|Quotes | No | No | No | Yes | Yes -|Replacements | No | No | No | Yes | Yes -|Special chars | No | Yes | Yes | Yes | Yes -|Special words | No | No | No | Yes | Yes -|================================================================== +[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 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 code and file listings. +'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] ...................................... @@ -1064,35 +1325,40 @@ 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 behave just like LiteralParagraphs except you don't have -to indent the contents. +'LiteralBlocks' are rendered just like <<X85,literal paragraphs>>. +Example: -LiteralBlocks can be used to resolve list ambiguity. If the following -list was just indented it would be processed as an ordered list (not -an indented paragraph): - --------------------------------------------------------------------- -.................... -1. Item 1 -2. Item 2 -.................... +................................... +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. +................................... --------------------------------------------------------------------- Renders: -.................... -1. Item 1 -2. Item 2 -.................... +................................... +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. +................................... -SidebarBlocks -~~~~~~~~~~~~~ +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. @@ -1113,25 +1379,17 @@ ************************************************ Any AsciiDoc SectionBody element (apart from SidebarBlocks) can be placed inside a sidebar. ************************************************ -Apply the 'abstract' style to generate an abstract, for example: - ---------------------------------------------------------------------- -[abstract] -************************************************ -In this paper we will attempt to... -************************************************ ---------------------------------------------------------------------- - [[X26]] Comment Blocks ~~~~~~~~~~~~~~ -The contents of CommentBlocks are not processed; they are useful for +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. Here's and example: +want displayed. CommentBlocks are never written to output files. +Example: --------------------------------------------------------------------- ////////////////////////////////////////// CommentBlock contents are not processed by asciidoc(1). @@ -1143,93 +1401,84 @@ NOTE: System macros are executed inside comment blocks. [[X76]] Passthrough Blocks ~~~~~~~~~~~~~~~~~~ -By default the block contents is subject to attribute and macro -substitution, no other markup is generated. PassthroughBlock content -will often be backend specific. Here's an example: +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> + <td>*Cell 1*</td> + <td>*Cell 2*</td> </tr></table> ++++++++++++++++++++++++++++++++++++++ --------------------------------------------------------------------- -Use and explicit 'subs' attribute to control substitution. The -following styles can be applied to passthrough blocks: +The following styles can be applied to passthrough blocks: pass:: - By default no substitutions are performed. + 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 first positional attribute). The +'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 content author and source. If no attributes are -specified the 'quote' style is used. +3) specify the quote's author and source. For example: -The 'quote' style treats the content like a SectionBody, for example: - --------------------------------------------------------------------- -[quote, Bertrand Russell, The World of Mathematics (1956)] +[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes] ____________________________________________________________________ -A good notation has subtlety and suggestiveness which at times makes -it almost seem like a live teacher. +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, Bertrand Russell, The World of Mathematics (1956)] +[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes] ____________________________________________________________________ -A good notation has subtlety and suggestiveness which at times makes -it almost seem like a live teacher. +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." ____________________________________________________________________ -The 'verse' style -retains the content's 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. -__________________________________________________ - [[X48]] Example Blocks ~~~~~~~~~~~~~~ -ExampleBlocks encapsulate the DocBook Example element and are used +'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 normally number examples and -generate a 'List of Examples' backmatter section. +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 you can -put any block elements apart from Titles, BlockTitles and Sidebars) -inside an example block. For example: +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 @@ -1244,11 +1493,11 @@ Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. ===================================================================== A title prefix that can be inserted with the `caption` attribute -(`xhtml11` and `html4` backends). For example: +(HTML backends). For example: --------------------------------------------------------------------- [caption="Example 1: "] .An example with a custom caption ===================================================================== @@ -1258,19 +1507,19 @@ --------------------------------------------------------------------- [[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 just a -<<X28,simple paragraph>>). Just precede the ExampleBlock with an -attribute list containing the admonition style name. For example: +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 block +.A NOTE admonition block ===================================================================== Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. . Fusce euismod commodo velit. @@ -1283,11 +1532,11 @@ --------------------------------------------------------------------- Renders: [NOTE] -.A NOTE block +.A NOTE admonition block ===================================================================== Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. . Fusce euismod commodo velit. @@ -1298,11 +1547,34 @@ nunc consequat lobortis. ===================================================================== See also <<X47,Admonition Icons and Captions>>. +[[X29]] +Open Blocks +~~~~~~~~~~~ +An 'OpenBlock' groups a set of block elements. 'OpenBlock' usage: +. <<X15,List item continuation>>. + +. 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. @@ -1311,118 +1583,129 @@ - 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. -- A nested list must use a different syntax from its parent so that - asciidoc(1) can distinguish the start of a nested list. -- By default lists of the same type can only be nested two deep; this - could be increased by defining new list definitions. -- In addition to nested lists a list item will include immediately - following Literal paragraphs. -- Use <<X15, List Item Continuation>> to append other block elements - to a list item. +- 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 not inside a list then it's value + 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. -- You need to use <<X15,list item continuation>> if a nested list is - accompanied by an <<X21,attribute list>>. -Bulleted and Numbered Lists -~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Bulleted list items start with a dash or an asterisk followed by a -space or tab character. Bulleted list syntaxes are: +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. ................... -There are two numbered list item syntaxes: +Numbered Lists +~~~~~~~~~~~~~~ +List item numbers are explicit or implicit. -. List items beginning with a single period followed by a space. The - period can be preceded by an optional decimal number. The default - numbering style is arabic (decimal). -. List items beginning with two periods followed by a space. An alpha - character or a roman number (upper or lower case) can optionally be - used in place of the first period: - * An attempt is made to set the number style based on number style - of the first list item. - * The default numbering style is lowercase alpha. +.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: -You can use the 'style' attribute to specify an alternative numbering -style. The numbered list style can be set to one of the following -values: 'arabic', 'loweralpha', 'upperalpha', 'lowerroman', -'upperroman'. +..................................................................... +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. +..................................................................... -Examples of numbered list items: +.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. -1. Arabic (decimal) numbered list item. -.. Lower case letter numbered list item. -a. Lower case letter numbered list item. -A. Upper case letter numbered list item. -iii. Lower case roman numbered list item. -IX. Upper case roman numbered list item. +. 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. + ** 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. - .. Fusce euismod commodo velit. - .. 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. ---------------------------------------------------------------------- - -Which render as: - - 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. + ** 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. -- 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. - .. Fusce euismod commodo velit. - .. Vivamus fringilla mi eu lacus. - 3. Donec eget arcu bibendum nunc consequat lobortis. - 4. Nam fermentum mattis ante. 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: @@ -1433,18 +1716,26 @@ 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 the +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 a double colon `::` or -semi-colon `;;`. A list item can have multiple labels, one per line. +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. @@ -1467,10 +1758,12 @@ 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:: @@ -1488,15 +1781,18 @@ 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 places the list text side-by-side -with the label instead of under the label. Here is an example: +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. @@ -1531,17 +1827,16 @@ [NOTE] ===================================================================== - Current PDF toolchains do not make a good job of determining the relative column widths for horizontal labeled lists. -- If you are generating DocBook markup then horizontal labeled lists - should not be nested because the 'DocBook XML V4.2' DTD does not - permit nested informal tables (although <<X13,DocBook XSL - Stylesheets>> and <<X31,dblatex>> process them correctly). +- 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 @@ -1578,56 +1873,56 @@ 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 glossary section. +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]]]` +`[<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 +`<<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 bibliography section. +located in a <<X93,bibliography section>>. [[X15]] List Item Continuation ~~~~~~~~~~~~~~~~~~~~~~ -To include subsequent block elements in list items (in addition to -implicitly included nested lists and Literal paragraphs) place a -separator line containing a single plus character between the list -item and the ensuing list continuation element. Multiple block -elements (excluding section Titles and BlockTitles) may be included in -a list item using this technique. Note that the continued items must -be indented as they normally would be outside of the list. +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). -You also need to use list item continuation if a nested list is -accompanied by an <<X21,attribute list>>. +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: -Here's an example of list item continuation: - --------------------------------------------------------------------- 1. List item one. + List item one continued with a second paragraph followed by an Indented block. @@ -1635,162 +1930,108 @@ ................. $ ls *.sh $ mv *.sh ~/tmp ................. + -List item one continued with a third paragraph. +List item continued with a third paragraph. -2. List item two. +2. List item two continued with an open block. ++ +-- +This paragraph is part of the preceding list item. - List item two literal paragraph (no continuation required). - -- Nested list (item one). - - Nested list literal paragraph (no continuation required). +a. This list is nested and does not require explicit item continuation. + -Nested list appended list item one paragraph +This paragraph is part of the preceding list item. -- Nested list item two. +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 a Listing -block. +List item one continued with a second paragraph followed by an +Indented block. + ................. $ ls *.sh $ mv *.sh ~/tmp ................. + -List item one continued with a third paragraph. +List item continued with a third paragraph. -2. List item two. - - List item two literal paragraph (no continuation required). - -- Nested list (item one). - - Nested list literal paragraph (no continuation required). +2. List item two continued with an open block. + -Nested list appended list item one paragraph - -- Nested list item two. - - -[[X29]] -List Block -~~~~~~~~~~ -A List block is a special delimited block containing a list element. - -- All elements between in the List Block are part of the preceding - list item. In this respect the List block behaves like <<X15,List - Item Continuation>> except that list items contained within the - block do not require explicit `+` list item continuation lines: -- The block delimiter is a single line containing two dashes. -- Any block title or attributes are passed to the first element inside - the block. - -The List Block is useful for: - -1. Lists with long multi-element list items. -2. Nesting a list within a parent list item (by default nested lists - follow the preceding list item). - -Here's an example of a nested list block: - ---------------------------------------------------------------------- -.Nested List Block -1. List item one. -+ -This paragraph is part of the preceding list item -+ -- +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. -This paragraph is part of the preceding list item - b. List item b. -This paragraph belongs to list item b. +This paragraph belongs to item two of the outer list. -- -+ -This paragraph belongs to item 1. -2. Item 2 of the outer list. ---------------------------------------------------------------------- -Renders: +[[X92]] +Footnotes +--------- +The shipped AsciiDoc configuration includes three footnote inline +macros: -.Nested List Block -1. List item one. -+ -This paragraph is part of the preceding list item -+ --- -a. This list is nested and does not require explicit item continuation. +`footnote:[<text>]`:: + Generates a footnote with text `<text>`. -This paragraph is part of the preceding list item +`footnoteref:[<id>,<text>]`:: + Generates a footnote with a reference ID `<id>` and text `<text>`. -b. List item b. +`footnoteref:[<id>]`:: + Generates a reference to the footnote with ID `<id>`. -This paragraph belongs to list item b. --- -+ -This paragraph belongs to item 1. +The footnote text can span multiple lines. -2. Item 2 of the outer list. +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: -Footnotes ---------- -The shipped AsciiDoc configuration includes the `\footnote:[<text>]` -and `\footnoteref:[<id>,<text>]` inline macros for generating -footnotes: - -- The `footnote` macro generates a footnote. -- The `footnoteref` macro has two forms: if the text is supplied a - foot note with an ID is generated; if the text is omitted a - reference to the footnote with the specified ID is generated. -- The footnote text can span multiple lines. - -Example footnote: - 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]. -Which renders: +Renders: A footnote footnote:[An example footnote.]; -a second footnote with a reference ID footnoteref:[note2,Second footnote]; +a second footnote with a reference ID footnoteref:[note2,Second footnote.]; finally a reference to the second footnote footnoteref:[note2]. -Footnotes are primarily useful when generating DocBook output -- -DocBook conversion programs render footnote outside the primary text -flow. - Indexes ------- The shipped AsciiDoc configuration includes the inline macros for -generating document index entries. +generating DocBook index entries. -`\indexterm:[<primary>,<secondary>,<tertiary>]`:: -`\(((<primary>,<secondary>,<tertiary>)))`:: - This inline macro generates an index term (the <secondary> and - <tertiary> attributes are optional). For example - `\indexterm:[Tigers,Big cats]` (or, using the alternative syntax - `\(((Tigers,Big cats)))`. Index terms that have secondary and +`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>))`:: +`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 @@ -1801,12 +2042,12 @@ an index at the point an 'Index' section appears in source document. Callouts -------- -Callouts are a mechanism for annotating verbatim text (source code, -computer output and user input for example). Callout markers are +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: --------------------------------------------------------------------- @@ -1850,27 +2091,28 @@ <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 that - refer to an item index 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). +- 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 -- start list items hard against - the left margin. +- 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: To include callout icons in PDF files generated by -<<X43,a2x(1)>> you need to use the `--icons` command-line option. +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 @@ -1880,37 +2122,37 @@ substitution option. The following attributes are available during inline callout macro substitution: -`\{index}`:: +`{index}`:: The callout list item index inside the angle brackets. -`\{coid}`:: +`{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 +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 -<<X57,Source Code Highlighter Filter>>: +'source' (code highlighter) filter: .AsciiDoc source --------------------------------------------------------------------- -[source,python] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -\include::test.py[] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + [source,python] + ------------------------------------------- + \include::test.py[] + ------------------------------------------- -\<1> Print statement. + \<1> Print statement. --------------------------------------------------------------------- .Included `test.py` source --------------------------------------------------------------------- print 'Hello World!' # \<1> @@ -1925,36 +2167,36 @@ 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.methods.co.nz/asciidoc/index.html[Asciidoc home page] + 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 in attribute lists that are enclosed in `[]` brackets - must be escaped with a backslash. -- Expansion of non-system macro references can normally be escaped by - prefixing a backslash character (see the AsciiDoc 'FAQ' for examples - of exceptions to this rule). -- System macros cannot be escaped. +- `]` 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>>. + <<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. @@ -1962,41 +2204,35 @@ URLs ^^^^ 'http', 'https', 'ftp', 'file', 'mailto' and 'callto' URLs are rendered using predefined inline macros. -- If you don't need a customized the link caption you can enter the - 'http', 'https', 'ftp', 'file' URLs and email addresses without any - special macro syntax. +- 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.methods.co.nz/asciidoc/[The AsciiDoc home page] - http://www.methods.co.nz/asciidoc/ + http://www.docbook.org/[DocBook.org] + http://www.docbook.org/ mailto:joe.bloggs@foobar.com[email Joe Bloggs] joe.bloggs@foobar.com - callto:joe.bloggs[] Which are rendered: -http://www.methods.co.nz/asciidoc/[The AsciiDoc home page] +http://www.docbook.org/[DocBook.org] -http://www.methods.co.nz/asciidoc/ +http://www.docbook.org/ mailto:joe.bloggs@foobar.com[email Joe Bloggs] joe.bloggs@foobar.com -callto:joe.bloggs[] +If the `<target>` necessitates space characters use `%20`, for example +`large%20image.png`. -- If the `<target>` necessitates space characters they should be - replaced by `%20`. For example `large%20image.png`. -- Define an attribute entry if you refer to the same URL more than - once, this will make your document <<X62,easier to maintain and - easier to read>>. - 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. @@ -2007,14 +2243,15 @@ Used to specify hypertext link targets: [[<id>,<xreflabel>]] anchor:<id>[<xreflabel>] -The `<id>` is a unique identifier that must begin with a letter. 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: +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 @@ -2025,20 +2262,20 @@ Creates a hypertext link to a document anchor. <<<id>,<caption>>> xref:<id>[<caption>] -The `<id>` refers to an existing anchor `<id>`. The optional -`<caption>` is the link's displayed text. Example: +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` backend displays the `<id>` enclosed in - square brackets. +- 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: @@ -2068,12 +2305,10 @@ 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. -Images can serve as hyperlinks using the <<X9,`image` macro>>. - [[X9]] Images ^^^^^^ Inline images are inserted into the output document using the 'image' macro. The inline syntax is: @@ -2088,16 +2323,23 @@ `<target>` file name paths are relative to the location of the referring document. [[X55]] .Image macro attributes -- The optional first positional attribute list entry specifies the - alternative text which is displayed if the output application is - unable to process the image file. For example: +- 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: @@ -2111,18 +2353,30 @@ - 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["Company Logo",scaledwidth="75%"] + 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 in DocBook block images (specifically for PDF documents). - Allowed values are `center`, `left` and `right`. For example: + 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. @@ -2137,76 +2391,90 @@ 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 employ the `id` -attribute as a block link target. For example: +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"]` block attribute list. +This is equivalent to the `[id="X30"]` <<X79,AttributeList element>>). [[X49]] Images ^^^^^^ -Formal titled images are inserted into the output document using the -'image' macro. The syntax is: +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 its -<<X9,inline counterpart>>. +The block `image` macro has the same <<X55,macro attributes>> as it's +<<X9,inline image macro>> counterpart. -Images can be titled by preceding the `image` macro with a -'BlockTitle'. DocBook toolchains normally number examples and -generate a 'List of Figures' backmatter section. +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. -For example: +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 -(`xhtml11` and `html4` backends). For example: +(HTML backends). For example: .Main circuit board - [caption="Figure 2:"] + [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 referenced by -'image' macros 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 to produce single-file XHTML -documents with embedded images and CSS, for example: +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 --unsafe -a data-uri mydocument.txt + $ asciidoc -a data-uri mydocument.txt -You will need to specify the `--unsafe` option because the AsciiDoc -`data-uri` is implemented using the `\{sys}` attribute. - -NOTE: Internet Explorer up to version 7 does not support 'data: URIs', -but it is supported by Internet Explorer 8 Beta 1. - +[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 and are stripped from the output. -Comment lines have been implemented as a block macro and are only -valid in a block context -- they are not treated as comments inside -paragraphs or delimited blocks. Example comment line: +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. -See also <<X26,Comment Blocks>>. +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. @@ -2225,13 +2493,13 @@ 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 main use is to include -verbatim embedded CSS or scripts into configuration file headers. -Example: +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] ------------------------------------ @@ -2246,11 +2514,11 @@ - 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 one disables + does not process nested includes). Setting 'depth' to '1' disables nesting inside the included file. By default, nesting is limited to a depth of five. - 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 @@ -2258,84 +2526,83 @@ 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. There are two forms of conditional inclusion -macro usage, the first includes document text between the `ifdef` and -`endif` macros if a document attribute is defined: +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>[] -The second for includes document text between the `ifndef` and `endif` -macros if the attribute is not defined: +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. -Take a look at the `*.conf` configuration files in the AsciiDoc -distribution for examples of conditional inclusion macro usage. +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: -.Two types of conditional inclusion -********************************************************************* -Conditional inclusion macros are evaluated when they are read, but -there is another type of conditional inclusion based on attribute -references, the latter being evaluated when the output file is -written. + ifdef::revnumber[Version number 42] -These examples illustrate the two forms of conditional inclusion. The -only difference between them is that the first is evaluated at program -load time while the second is evaluated when the output is written: +Is equivalent to: - ifdef::world[] - Hello World! - endif::world[] + ifdef::revnumber[] + Version number 42 + endif::revnumber[] - {world#}Hello World! +'ifdef' and 'ifndef' macros also accept multiple attribute names: -In this example when the `\{world#}` conditional attribute reference -is evaluates to a zero length string if `world` is defined; if `world` -is not defined the whole line is dropped. +- 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. -The subtle difference between the two types of conditional inclusion -has implications for AsciiDoc configuration files: AsciiDoc has to -read the configuration files *before* reading the source document, -this is necessary because the AsciiDoc source syntax is mostly defined -by the configuration files. This means that any lines of markup -enveloped by conditional inclusion macros will be included or excluded -*before* the attribute entries in the AsciiDoc document header are -read, so setting related attributes in the AsciiDoc source document -header will have no effect. If you need to control configuration file -markup inclusion with attribute entries in the AsciiDoc source file -header you need to use attribute references to control inclusion -instead of conditional inclusion macros (attribute references are -substituted at the time the output is written rather than at program -startup). +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::[] -eval, sys and sys2 System Macros -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -These 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 an inline context where attribute substitution is enabled. +- 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]` @@ -2358,14 +2625,15 @@ 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). +`<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 + 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>] @@ -2381,28 +2649,33 @@ Red [red]+++`sum_(i=1)\^n i=(n(n+1))/2`$+++ AsciiMathML formula $$:: Inline and block. The double-dollar passthrough is functionally - identical with one exception: special characters are escaped. - Example: + 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>=<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 @@ -2442,98 +2715,159 @@ 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. -There are a wide variety of built-in customizable styles. -- All table meta-data is contained specified in the table's attribute - list, not in the the table data. -- There is no provision for cells to span multiple columns. +- 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. This is no accident, like figures, tables are outside the -normal document flow -- tables are for consulting not for reading. +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 -^^^^^^^^^^^^ +.Simple table [width="15%"] |======= |1 |2 |A |3 |4 |B |5 |6 |C |======= -AsciiDoc source: - +.AsciiDoc source --------------------------------------------------------------------- [width="15%"] |======= |1 |2 |A |3 |4 |B |5 |6 |C |======= --------------------------------------------------------------------- -Columns formatted with strong, monospaced and emphasis styles -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.An example table -[width="50%",cols=">s,^m,e",frame="none",options="header,footer"] +.Columns formatted with strong, monospaced and emphasis styles +[width="50%",cols=">s,^m,e",frame="topbot",options="header,footer"] |========================== -| |Column 2|Column 3 +| 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: - +.AsciiDoc source --------------------------------------------------------------------- .An example table -[width="50%",cols=">s,^m,e",frame="none",options="header,footer"] +[width="50%",cols=">s,^m,e",frame="topbot",options="header,footer"] |========================== -| |Column 2|Column 3 +| 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 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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. - -.Windtrainer workouts +.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 | @@ -2547,12 +2881,15 @@ Moderately hard interspersed with 3x 3min intervals (2min hard + 1min really hard taking the HR up to 160). |========================================================= -AsciiDoc source: +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 @@ -2569,68 +2906,80 @@ hard + 1min really hard taking the HR up to 160). |========================================================= --------------------------------------------------------------------- -A table with externally sourced CSV data -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - +.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: - +.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 AsciiDoc table format is 'psv'. +default table format is 'psv'. -'csv' is the quasi-standard row oriented 'Comma Separated Values -(CSV)' format commonly used to import and export spreadsheet and -database data. - 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 mandatory row separators. +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, that really the only difference (apart from - different default separators). + cells with a separator. - 'psv' and 'dsv' separators are Python regular expressions. -- The default 'psv' separator is `((?P<cellcount>\d+)\*)?\|` (a pipe - character with optional cell multiplier prefix); the default 'dsv' - separator is `:|\n` (a colon or a line break). +- 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. -- The 'psv' format allows cells to be stacked vertically, this makes - it easy to enter large amounts of text per cell while still - retaining readability. -Here are four 'psv' cells (the second item is multiplied by two; the +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 + |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 ~~~~~~~~~~~~~~~~ -Individual tables are customized by an optional <<X21,AttributeList>> -preceding the table. Specify attributes when you want to change the -default table format: +Tables can be customized by the following attributes: format:: 'psv' (default), 'dsv' or 'csv' (See <<X68, Table Data Formats>>). separator:: @@ -2645,78 +2994,157 @@ 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'). +(defaults to 'top'). Overridden by <<X70,Column specifiers>> and +<<X84,Cell specifiers>>. options:: -The 'options' attribute can contain the following comma separated -values: 'header', 'footer'. By default header and footer rows are -omitted. +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 outputs use this value directly. If width is -specified DocBook uses the absolute widths (see calculated -<<X72,markup attributes>> ), if no width is specified all of the -available width is used. +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 presented and are used in the +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...) + 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 column '<align>' character can be '<' (left), '^' (center) or - '>' (right). Cells are left aligned by default. -- A '<multiplier>' can be used to specify repeated columns e.g. - `cols="4*<"` specifies four left-justified columns. Default value 1. -- The '<style>' name specifies a <<X71,table style>> to used to markup +- 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' row formatting. +- 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>>). -Tables come with the following predefined styles: +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. @@ -2727,84 +3155,138 @@ 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. +as a filter to process cell contents. See also <<X83,Docbook table +limitations>>. literal:: No text formatting; monospaced font; all line breaks are retained -(like AsciiDoc 'LiteralBlock'). +(the same as the AsciiDoc <<X65,LiteralBlock>> element). verse:: -Text formatting; all line breaks are retained (c.f. AsciiDoc delimited -block 'verse' style). +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. Both absolute and percentage width values are -available. Column specific attributes are available when substituting -the 'colspec' cell data tags. +templates and tags. Column specific attributes are available when +substituting the 'colspec' cell data tags. pageunits:: -Only used by DocBook, defaults to 'pt'. +DocBook backend only. Specifies table column absolute width units. +Defaults to '*'. pagewidth:: -The nominal output page width in 'pageunit' units. Used to calculate -table and column widths. Only used by DocBook, defaults to '425'. +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). -colalign:: -'left', 'right' or 'center'. - 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). -colnumber:: -Integer value: '1' for column 1, '2' for column 2 ... +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 table syntax using a '!' character instead of a '|' -character is provided to allow a single level of table nesting. +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`. -NOTE: When generating PDF nested tables using `a2x(1)` you will need -to use the `--no-xmllint` option. This is because the nested tables -are not legal in DocBook (you have to use the DocBook 4 'entrytbl' -element). But both 'dblatex' (as of version 0.28) and 'FOP' (as of -version 0.95beta) will process nested DocBook tables, but not -'entrytbl' elements. +[[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 for a UNIX environment, you're going +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 you can compose -AsciiDoc files that will translate to a DocBook refentry (man page) -document. The resulting DocBook file can then be translated to the +AsciiDoc files that will generate DocBook refentry (man page) +documents. The resulting DocBook file can then be translated to the native roff man page format (or other formats). For example, the `asciidoc.1.txt` file in the AsciiDoc distribution `./doc` directory was used to generate both the `asciidoc.1.css-embedded.html` HTML file the `asciidoc.1` roff @@ -2824,23 +3306,22 @@ 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 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 +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 @@ -2859,16 +3340,16 @@ ~~~~~~~~~~~~~~~~~~~~~~ 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 +`{mansource}`, `{manversion}` and `{manmanual}` attributes respectively. This example is from the AsciiDoc header of a man page source file: :man source: AsciiDoc - :man version: {revision} + :man version: {revnumber} :man manual: AsciiDoc Manual [[X78]] Mathematical Formulas @@ -2891,12 +3372,12 @@ 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 http://www.methods.co.nz/asciidoc/[AsciiDoc -website] or the distributed `doc/latexmath.txt` file. +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 @@ -2906,30 +3387,30 @@ 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' backend. To enable ASCIIMathML support you must define the -'asciimath' attribute, for example using the `-a asciimath` +'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 http://www.methods.co.nz/asciidoc/[AsciiDoc -website] or the distributed `doc/asciimathml.txt` file. +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' backend. AsciiDoc -uses the +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 @@ -2937,16 +3418,13 @@ 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 http://www.methods.co.nz/asciidoc/[AsciiDoc -website] or the distributed `doc/latexmathml.txt` file. +For more examples see the {website}[AsciiDoc website] or the +distributed `doc/latexmathml.txt` file. -There are more examples on the -http://www.methods.co.nz/asciidoc/[AsciiDoc website]. - 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 @@ -3113,11 +3591,11 @@ 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 +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. @@ -3134,16 +3612,16 @@ ~~~~~~~~~~~~~~~~~~~~~~~~~~ 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_character>=<translated_characters> Special characters are normally confined to those that resolve -markup ambiguity (in the case of SGML/XML markups the ampersand, less -than and greater than characters). The following example causes all -occurrences of the `<` character to be replaced by `\&lt;`. +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 `&lt;`. <=&lt; Quoted Text section ~~~~~~~~~~~~~~~~~~~ @@ -3171,12 +3649,12 @@ [quotes] ^= ~= -<<X52,Unconstrained quotes>> are differentiated by prefixing the tag -name with a hash character, for example: +<<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. @@ -3191,20 +3669,20 @@ 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=NOTE IMPORTANT [strongwords] <strong>{words}</strong> -The examples specifies that any occurrence of `NOTE:` or `IMPORTANT:` +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 +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 @@ -3214,20 +3692,20 @@ .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. + +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 + `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 @@ -3238,11 +3716,11 @@ Replacements section ~~~~~~~~~~~~~~~~~~~~ `[replacements]` and `[replacements2]` configuration file entries specify find and replace text and are formatted like: - find_pattern=replacement_text + <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 @@ -3273,104 +3751,108 @@ - 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}` +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 and Locations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Configuration file names, precedence and locations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Configuration files have a `.conf` file name extension; they are -loaded implicitly (using predefined file names and locations) or -explicitly (using the asciidoc(1) `-f` (`--conf-file`) command-line -option). +loaded from the following locations: -Implicit configuration files are loaded from the following directories -in the following order: - -1. The global configuration directory (normally `/etc/asciidoc` or - `/usr/local/etc/asciidoc`) if it exists. -2. The directory containing the asciidoc executable. +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. -The following implicit configuration files from each of the above -locations are loaded in the following order: +Configuration files from the above locations are loaded in the +following order: -1. `asciidoc.conf` -2. `<backend>.conf` -3. `<backend>-<doctype>.conf` -4. `lang-<lang>.conf` +- 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. -Where `<backend>` and `<doctype>` are values specified by the -asciidoc(1) `-b` (`--backend`) and `-d` (`--doctype`) command-line -options. `<lang>` is the value of the AsciiDoc `lang` attribute -(defaults to `en` (English)). +- `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>.conf` and `<backend>-<doctype>.conf` from locations 1, + 2,3. +- Filter conf files from the `filters` directory in locations 1, 2, 3. +- `lang-<lang>.conf` from locations 1, 2, 3. +- `asciidoc.conf` from location 4. +- `<backend>.conf` and `<backend>-<doctype>.conf` from location 4. + 2,3. +- Filter conf files from location 4. +- `<docfile>.conf` and `<docfile>-<backend>.conf` from location 4. +- Configuration files from location 5. -Finally, configuration files named like the source file will be -automatically loaded if they are found in the source file directory. -For example if the source file is `mydoc.txt` and the -`--backend=html4` option is used then asciidoc(1) will look for -`mydoc.conf` and `mydoc-html4.conf` in that order. +Where: -Implicit configuration files that don't exist will be silently -skipped. +- `<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. -The user can explicitly specify additional configuration files using -the asciidoc(1) `-f` (`--conf-file`) command-line option. The `-f` -option can be specified multiple times, in which case configuration -files will be processed in the order they appear on the command-line. +[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: -For example, when we translate our AsciiDoc document `mydoc.txt` with: + Life's Mysteries + ================ + :author: Hu Nose + :doctype: book + :toc: + :icons: + :data-uri: + :lang: en + :encoding: iso-8859-1 - $ asciidoc -f extra.conf mydoc.txt +Attributes set in the document header take precedence over +configuration file attributes. -Configuration files (if they exist) will be processed in the following -order: +===================================================================== -1. First default global configuration files from the asciidoc program - directory are loaded: - - asciidoc.conf - xhtml11.conf - -2. Then, from the users home `~/.asciidoc` directory. This is were - you put customization specific to your own asciidoc documents: - - asciidoc.conf - xhtml11.conf - xhtml11-article.conf - -3. Next from the source document project directory (the first three - apply to all documents in the directory, the last two are specific - to the mydoc.txt document): - - asciidoc.conf - xhtml11.conf - xhtml11-article.conf - mydoc.conf - mydoc-xhtml11.conf - -4. Finally the file specified by the `-f` command-line option is - loaded: - - extra.conf - 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 its corresponding attribute -value. +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. @@ -3379,11 +3861,11 @@ - Intrinsic attributes. Within each of these divisions the last processed entry takes precedence. -IMPORTANT: If an attribute is not defined then the line containing the +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. @@ -3399,97 +3881,114 @@ For example: :Author Initials: JB -This will set an attribute reference `\{authorinitials}` to the value +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 and dash characters only -- all other characters - deleted). This allows more reader friendly text to be used. + 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. -- Special characters in the entry `<value>` are substituted. You can - enter special characters using character entity values, for example - `\&amp;`. - 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 a - different AttributeEntry substitution set the `attributeentry-subs` - attribute. + `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 -:Date: April 23, 2004 -:Revision: 5.1.1 -:Key words: linux, ralink, debian, wireless -:Revision history: +:author: Stuart Rackham +:email: srackham@gmail.com +:revdate: April 23, 2004 +:revnumber: 5.1.1 --------------------------------------------------------------------- Which creates these attributes: {author}, {firstname}, {lastname}, {authorinitials}, {email}, - {date}, {revision}, {keywords}, {revisionhistory} + {revdate}, {revnumber} -The preceding example is equivalent to the standard AsciiDoc two line -document header. Actually it's a little bit different with the -addition of the `\{keywords}` and `\{revisionhistory}` attributes -footnote:[The existence of a `\{revisionhistory}` attribute causes a -revision history file (if it exists) to be included in DocBook -outputs. If a file named like `\{docname}-revhistory.xml` exists in -the document's directory then it will be added verbatim to the DocBook -header (see the `./doc/asciidoc-revhistory.xml` example that comes -with the AsciiDoc distribution).]. +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 -entries to be set from within an AsciiDoc document: +section entries and markup template sections to be set from within an +AsciiDoc document: - :<section_name>.<entry_name>: <entry_value> + :<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': +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://hg.sharesource.org/asciidoc/[AsciiDoc home page] + :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}. @@ -3498,55 +3997,51 @@ - 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 and inline quotes: +- 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. -- Attribute values are enclosed in quotation mark (") characters. -- If the attribute list only contains positional attribute values and - the values contain no commas then quoting is unnecessary. +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 (`&#44;`) and double-quote (`&#34;`) character entities: -Here are three examples (a single unquoted positional attribute; three -unquoted attribute values; one positional attribute followed by two -named attributes): - [Hello] [quote, Bertrand Russell, The World of Mathematics (1956)] ["22 times", backcolor="#0e0e0e", options="noborders,wide"] + [A footnote&#44; &#34;with an image&#34; image:smallnew.png[]] .Attribute list behavior -- If one or more attribute values contains a comma the all values must - be quoted (enclosed in quotation characters). +- 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 quotation mark (") character in a quoted attribute - value the the quotation mark must be escaped with a backslash. +- 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 inside the document. -- Attribute references are allowed inside attribute lists -- this is - the only substitution performed on attribute lists. + 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 +- Positional attributes are referred to as `{1}`,`{2}`,`{3}`,... +- Attribute `{0}` refers to the entire list (excluding the enclosing square brackets). -- Attribute lists are evaluated as a list of Python function - arguments. If this fails or any of the items do not evaluate to a - string, a number or None then all list items are treated as string - literals. +- Named attribute names cannot contain dash characters. [[X75]] Options attribute ~~~~~~~~~~~~~~~~~ If the attribute list contains an attribute named `options` it is @@ -3567,109 +4062,118 @@ ~~~~~~~~~~~~~~~~~~~~~ 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. -AttributeList Element -~~~~~~~~~~~~~~~~~~~~~ -An <<X21,attribute list>> on a line by itself constitutes an -'AttributeList' block element, its attributes apply to the following -block element. The list attributes are passed to the next block -element for markup template substitution. Often the first list -parameter is used to specify the element's <<X23,style>>. - Attribute References -------------------- -An attribute references is an attribute name (possibly followed by an -additional parameters) enclosed in braces. When an attribute +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 behavior +.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. + '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 +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 the attribute name -to calculate a substitution value. Conditional attribute references -take the following forms: +Additional parameters are used in conjunction with attribute names to +calculate a substitution value. Conditional attribute references take +the following forms: -`\{<name>=<value>}`:: - `<value>` is substituted if the attribute `<name>` is +`{<names>=<value>}`:: + `<value>` is substituted if the attribute `<names>` is undefined otherwise its value is substituted. `<value>` can contain simple attribute references. -`\{<name>?<value>}`:: - `<value>` is substituted if the attribute `<name>` is defined +`{<names>?<value>}`:: + `<value>` is substituted if the attribute `<names>` is defined otherwise an empty string is substituted. `<value>` can contain simple attribute references. -`\{<name>!<value>}`:: - `<value>` is substituted if the attribute `<name>` is +`{<names>!<value>}`:: + `<value>` is substituted if the attribute `<names>` is undefined otherwise an empty string is substituted. `<value>` can contain simple attribute references. -`\{<name>#<value>}`:: - `<value>` is substituted if the attribute `<name>` is defined +`{<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. -`\{<name>%<value>}`:: - `<value>` is substituted if the attribute `<name>` is not +`{<names>%<value>}`:: + `<value>` is substituted if the attribute `<names>` is not defined otherwise the containing line is dropped. `<value>` can contain simple attribute references. -`\{<name>@<regexp>:<value1>[:<value2>]}`:: - `<value1>` is substituted if the value of attribute `<name>` +`{<names>@<regexp>:<value1>[:<value2>]}`:: + `<value1>` is substituted if the value of attribute `<names>` matches the regular expression `<regexp>` otherwise `<value2>` - is substituted. If attribute `<name>` is not defined the + 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. -`\{<name>$<regexp>:<value1>[:<value2>]}`:: +`{<names>$<regexp>:<value1>[:<value2>]}`:: Same behavior as the previous ternary attribute except for the following cases: - `\{<name>$<regexp>:<value>}`;; - Substitutes `<value>` if `<name>` matches `<regexp>` + `{<names>$<regexp>:<value>}`;; + Substitutes `<value>` if `<names>` matches `<regexp>` otherwise the result is undefined and the containing line is dropped. - `\{<name>$<regexp>::<value>}`;; - Substitutes `<value>` if `<name>` does not match + `{<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 `docbook` or `xhtml11` the example evaluates to - ``DocBook or XHTML backend'' otherwise it evaluates to ``some other - backend'': + 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@docbook|xhtml11:DocBook or XHTML backend: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`]: @@ -3678,55 +4182,112 @@ [[X24]] System Attribute References ~~~~~~~~~~~~~~~~~~~~~~~~~~~ System attribute references generate the attribute text value by -executing a predefined action that is parametrized by a single -argument. The syntax is `{<action>:<argument>}`. +executing a predefined action that is parametrized by one or more +arguments. The syntax is `{<action>:<arguments>}`. -`\{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. In all - remaining cases the attribute evaluates to a string - representation of the `<expression>` result. +`{counter:<attrname>[:<seed>]}`:: + Increments the document attribute (if the attribute is + undefined it is set to `1`). Returns the new attribute value. -`\{include:<filename>}`:: + - 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. -`\{sys:<command>}`:: +`{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>}`:: +`{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 them with a backslash. + 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, execution parameters along with attributes -defined in the default configuration files. Here's the list of +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 + {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, @@ -3736,66 +4297,90 @@ {backend} document backend specified by `-b` option {backslash} backslash character {basebackend-<base>} empty string '' {basebackend} html or docbook {brvbar} broken vertical bar (|) character - {date} document date (from document header) - {docname} document file name without extension + {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 + {gt} greater than (>) character entity {id} running block id generated by BlockId elements - {indir} document input directory name (note 1) - {infile} input file name (note 1) + {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 - {lt} less than (<) character + {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 entity - {outdir} document output directory name (note 1) - {outfile} output file name (note 1) - {revision} document revision number (from document header) - {sectnum} section number (in section titles) + {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) + {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) + {showcomments} send comment lines to the output {title} section title (in titled elements) - {two_colons} Two colon characters. - {two_semicolons} Two semicolon characters. + {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 + {zwsp} Zero-width space character entity -.NOTES +[NOTE] +====== 1. Intrinsic attributes are global so avoid defining custom attributes with the same names. - -2. `\{infile}`, `\{outdir}`, `\{infile}`, `\{indir}` attributes are +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 <<X33,xhtml11>> subsection for attributes that relate - to AsciiDoc XHTML file generation. - +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]. +====== + [[X73]] Block Element Definitions ------------------------- The syntax and behavior of Paragraph, DelimitedBlock, List and Table block elements is determined by block definitions contained in @@ -3815,25 +4400,28 @@ 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 it also matches the last - line. Table elements don't have an explicit delimiter -- they - synthesize their delimiters at runtime. + 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. + 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. @@ -3906,24 +4494,24 @@ 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. +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 Default paragraph definition has a couple of special properties: +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 @@ -3961,16 +4549,13 @@ The block contents are processed as a SectionBody. skip:: The block is treated as a comment (see <<X26,CommentBlocks>>). -list:: - The block is a <<X29,list block>>. +'presubs', 'postsubs' and 'filter' entries are ignored when +'sectionbody' or 'skip' options are set. -'presubs', 'postsubs' and 'filter' entries are meaningless when -'sectionbody', 'skip' or 'list' 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 @@ -3985,11 +4570,11 @@ before it is executed, this is useful for passing arguments to the filter. Lists ~~~~~ -List behavior and syntax is determined by `[listdef*]` configuration +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: @@ -4009,18 +4594,18 @@ 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 +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 +configuration files. The following `[tabledef-*]` section entries generate table output markup elements: -comspec:: - The table 'comspec' tag definition. +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. @@ -4059,71 +4644,76 @@ [[X59]] Filters ------- -Filters are external shell commands used to process Paragraph and -DelimitedBlock content; they are specified in configuration file -Paragraph and DelimitedBlock definitions. +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. + 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 can potentially generate unsafe output. Before -installing a filter you should verify that it can't be coerced into -generating malicious output or exposing sensitive information. +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) searches for the command: +asciidoc(1) recursively searches for the executable filter command: - First it looks in the user's `$HOME/.asciidoc/filters` directory. -- Next the `/etc/asciidoc/filters` directory is searched. +- 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`). -Sub-directories are also included in the searches -- 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. +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 +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 an existing Paragraph or DelimitedBlock definition +<<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 (see previous section). [[X56]] -Code Filter -~~~~~~~~~~~ +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: This filter primarily 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 -<<X57,Source Code Highlighter Filter>>. +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]. [listing] ..................................................................... .Code filter example [code,python] @@ -4154,37 +4744,37 @@ return quote + word + quote else: return word ---------------------------------------------- -[[X57]] -Source Code Highlighter Filter -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A -http://www.methods.co.nz/asciidoc/source-highlight-filter.html[source -code highlighter filter] can be found in the AsciiDoc distribution -`./filters` directory. +Built-in filters +~~~~~~~~~~~~~~~~ +The AsciiDoc distribution includes 'source', 'music', 'latex' and +'graphviz' filters, details are on the +{website}index.html#_filters[AsciiDoc website]. [[X58]] -Music Filter -~~~~~~~~~~~~ -A http://www.methods.co.nz/asciidoc/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 Western classical -notation in the form of a trimmed PNG image which is automatically -inserted into the output document. +Filter plugins +~~~~~~~~~~~~~~ +Filter plugins are a simple mechanism for distributing AsciiDoc +filters. A filter plugin is a Zip file containing the files that +constitute a filter. The asciidoc(1) `--filter` option implements +commands to install, remove and list filter plugins. Filter plugin +commands and conventions are documented in the asciidoc(1) man page. +You can find a list of filter plugins on the +{website}filters.html[AsciiDoc website]. [[X12]] Converting DocBook to other file formats ---------------------------------------- -DocBook files are validated, parsed and translated by 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, DVI, PostScript, LaTeX). +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. @@ -4192,19 +4782,19 @@ 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, 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 +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. All you need is -<<X40,xsltproc(1)>>, <<X13,DocBook XSL Stylesheets>> and optionally: -<<X31,dblatex>> or <<X14,FOP>> (if you want PDF); `w3m(1)` or -`lynx(1)` (if you want text). +`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: @@ -4221,24 +4811,24 @@ ~~~~~~~~~~~~~~~ AsciiDoc produces nicely styled HTML directly without requiring a DocBook toolchain but there are also advantages in going the DocBook route: -- HTML from DocBook includes automatically generated indexes, tables - of contents, footnotes, lists of figures and tables. +- 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, revision history, figure and table captions and admonition - captions will be output in the specified language (setting the - AsciiDoc 'lang' attribute sets the DocBook 'lang' attribute). + 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 (see the -http://www.methods.co.nz/asciidoc/[AsciiDoc website] for example). +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>>. @@ -4263,38 +4853,33 @@ Toolchain components summary ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ AsciiDoc:: Converts AsciiDoc (`.txt`) files to DocBook XML (`.xml`) files. -[[X13]] -http://docbook.sourceforge.net/projects/xsl/[DocBook XSL Stylesheets]:: +[[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]:: +[[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]:: +[[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]:: +[[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:: +[[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. @@ -4311,16 +4896,16 @@ 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.css` CSS stylesheet. +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. +(`./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. @@ -4329,17 +4914,20 @@ 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.sh article.fo article.pdf + $ 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: @@ -4372,35 +4960,10 @@ source text is fine), however you can convert AsciiDoc text files to formatted text using the AsciiDoc <<X43,a2x(1)>> toolchain wrapper utility. -XML and Character Sets ----------------------- -The default XML character set `UTF-8` is used when AsciiDoc generates -DocBook files but this can be changed by setting the `xmldecl` entry -in the `[attributes]` section of the `docbook.conf` file or by -composing your own configuration file `[header]` section). - -TIP: If you get an 'undefined entity' error when processing DocBook -files you'll may find that you've used an undefined HTML character -entity. An easy (although inelegant) fix is to use the character's -character code instead of its symbolic name (for example use `\&#160;` -instead of `\&nbsp;`). - -If your system has been configured with an XML catalog you may find a -number of entity sets are already automatically included. - -PDF Fonts -~~~~~~~~~ -The Adobe PDF Specification states that the following 14 fonts should -be available to every PDF reader: Helvetica (normal, bold, italic, -bold italic), Times (normal, bold, italic, bold italic), Courier -(normal, bold, italic, bold italic), Symbol and ZapfDingbats. -Non-standard fonts should be embedded in the distributed document. - - [[X36]] Help Commands ------------- The asciidoc(1) command has a `--help` option which prints help topics to stdout. The default topic summarizes asciidoc(1) usage: @@ -4470,18 +5033,17 @@ 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 + 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 @@ -4501,10 +5063,13 @@ [[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. @@ -4526,44 +5091,48 @@ \ comments=s1:/*,ex:*/,://,b:#,:%,:XCOMM,fb:-,fb:*,fb:+,fb:.,fb:> --------------------------------------------------------------------- Troubleshooting ~~~~~~~~~~~~~~~ -- The asciidoc(1) `-v` (`--verbose`) command-line option displays the - order of configuration file loading and warns of potential - configuration file problems. -- Not all valid AsciiDoc documents produce valid backend markup. Read - the <<X5,AsciiDoc Backends>> section if AsciiDoc output is rejected - as non-conformant by a backend processor. +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 ...` + 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:: - If text in your document is incorrectly interpreted as formatting - instructions you can suppress formatting by placing a backslash - character immediately in front of the leading quote character(s). - For example in the following line the backslash prevents text - between the two asterisks from being output in a strong (bold) - font: + You can suppress markup expansion by placing a backslash character + immediately in front of the element. The following example + suppresses inline monospaced formatting: - Add `\*.cs` files and `*.resx` files. + \+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 paragraph without an + 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:: @@ -4581,49 +5150,63 @@ 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 'companyname=Bill &amp; Ben' mydoc.txt + $ asciidoc -a 'orgname=Bill &amp; Ben Inc.' mydoc.txt -Macro attribute lists:: - If named attribute list entries are present then all string +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 that redefines the document underlines, pushing them down one -level. For example `combined.txt`: +document and use the `leveloffset` attribute to push them all down one +level. For example: ---------------------------------------------------------------------- -:titles.underlines: "__","==","--","~~","^^" - +[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 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 document Headers (Author and Revision lines) in the - included files -- conditionally exclude them if they are necessary - for stand-alone processing. +- 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 @@ -4646,18 +5229,18 @@ 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 -s -b docbook section1.txt + $ asciidoc -sb docbook section1.txt -Processing document snippets -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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> @@ -4671,12 +5254,12 @@ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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}` glossary entry is useful for - outputting trailing blank lines in markup templates. + 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 @@ -4686,27 +5269,40 @@ $ xmllint --format mydoc.xml Supporting minor DocBook DTD variations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The conditional inclusion of DocBook SGML markup at the end of the -distribution `docbook.conf` file illustrates how to support minor DTD -variations. The included sections override corresponding entries from -preceding sections. +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 of course that they consider you a trusted -source). This example creates a composite HTML configuration -file for `mydoc.txt`: +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 @@ -4720,11 +5316,11 @@ 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 +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 @@ -4732,11 +5328,11 @@ 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::backend-docbook[] +\ifdef::basebackend-docbook[] \eval::[Section.setlevel(0)] +++++++++++++++++++++++++++++++ <glossary> @@ -4744,11 +5340,11 @@ <glossdiv> ... </glossdiv> </glossary> +++++++++++++++++++++++++++++++ -\endif::backend-docbook[] +\endif::basebackend-docbook[] --------------------------------------------------------------------- Validating output files ~~~~~~~~~~~~~~~~~~~~~~~ Use `xmllint(1)` to check the AsciiDoc generated markup is both well @@ -4762,11 +5358,18 @@ 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 @@ -4784,12 +5387,13 @@ 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 A: Migration Notes ---------------------------- +[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 @@ -4809,34 +5413,36 @@ 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 B: Packager Notes ---------------------------- +[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 C: AsciiDoc Safe Mode ------------------------------- -AsciiDoc 'safe mode' skips potentially dangerous sections in AsciiDoc -source files by inhibiting the execution of arbitrary code or the -inclusion of arbitrary files. +[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 enabled by default and can only be disabled using the -asciidoc(1) `--unsafe` command-line option. +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 +- `include::<filename>[]` and `include1::<filename>[]` block macro files must reside inside the parent file's directory. -- `\{include:<filename>}` executable attribute files must reside +- `{include:<filename>}` executable attribute files must reside inside the source document directory. - Passthrough Blocks are dropped. [WARNING] ===================================================================== @@ -4847,45 +5453,48 @@ 2. Implementing elements that don't escape special characters. 3. Accepting configuration files from untrusted sources. ===================================================================== -Appendix D: Using AsciiDoc with non-English Languages ------------------------------------------------------ +[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, revision history, figure and table captions - and admonition captions are output in the specified language. - For example: + 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 or xhtml directly from asciidoc(1) you'll +- 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 default `asciidoc.conf` file). The easiest way is to - create a language `.conf` file (see the example `lang-es.conf` file - that comes with the AsciiDoc distribution). + 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>>. -- Some character sets display double-width characters (for example - Japanese). As far as <<X17,title underlines>> are concerned they - should be treated as single character. If you think this looks - untidy so you may prefer to use the <<X46,single line title>> - format. +[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. -Appendix E: Vim Syntax Highlighter ----------------------------------- 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 @@ -4895,85 +5504,347 @@ You can also turn on syntax highlighting by adding the following line to the end of you AsciiDoc source files: // vim: set syntax=asciidoc: -NOTE: Dag Wieers has implemented an alternative Vim syntax file for -AsciiDoc which can be found here -http://svn.rpmforge.net/svn/trunk/tools/asciidoc-vim/. +TIP: Bold fonts are often easier to read, use the Vim `:set +background=dark` command to set bold bright fonts. -NOTE: Emacs users: The http://xpt.sourceforge.net/[*Nix Power Tools -project] has released an -http://xpt.sourceforge.net/tools/doc-mode/[AsciiDoc syntax highlighter -for emacs]. +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. This list of limitations also discusses how to work -around the problems: +things wrong: -- Indented lists with preceding blank lines are sometimes mistaken - for literal (indented) paragraphs. You can work around this by - deleting the preceding blank line, or inserting a space in the - preceding blank lines, or putting a list continuation character - (`+`) in the preceding blank line. - - 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. -- If a closing block delimiter is not preceded by a blank line it is - sometimes mistaken for a title underline. A workaround is to insert - a blank line before the closing delimiter. -- If a list block delimiter is mistaken for a title underline precede - it with a blank line. - -- Lines within a paragraph beginning with a period will be highlighted - as block titles. For example: - - .chm file. -+ -To work around this restriction move the last word of the previous -line to the start of the current (although words starting with a -period should probably be quoted monospace which would also get around -the problem). - -TIP: Sometimes incorrect highlighting is caused by preceding lines -that appear blank but contain white space characters -- setting your -editor options so that white space characters are visible is a good -idea. - - [[X74]] -Appendix F: Attribute Options ------------------------------ +[appendix] +Attribute Options +----------------- Here is the list of predefined <<X75,attribute list options>>: -[cols="2,2,2,5",options="header"] +[cols="2e,2,2,5",frame="topbot",options="header"] |==================================================================== |Option|Backends|AsciiDoc Elements|Description -|compact |docbook, xhtml11 |bulleted list, numbered list| -Minimizes vertical space in the list +|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. -|strong |xhtml11,html4 |labeled lists| -Emboldens label text. +|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. -|footer |docbook, xhtml11, html4 |table| +|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, html4 |table| +|header |docbook, xhtml11, html5, html4 |table| The first row of the table is rendered as a header. -|breakable, unbreakable |docbook (XSL/FO) |table| -The 'breakable' options allows the table to break across page -boundaries (the default behavior); 'unbreakable' attempts to keep the -table together on a single page. If neither option is specified the -default XSL stylesheet behavior prevails. - |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 +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'. + +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', 'CSS' and 'Get Firefox!') 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>>. + +|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 and navigation +icons. 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. + +|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 it's 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 <<X99,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 <<X99,HTML stylesheets and JavaScript locations>>. + +|stylesheet |html5, xhtml11 | +The file name of an optional additional CSS <<X35,stylesheet>>. + +|theme |html5, xhtml11 | +Use alternative stylesheets (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-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.