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.

