ASCIIdocs Quick Start Guide at OpenSolaris.org

You are not signed in. or register.

>> xref:[
Community: Documentation Current Documentation Quick Start Doc List Big Doc List Reference Information Build, Install, Patch, and Upgrade Documentation System Administration Documentation Developer Documentation Articles Hardware Documentation OpenSolaris Documentation Understanding Modern Operating Systems Security Documentation Storage Administration Documentation Examples University Curriculum Tools FAQs Doc Downloads Book Title Matrix How To Participate Doc Roadmap Doc Reviews chapter1 figures chapter2 figures chapter3 Persistent Links to Man Pages Doc Plan: Dual-Boot OpenSolaris DP2 with a Second Operating System Dual-Booting OpenSolaris DP2 with Ubuntu Linux Dual-Booting OpenSolaris with Ubuntu Linux: Preparing & Backing Up Your Hard Drive Dual-Booting OpenSolaris with Linux: Creating a New Partition Dual-Booting OpenSolaris with Linux: Installing OpenSolaris on the New Partition Dual-Booting OpenSolaris DP2 with Vista Dual-Booting OpenSolaris with Vista: Preparing Your Hard Drive Dual-Booting OpenSolaris with Vista: Backing Up Your Hard Drive Dual-Booting OpenSolaris with Vista: Creating a New Partition Dual-Booting OpenSolaris with Vista: Installing OpenSolaris on the New Partition Contributor Resources Documentation Style Guide for OpenSolaris Sun Global Glossary XML Templates XMLmind Add-on For SolBook XML Documentation Tools ASCIIdocs Quick Start Guide DocTools Tutorial Man Page Guidelines Docs Wiki OpenSolaris Documentation License Information Discussions Announcements Blogs Files Leaders News Events Observers New-to-Solaris FAQ Documentation Source Package Management Comparison Learning Materials for Users More About OpenSolaris Multimedia Printing Virtualization Administration	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. <<,

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.