AsciiDoc User Guide
The AsciiDoc linuxdoc backend is still distributed but is no longer being actively developed or tested with new AsciiDoc releases (the last supported release was AsciiDoc 6.0.3).
•Tables are not supported.
•Images are not supported.
•Callouts are not supported.
•Horizontal labeled lists are not supported.
•Only article document types are allowed.
•The Abstract section can consist only of a single paragraph.
•An AsciiDoc Preamble is not allowed.
•The LinuxDoc output format does not support multiple labels per labeled list item although LinuxDoc conversion programs generally output all the labels with a warning.
•Don't apply character formatting to the link macro attributes, LinuxDoc does not allow displayed link text to be formatted.
The default output file name extension is .sgml.
Document Structure
An AsciiDoc document consists of a series of block elements starting with an optional document Header, followed by an optional Preamble, followed by zero or more document Sections.
Almost any combination of zero or more elements constitutes a valid AsciiDoc document: documents can range from a single sentence to a multi-part book.
Block Elements
Block elements consist of one or more lines of text and may contain other block elements.
The AsciiDoc block structure can be informally summarized 1 as follows:
Document |
::= (Header?,Preamble?,Section*) |
Header |
::= (Title,(AuthorLine,RevisionLine?)?) |
AuthorLine |
::= (FirstName,(MiddleName?,LastName)?,EmailAddress?) |
RevisionLine |
::= (Revision?,Date) |
Preamble |
::= (SectionBody) |
Section |
::= (Title,SectionBody?,(Section)*) |
SectionBody |
::= ((BlockTitle?,Block)|BlockMacro)+ |
Block |
::= (Paragraph|DelimitedBlock|List|Table) |
List |
::= (BulletedList|NumberedList|LabeledList|CalloutList) |
BulletedList |
::= (ListItem)+ |
NumberedList |
::= (ListItem)+ |
1This is a rough structural guide, not a rigorous syntax definition
9
|
AsciiDoc User Guide |
CalloutList |
::= (ListItem)+ |
LabeledList |
::= (ItemLabel+,ListItem)+ |
ListItem |
::= (ItemText,(List|ListParagraph|ListContinuation)*) |
Table |
::= (Ruler,TableHeader?,TableBody,TableFooter?) |
TableHeader |
::= (TableRow+,TableUnderline) |
TableFooter |
::= (TableRow+,TableUnderline) |
TableBody |
::= (TableRow+,TableUnderline) |
TableRow |
::= (TableData+) |
Where: |
|
•? implies zero or one occurrence, + implies one or more occurrences, * implies zero or more occurrences.
•All block elements are separated by line boundaries.
•BlockId, AttributeEntry and AttributeList block elements (not shown) can occur almost anywhere.
•There are a number of document type and backend specific restrictions imposed on the block syntax.
•The following elements cannot contain blank lines: Header, Title, Paragraph, ItemText.
•A ListParagraph is a Paragraph with it's listelement option set.
•A ListContinuation is a list continuation element.
Header
The Header is optional but must start on the first line of the document and must begin with a document title. Optional Author and Revision lines immediately follow the title.
The author line contains the author's name optionally followed by the author's email address. The author's name consists of a first name followed by optional middle and last names separated by white space. The email address is last and must be enclosed in angle <> brackets. Author names cannot contain angle <> bracket characters.
The optional document header revision line should immediately follow the author line. The revision line can be one of two formats:
1.A an alphanumeric document revision number followed by a date:
•The revision number and date must be separated by a comma.
•The revision number is optional but must contain at least one numeric character.
•Any non-numeric characters preceding the first numeric character will be dropped.
2.An RCS $Id$ marker.
The document heading is separated from the remainder of the document by one or more blank lines.
10