AsciiDoc User Guide

	Stuart Rackham <[e-mail]>
	Revision History
Revision 7.1.2	7 March 2006	SJR

Table of Contents
Introduction ..........................................................................................................................................	3
Getting Started .....................................................................................................................................	4
Installing the AsciiDoc tarball distribution ..................................................................................	5
Example AsciiDoc Documents ....................................................................................................	5
AsciiDoc Document Types ..................................................................................................................	5
article ............................................................................................................................................	5
book ..............................................................................................................................................	6
manpage .......................................................................................................................................	6
AsciiDoc Backends ..............................................................................................................................	6
docbook ........................................................................................................................................	6
xhtml11 ........................................................................................................................................	7
html4 ............................................................................................................................................	8
linuxdoc ........................................................................................................................................	8
Document Structure .............................................................................................................................	9
Block Elements ............................................................................................................................	9
Header ........................................................................................................................................	10
Preamble ....................................................................................................................................	11
Sections ......................................................................................................................................	11
Inline Elements ..........................................................................................................................	12
Document Processing .........................................................................................................................	12
Text Formatting .................................................................................................................................	13
Quoted Text ...............................................................................................................................	13
Inline Passthroughs ....................................................................................................................	14
Superscripts and Subscripts .......................................................................................................	14
Line Breaks (HTML/XHTML) ..................................................................................................	15
Rulers (HTML/XHTML) ...........................................................................................................	15
Tabs ............................................................................................................................................	15
Replacements .............................................................................................................................	15
Special Words ............................................................................................................................	15
Titles ..................................................................................................................................................	15
Two line titles ............................................................................................................................	16
One line titles .............................................................................................................................	16
BlockTitles .........................................................................................................................................	16
BlockId Element ................................................................................................................................	17
Paragraphs ..........................................................................................................................................	17
Default Paragraph ......................................................................................................................	17
Literal Paragraph ........................................................................................................................	17
Admonition Paragraphs .............................................................................................................	18
Delimited Blocks ...............................................................................................................................	19
Predefined Delimited Blocks .....................................................................................................	19
Listing Blocks ............................................................................................................................	19

1

AsciiDoc User Guide
Literal Blocks .............................................................................................................................	20
SidebarBlocks ............................................................................................................................	21
Comment Blocks ........................................................................................................................	21
Passthrough Blocks ....................................................................................................................	21
Quote Blocks ..............................................................................................................................	22
Example Blocks .........................................................................................................................	22
Admonition Blocks ....................................................................................................................	23
Lists ....................................................................................................................................................	24
Bulleted and Numbered Lists .....................................................................................................	24
Vertical Labeled Lists ................................................................................................................	26
Horizontal Labeled Lists ............................................................................................................	27
Question and Answer Lists ........................................................................................................	28
Glossary Lists .............................................................................................................................	28
Bibliography Lists ......................................................................................................................	29
List Item Continuation ...............................................................................................................	29
List Block ...................................................................................................................................	30
Footnotes ............................................................................................................................................	31
Indexes ...............................................................................................................................................	31
Callouts ..............................................................................................................................................	32
Implementation Notes ................................................................................................................	33
Macros ................................................................................................................................................	34
Inline Macros .............................................................................................................................	34
Block Macros .............................................................................................................................	36
System Macros ...........................................................................................................................	37
Macro Definitions ......................................................................................................................	39
Tables .................................................................................................................................................	40
Example Tables ..........................................................................................................................	40
AsciiDoc Table Block Elements ................................................................................................	42
Manpage Documents .........................................................................................................................	45
Document Header ......................................................................................................................	46
The NAME Section ....................................................................................................................	46
The SYNOPSIS Section ............................................................................................................	46
Configuration Files ............................................................................................................................	46
Configuration File Format .........................................................................................................	46
Markup Template Sections ........................................................................................................	47
Special Sections .........................................................................................................................	47
Configuration File Names and Locations ..................................................................................	52
Document Attributes ..........................................................................................................................	54
Attribute Entries .................................................................................................................................	54
Attribute Lists ....................................................................................................................................	56
Macro Attribute lists ..................................................................................................................	56
AttributeList Element .................................................................................................................	57
Attribute References ..........................................................................................................................	57
Simple Attributes References ....................................................................................................	57
Conditional Attribute References ..............................................................................................	57
System Attribute References ......................................................................................................	58
Intrinsic Attributes .............................................................................................................................	59
Block Element Definitions .................................................................................................................	60
Styles ..........................................................................................................................................	62
Paragraphs ..................................................................................................................................	62
Delimited Blocks .......................................................................................................................	63
Lists ............................................................................................................................................	63
Tables .........................................................................................................................................	64
Filters .................................................................................................................................................	65

2

AsciiDoc User Guide
Filter Search Paths .....................................................................................................................	65
Filter Configuration Files ...........................................................................................................	66
Code Filter .................................................................................................................................	66
Converting DocBook to other file formats ........................................................................................	67
a2x Toolchain Wrapper ..............................................................................................................	68
Toolchain Components ..............................................................................................................	68
AsciiDoc DocBook XSL Drivers ...............................................................................................	69
FOP ............................................................................................................................................	70
Generating Plain Text Files ...............................................................................................................	70
XML and Character Sets ....................................................................................................................	70
PDF Fonts ..................................................................................................................................	71
Help Commands .................................................................................................................................	71
Customizing Help ......................................................................................................................	71
Tips and Tricks ..................................................................................................................................	71
Know Your Editor ......................................................................................................................	71
Vim Commands for Formatting AsciiDoc .................................................................................	71
Troubleshooting .........................................................................................................................	73
Gotchas ......................................................................................................................................	73
Combining Separate Documents ................................................................................................	74
Processing Document Sections Separately ................................................................................	75
Processing Document Chunks ...................................................................................................	75
Badges in HTML Page Footers ..................................................................................................	76
Pretty Printing AsciiDoc Output ................................................................................................	76
Supporting Minor DocBook DTD Variations ............................................................................	76
Shipping Stand-alone AsciiDoc Source .....................................................................................	76
Inserting Blank Space ................................................................................................................	77
Closing Open Sections ...............................................................................................................	77
Validating Output Files ..............................................................................................................	77
Glossary .............................................................................................................................................	77
A. Migration Notes ............................................................................................................................	78
Version 6 to version 7 ................................................................................................................	78
B. Packager Notes ..............................................................................................................................	79
C. AsciiDoc Safe Mode .....................................................................................................................	79
D. Installing FOP on Windows ..........................................................................................................	80
E. Installing FOP on Linux ................................................................................................................	81
F. Installing Java on Windows ...........................................................................................................	81
G. Installing Java on Linux ................................................................................................................	82
H. Using AsciiDoc with non-English Languages ..............................................................................	83
I. ASCIIMathML Support ..................................................................................................................	83

AsciiDoc is a text document format for writing short documents, articles, books and UNIX man pages. AsciiDoc files can be translated to HTML and DocBook markups using the asciidoc(1) command. 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.

Introduction

This is an overly large document, it probably needs to be refactored into a Tutorial, FAQ, Quick Reference and Formal Reference.

3