AsciiDoc User Guide

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 it's 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.

asciidoc(1) comes with a set of configuration files to translate AsciiDoc articles, books or man pages to HTML or DocBook backend formats.

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 far to much time typing markup tags, consulting reference manuals and fixing syntax errors than actually writing the documentation.

Getting Started

AsciiDoc is written in Python so you need a Python interpreter (version 2.3 or later) to execute asciidoc(1). Python is installed by default in most Linux distributions. You can download Python from the official Python website http://www.python.org.

Prepackaged AsciiDoc Distributions

4