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