ASCIIdoc is an extensive Python script that takes simple text files and
converts them into other formats. Three document types are supported.
article (the default)
book
manpage
ASCIIdoc uses .txt files by default.
The default output of ASCIIdoc is an HTML file (xhtml11).
The document types supported by ASCIIdoc are:
article - short documents, articles, and general documentation
book - similar to articles, but include level 0 book part sections
manpage - used to generate UNIX manual pages
Man pages are created by converting the ASCIIdoc text files to DocBook
refentry files, and then to standard roff man pages.
ASCIIdoc uses backend configuration files to output:
DocBook XML (docbook)
XHTML 1.1 with CCS2 (xhtml11; the default)
HTML 4.01 - unstyled (html4)
linuxdoc (no longer actively supported)
The backend configurations are called using the -b option.
Other tools can convert the docbook output ( -b docbook ) to:
PostScript
HTML
PDF
DVI
roff (man page source)
HTMLHelp
JavaHelp
text
etc.
ASCIIdoc has a DocBook Toolchain wrapper called a2x. You will need xsltproc,
DocBook XSL stylesheets, and optionally FOP (for PDF output) or lynx (for text
output) to benefit from its abilities, but it makes conversion very easy.
As an example:
a2x -f pdf .txt
xslfproc is in /usr/bin on OpenSolaris. FOP must be downloaded from the
Apache site (http://xml.apache.org/fop/) and installed.
gunzip fop-0.20.5-bin.tar.gz
tar xf fop-0.20.5-bin.tar
cd fop-0.20.5
cp fop.sh ../bin/
vi ~/bin/fop.sh
Set FOP_HOME
cd
ln -s fop-0.20.5 fop
unzip jimi1_0.zip
cd Jimi
unzip JimiProClasses.zip
cp ./examples/AppletDemo/JimiProClasses.jar ../fop-0.20.5/lib/
export JAVA_HOME=/usr/j2se
(I currently get an error "Exception in thread "main"
java.lang.NoClassDefFoundError: org/apache/fop/apps/Fop" using fop.)
You can use the -verbose switch to see the executed toolchain commands.
Formatting rules for the text file are fairly straight-forward though
there are a large number of "tags" used. The tags are much simpler than
HTML or XML tags; the purpose of ASCIIdoc is to let you concentrate on
text entry, not on tag entry and formatting.
Formatting text follows simple rules.
Emphasized text is enclosed in single quotes: 'emphasized'
Strong text (usually bold) in enclosed in asterisks: *strong*
Monospaced text is enclosed in backtick characters: `monospaced`
Quoted text is enclosed in doublee-quotes: "quoted"
- quoted text must not be flanked by alphanumeric characters
- quoting cannot be overlapped
- different quoting types can be nested
- to suppress quoted text formatting, place a backslash character before
the leading quote character(s). In the case of ambiguity between escaped
and non-escaped text you will need to escape both leading and trailing
quotes, in the case of multi-character quotes you may even need to escape
individual characters.
Put carets on either side of text to be superscripted: ^super^
Put tildes on either side of text to be subscripted: ~sub~
By default, tabs are replaced by 8 spaces. This can be over-ridden.
The following replacements are defined in the default AsciiDoc configuration:
(C) copyright, (TM) trademark, (R) registered trademark, ~-- em dash,
... ellipsis.
Line breaks (HTML/XHTML) are forced by a space followed by the "+" character
at the end of a line.
Rulers (HTML/XHTML) are generated by a line of three or more apostrophe
characters.
Headers consist of titles, equal signs, an author line, and a date line,
like this:
This Is A Title
{{{===============}}}
John Doe
v0.1 April 2006
There are five regular section levels supported. Book documents can have
level 0 sections; all documents can have level 1 through 4 sections.
Section levels are delineated by the section titles, which can either be
one-line or two-line titles:
One Line:
The number of equals signs (=) indicate the section level:
= Document Title (level 0)
== Section Title (level 1)
=== Section Title (level 2)
==== Section Title (level 3)
===== Section Title (level 4)
Two Lines:
Two-line titles consist of a title line (starting against the left margin),
and an underline. Section underlines consist of different underline
characters spanning the width of the title line:
=== Level 0 (top)
~--- Level 1
~~~ Level 2
^^^ Level 3
+++ Level 4
Paragraphs are delimited by a blank line, the end of the file, or the start
of a DelimitedBlock.
ASCIIdoc supports a wide range of other formatting codes, such as numerous
block styles, lists, paragrasph styles, callouts, and on and on. For all of
the features and codes, read the main manual that comes with the package
~--chances are that what you need is already there.
For working examples see the article.txt and book.txt documents in the
AsciiDoc ./doc distribution directory.
The asciidoc(1) command has a ~--help option which prints help topics to
stdout. The default topic summarizes asciidoc(1) usage:
$ asciidoc ~--help
To print a list of help topics:
$ asciidoc ~--help=3Dtopics
To print a help topic specify the topic name as a command argument.
Examples:
$ asciidoc ~--help=3Dmanpage
$ asciidoc ~--help=3Dsyntax
Here is a rundown of some of the more common items you may need.
AsciiDoc can process UTF-8 character sets but there are some things you
need to be aware of:
* Admonition captions, example block title prefixes, table title prefixes
and image block title prefixes default to English. You can customise
these captions and prefixes with the caption attribute. Alternatively
you could override the related AsciiDoc configuration file entries with
a custom configuration file.
Note: The caption attribute only applies if you are using the xhtml11
or html4 backends - if you are going the DocBook route you will
need to configure the XSL Stylesheets for your language.
* Some character sets display double-width characters (for example
Japanese). As far as title underlines are concerned they should be
treated as single character. If you think this looks untidy so you may
prefer to use the single line title format.
ListingBlocks are rendered verbatim in a monospaced font, they retain line
and whitespace formatting and AsciiDoc User Guide often distinguished by a
background or border. There is no text formatting or substitutions within
Listing blocks apart from Special Characters and Callouts. Listing blocks
are often used for code and file listings.
Here's an example:
~--------------------------------------
#include
int main() {
printf("Hello World!\n");
exit(0);
}
~--------------------------------------
A sidebar is a short piece of text presented outside the narrative flow of
the main text. The sidebar is normally presented inside a bordered box to
set it apart from the main text.
The sidebar body is treated like a normal section body.
Here's an example:
An Example Sidebar
************************************************
Any AsciiDoc SectionBody element (apart from
SidebarBlocks) can be placed inside a sidebar.
************************************************
The contents of CommentBlocks are not processed; they are useful for
annotations and for excluding new or outdated content that you don't want
displayed. Here's an example:
//////////////////////////////////////////
CommentBlock contents are not processed by
asciidoc(1).
//////////////////////////////////////////
ExampleBlocks encapsulate the DocBook Example element and are used for,
well, examples. Example blocks can be titled by preceding them with a
BlockTitle. DocBook toolchains normally number examples and generate a
List of Examples backmatter section.
Example blocks are delimited by lines of equals characters and you can put
any block elements apart from Titles, BlockTitles and Sidebars) inside an
example block. For example:
An example
{{{=======================================================================}}}
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.
{{{=======================================================================}}}
The ExampleBlock definition includes a set of admonition styles (NOTE, TIP,
IMPORTANT, WARNING, CAUTION) for generating admonition blocks (admonitions
containing more than just a simple paragraph). Just precede the ExampleBlock
with an attribute list containing the admonition style name. For example:
[NOTE]
A NOTE block
{{{=======================================================================}}}
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.
Fusce euismod commodo velit.
Vivamus fringilla mi eu lacus.
. Fusce euismod commodo velit.
. Vivamus fringilla mi eu lacus.
Donec eget arcu bibendum
nunc consequat lobortis.
{{{=======================================================================}}}
Bulleted list items start with a dash or an asterisk followed by a space or
tab character. Bulleted list
syntaxes are:
- List item.
* List item.
Numbered list items start with an optional number or letter followed by a
period followed by a space or tab character. List numbering is optional.
Numbered list syntaxes are:
Integer numbered list item.
1. Integer numbered list item with optional numbering.
. Lowercase letter numbered list item.
a. Lowercase letter numbered list item with optional numbering.
AsciiDoc comes pre-configured with a labeled list (:- label delimiter) for
generating DocBook glossary lists. Example:
A glossary term:-
The corresponding definition.
A second glossary term:-
The corresponding definition.
AsciiDoc comes with a predefined itemized list (+ item bullet) for
generating bibliography entries.
Example:
+ [[[taoup]]] Eric Steven Raymond. 'The Art of UNIX Programming'.
Addison-Wesley. ISBN 0-13-142901-9.
+ [[[walsh-muellner]]] Norman Walsh & Leonard Muellner. 'DocBook - The
Definitive Guide'. O'Reilly & Associates. 1999. ISBN 1-56592-580-7.
The [[[]]] syntax is a bibliography entry anchor, it generates
an anchor named and additionally displays [] at
the anchor position. For example
[[[taoup]]] generates an anchor named taoup that displays [taoup] at the
anchor position. Cite the reference from elsewhere your document using
<>, this displays a hyperlink ([taoup]) to the corresponding
bibliography entry anchor.
The shipped AsciiDoc configuration includes the footnote:[] inline
macro for generating footnotes. The footnote text can span multiple lines.
Example footnote:
A footnote footnote:[An example footnote.]
Footnotes are primarily useful when generating DocBook output -
DocBook conversion programs render footnote outside the primary text flow.
The shipped AsciiDoc configuration includes the inline macros for generating
document index entries.
indexterm:[,,] ,
++,,++ ,
This inline macro generates an index term (the and
attributes are optional).
For example indexterm:[Tigers,Big cats] (or, using the alternative syntax
++Tigers,Big cats++. Index terms that have secondary and tertiary entries
also generate separate index terms for the secondary and tertiary entries.
The index terms appear in the index, not the primary text flow.
indexterm2:[] , ++ ,
This inline macro generates an index term that appears in both the index and
the primary text flow.
The should not be padded to the left or right with white space
characters.
Two AsciiDoc inline macros are provided for creating hypertext links within
an AsciiDoc document. You can use either the standard macro syntax or the
(preferred) alternative.
anchor
Used to specify hypertext link targets:
[[,]]
anchor:[]
The is a unique identifier that must begin with a letter. The optional
is the text to be displayed by captionless xref macros that refer
to this anchor. The optional is only really useful when
generating DocBook output. Example anchor:
[[X1]]
You may have noticed that the syntax of this inline element is the same as
that of the BlockId block element, this is no coincidence since they are
functionally equivalent.
xref
Creates a hypertext link to a document anchor.
<<,>>
xref:[]
The refers to an existing anchor . The optional is the
link's displayed text. If is not specified then the , enclosed
in square brackets, is displayed. Example:
<>
Inline images are inserted into the output document using the image macro.
The inline syntax is:
image:[]
The contents of the image file is displayed. To display the image
it's file format must be supported by the target backend application. HTML
and DocBook applications normally support PNG or JPG files.
file name paths are relative to the location of the referring
document.
Tables are the most complex AsciiDoc elements; read the (long) Tables
section in the main document. AsciiDoc generates nice HTML tables, but the
current crop of DocBook toolchains render tables with varying degrees of
success. Use tables only when really necessary.
MANPAGE DOCUMENTS
Sooner or later, you may need to write a man page. By observing a couple
of additional conventions you can compose AsciiDoc files that will translate
to a DocBook refentry (man page) document. The resulting DocBook file can
then be translated to the native roff man page format (or other formats).
For example, the asciidoc.1.txt file in the AsciiDoc distribution ./doc
directory was used to generate both the asciidoc.1.css-embedded.html HTML
file the asciidoc.1 roff formatted asciidoc(1) man page.
Document Header
A document Header is mandatory. The title line contains the man page
name followed immediately by the manual section number in brackets, for
example ASCIIDOC(1). The title name should not contain white space and
the manual section number is a single digit optionally followed by a
single character.
The NAME Section
The first manpage section is mandatory, must be titled NAME and must
contain a single paragraph (usually a single line) consisting of a list
of one or more comma separated command name(s) separated from the command
purpose by a dash character. The dash must have at least one white space
character on either side. For example:
printf, fprintf, sprintf - print formatted output
The SYNOPSIS Section
The second manpage section is mandatory and must be titled SYNOPSIS.
