1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
|
AsciiDoc Home Page
==================
.{date}: AsciiDoc {revision} Released
************************************************************************
Additions and change in this release include:
- Up to 250% faster than previous release (precompiled regular
expression optimization).
- Bulleted lists can now be nested up to six deep with the addition of
two, three, four and five asterisk bullet syntaxes.
- Implicitly numbered lists can now be nested up to six deep with the
addition of two, three, four and five period character syntaxes.
- Labeled lists can now be nested up to four deep with the addition of
three and four colon syntaxes.
Plus a number of smaller additions along with the usual documentation
polishing. Read the link:CHANGELOG.html[CHANGELOG] for a full list of
all additions and changes.
One final note: if you are upgrading from version 8.2.7 or less please
read about possible link:CHANGELOG.html#X1[compatibility issues]
first.
mailto:srackham@gmail.com['Stuart Rackham']
************************************************************************
Introduction
------------
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.
TIP: The pages you are reading were written using AsciiDoc, to view
the corresponding AsciiDoc source click on the *Page Source* menu item
in the left hand margin.
Overview and Examples
---------------------
You write an AsciiDoc document the same way you would write a
normal text document, there are no markup tags or weird format
notations. AsciiDoc files are designed to be viewed, edited and
printed directly or translated to other presentation formats using
the asciidoc(1) command.
The asciidoc(1) command translates AsciiDoc files to HTML, XHTML and
DocBook markups. DocBook can be post-processed to presentation
formats such as HTML, PDF, DVI, LaTeX, roff, and Postscript using
readily available Open Source tools.
Example Articles
~~~~~~~~~~~~~~~~
- This version of the
link:asciidoc.css-embedded.html[AsciiDoc User Guide]
was generated by AsciiDoc from
link:asciidoc.txt[this AsciiDoc file].
- Here's the link:asciidoc.html[same document] created by first
generating DocBook markup using AsciiDoc and then converting the
DocBook markup to HTML using 'DocBook XSL Stylesheets'.
- The User Guide again, this time a
link:chunked/index.html[chunked version].
- This link:article.txt[AsciiDoc article template] produced
this link:article.html[HTML file] and this
link:article.pdf[PDF file] via DocBook markup generated by AsciiDoc.
- This link:asciidoc.pdf[PDF formatted User Guide] was generated from
asciidoc(1) DocBook output.
Example Books
~~~~~~~~~~~~~
AsciiDoc markup supports all the standard DocBook frontmatter and
backmatter sections (dedication, preface, bibliography, glossary,
index, colophon) plus footnotes and index entries.
Book::
This link:book.txt[AsciiDoc book's] DocBook output
produced link:book.html[this HTML file] using the
'DocBook XSL Stylesheets'.
Multi-part book::
This link:book-multi.txt[multi-part AsciiDoc book's]
DocBook output produced link:book-multi.html[this HTML file]
using the 'DocBook XSL Stylesheets'.
Example UNIX Man Pages
~~~~~~~~~~~~~~~~~~~~~~
HTML formatted AsciiDoc man pages
link:asciidoc.1.css-embedded.html[with stylesheets] and
link:asciidoc.1.html[without stylesheets] were generated by AsciiDoc
from link:asciidoc.1.txt[this file].
This link:asciidoc.1[roff formatted man page] was generated from
asciidoc(1) DocBook output using `xsltproc(1)` and DocBook XSL
Stylesheets.
Example Web Site
~~~~~~~~~~~~~~~~
The link:README-website.html[AsciiDoc website] is included in the
AsciiDoc distribution (in `./examples/website/`) as example website
built using AsciiDoc. See `./examples/website/README-website.txt`.
More examples
~~~~~~~~~~~~~
- link:newtables.html[Tables].
//- link:newlists.html[Lists].
Music Filter
------------
A link:music-filter.html[music filter] is included in the distribution
`./filters/` directory. It translates music in
http://lilypond.org/[LilyPond] or http://abcnotation.org.uk/[ABC]
notation to standard classical notation
Source Code Highlight Filter
----------------------------
A link:source-highlight-filter.html[source code highlight filter] is
included in the distribution `./filters/` directory.
[[X4]]
Graphviz Filter
---------------
Gouichi Iisaka has written a http://www.graphviz.org/[Graphviz] filter
for AsciiDoc. Graphviz generates diagrams from a textual
specification. Gouichi Iisaka's Graphviz filter is included in the
AsciiDoc distribution. Here are some
link:asciidoc-graphviz-sample.html[AsciiDoc Graphviz examples].
[[X3]]
Mathematical Formulae
---------------------
You can include mathematical formulae in AsciiDoc XHTML documents using
link:asciimathml.html[ASCIIMathML] or link:latexmathml.html[LaTeXMathML]
notation.
link:latexmath.pdf[LaTeX Math] can be included in AsciiDoc
documents processed by `dblatex(1)`.
Vim Syntax Highlighter
----------------------
An AsciiDoc syntax highlighter for the Vim text editor is included in
the AsciiDoc distribution (see 'Appendix F' of the 'AsciiDoc User
Guide' for details).
.Syntax highlighter screenshot
image::images/highlighter.png[height=250,caption="",link="images/highlighter.png"]
Dag Wieers has implemented an alternative Vim syntax file for AsciiDoc
which can be found here
http://svn.rpmforge.net/svn/trunk/tools/asciidoc-vim/.
[[X2]]
Resources
---------
- Check the link:downloads.html[Downloads page] for packaged versions
of AsciiDoc.
- Alex Efros has written an HTML formatted
http://powerman.name/doc/asciidoc[AsciiDoc Cheatsheet] using
Asciidoc.
- Thomas Berker has written an
http://liksom.info/blog/?q=node/114[AsciiDoc Cheatsheet] in Open
Document and PDF formats.
- The http://www.wikimatrix.org/[WikiMatrix] website has an excellent
http://www.wikimatrix.org/syntax.php[web page] that compares the
various Wiki markup syntaxes. An interesting attempt at Wiki markup
standardization is http://www.wikicreole.org/[CREOLE].
- Terrence Brannon has written
http://static.livingcosmos.org/domains/com/metaperl/www/asciidoc-el/[AsciiDoc
functions for Emacs].
- The http://xpt.sourceforge.net/[*Nix Power Tools project] has
released an http://xpt.sourceforge.net/tools/doc-mode/[AsciiDoc
syntax highlighter for Emacs].
- Franck Pommereau has written
http://www.univ-paris12.fr/lacl/pommereau/soft/asciidoctest.html[Asciidoctest],
a program that doctests snippets of Python code within your Asciidoc
documents.
- The http://remips.sourceforge.net/[ReMIPS] project website has been
built using AsciiDoc.
- Here are some link:asciidoc-docbook-xsl.html[DocBook XSL Stylesheets
Notes].
- Karl Mowatt-Wilson has developed an http://ikiwiki.info/[ikiwiki]
plugin for AsciiDoc which he uses to render
http://mowson.org/karl[his website]. The plugin is available
http://www.mowson.org/karl/colophon/[here] and there is some
discussion of the ikiwiki integration
http://ikiwiki.info/users/KarlMW/discussion/[here].
Blogpost weblog client
----------------------
http://srackham.wordpress.com/blogpost-readme/[blogpost] is a
command-line weblog client for publishing AsciiDoc documents to
http://wordpress.org/[WordPress] blog hosts. It creates and updates
weblog posts and pages directly from AsciiDoc source documents.
[[X1]]
LaTeX Backend
-------------
An experimental LaTeX backend has been written for AsciiDoc by
Benjamin Klum. Benjamin has done a superhuman job (I admit it, I
didn't think this was doable due to AsciiDoc's SGML/XML bias).
Here's link:latex-backend.html[Benjamin's documentation].
NOTE: Owning to to other commitments, Benjamin is unable to maintain
this backend. I don't have the expertise or time to take this on
consequently the LaTeX backend has not been tested or updated since
AsciiDoc version 8.2.7 and is currently unsupported.
Projects using AsciiDoc
-----------------------
Here are some projects I know of, if you know of more drop me a line
and I'll add them to the list.
- The Linux kernel
http://www.kernel.org/pub/software/scm/git/docs/git.html[git source
code management system].
- Some documentation about git by Nico Schottelius (in German)
http://nico.schotteli.us/papers/linux/git-firmen/.
- The http://www.netpromi.com/kirbybase_ruby.html[KirbyBase for Ruby]
database management system manual.
- The http://www.selenic.com/mercurial/[Mercurial distributed SCM]
uses asciidoc for its man pages.
- Pascal Rapaz has written a Python script to automate AsciiDoc
website generation. You can find it at
http://www.rapazp.ch/opensource/tools/asciidoc.html.
- The http://xpt.sourceforge.net/[*Nix Power Tools project] uses
AsciiDoc for documentation and has released an Emacs syntax
highlighter (see <<X2,Resources>> above).
- The http://www.wesnoth.org/[Battle for Wesnoth] project uses
AsciiDoc for it's http://www.wesnoth.org/wiki/WesnothManual[Manual]
in a number of different languages.
- Troy Hanson uses AsciiDoc to generate user guides for the
http://tpl.sourceforge.net/[tpl] and
http://uthash.sourceforge.net/[uthash] projects (the HTML versions
have a customised contents sidebar).
- Jared Henley has written
http://jared.henley.id.au/software/awb/documentation.html[AsciiDoc
Website Builder]. 'AsciiDoc Website Builder' (awb) is a python
program that automates the building of of a website written in
AsciiDoc. All you need to write is the AsciiDoc source plus a few
simple configuration files.
AsciiDoc version 9
-----------------
The next version of AsciiDoc is underway -- details
link:version9.html[here].
|
