Download AsciiDoc User Guide

AsciiDoc User Guide
Introduction
This is an overly large document, it probably needs to be refactored into a Tutorial, FAQ, Quick
Reference and Formal Reference.
If you're new to AsciiDoc read this section and the Getting Started section and take a look at the
example AsciiDoc *.txt source files in the distribution doc directory.
Plain text is the most universal electronic document format, no matter what computing environment you
use, you can always read and write plain text documentation. But for many applications plain text is not a
viable presentation format. HTML, PDF and roff (roff is used for man pages) are the most widely used
UNIX presentation formats. DocBook is a popular UNIX documentation markup format which can be
translated to HTML, PDF and other presentation formats.
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, man page, HTML and other presentation formats.
The AsciiDoc format is a useful presentation format in its own right: AsciiDoc files are unencumbered by
markup and are easily viewed, proofed and edited.
AsciiDoc 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 Example AsciiDoc Documents below.
You write an AsciiDoc document the same way you would write a normal text document, there are no
markup tags or arcane notations. Built-in AsciiDoc formatting rules have been kept to a minimum and are
reasonably obvious.
Text markup conventions tend to be a matter of (often strong) personal preference: if the default syntax is
not to your liking you can define your own by editing the text based asciidoc(1) configuration files.
You can create your own configuration files to translate AsciiDoc documents to almost any SGML/XML
markup.
comes with a set of configuration files to translate AsciiDoc articles, books or man pages to
HTML or DocBook backend formats.
asciidoc(1)
My AsciiDoc Itch
DocBook has emerged as the defacto standard Open Source documentation format. But DocBook
is a complex language, the marked up text is difficult to read and even more difficult to write
directly — I found I was spending more time typing markup tags, consulting reference manuals
and fixing syntax errors, than I was writing the documentation.
Getting Started
4