text: 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.
  
  .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.
  
  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
  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.
  
  Use the asciidoc(1) `-d` (`--doctype`) option to specify the AsciiDoc
  document type -- the default document type is 'article'.
  
  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.
  
  
  