Beruflich Dokumente
Kultur Dokumente
ii
REVISION HISTORY
NUMBER
DATE
DESCRIPTION
NAME
iii
Contents
Introduction
2.1
Example Articles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2
Example Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3
2.4
Example Slideshows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5
2.6
More examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
eBook Publication
Mathematical Formulae
Editor Support
10
11
13
15
12 LaTeX Backend
16
17
Read the CHANGELOG for release highlights and a full list of all additions, changes and bug fixes. Changes are documented in the updated User Guide. See the Installation page for downloads and and installation instructions.
Stuart Rackham
iv
1 / 17
Chapter 1
Introduction
AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages
and blogs. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page.
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.
AsciiDoc is free software and is licenced under the terms of the GNU General Public License version 2 (GPLv2).
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.
2 / 17
Chapter 2
2.1
Example Articles
This XHTML version of the AsciiDoc User Guide was generated by AsciiDoc from this AsciiDoc file.
Heres the 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 chunked version.
AsciiDoc generated this stand-alone HTML file containing embedded CSS, JavaScript and images from this AsciiDoc article
template with this command:
asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt
The same AsciiDoc article template generated this HTML 5 (the toc2 attribute puts a table of contents in the left margin) from
this command:
asciidoc -b html5 -a icons -a toc2 -a theme=flask article.txt
The same AsciiDoc article template produced this HTML file and this PDF file via DocBook markup generated by AsciiDoc.
2.2
Example Books
AsciiDoc markup supports all the standard DocBook frontmatter and backmatter sections (dedication, preface, bibliography,
glossary, index, colophon) plus footnotes and index entries.
This AsciiDoc book produced this HTML file using the DocBook XSL Stylesheets.
The PDF formatted AsciiDoc User Guide was generated from asciidoc(1) DocBook output.
The EPUB formatted AsciiDoc User Guide was generated using a2x.
This EPUB formatted book skeleton was generated using a2x.
This multi-part AsciiDoc book produced this HTML file using the DocBook XSL Stylesheets.
2.3
3 / 17
HTML formatted AsciiDoc man pages with stylesheets and without stylesheets were generated by AsciiDoc from this file.
This roff formatted man page was generated from asciidoc(1) DocBook output using xsltproc(1) and DocBook XSL
Stylesheets.
2.4
Example Slideshows
The Slidy backend generates HTML slideshows that can be viewed in any web browser. Whats nice is that you can create
completely self contained slideshows including embedded images.
Here is the slidy backend documentation slideshow and here is its AsciiDoc source.
An example slidy slideshow and the AsciiDoc source.
2.5
The AsciiDoc website is included in the AsciiDoc distribution (in ./examples/website/) as an example website built using
AsciiDoc. See ./examples/website/README-website.txt.
2.6
More examples
4 / 17
Chapter 3
eBook Publication
The two most popular open eBook formats are EPUB and PDF. The AsciiDoc a2x toolchain wrapper makes it easy to publish
EPUB and PDF eBooks with AsciiDoc. See also example books and AsciiDoc EPUB Notes).
5 / 17
Chapter 4
6 / 17
Chapter 5
7 / 17
Chapter 6
Mathematical Formulae
You can include mathematical formulae in AsciiDoc XHTML documents using ASCIIMathML or LaTeXMathML notation.
The AsciiDoc LaTeX filter translates LaTeX source to an image that is automatically inserted into the AsciiDoc output documents.
AsciiDoc also has latexmath macros for DocBook outputs they are documented in this PDF file and can be used in AsciiDoc
documents processed by dblatex(1).
8 / 17
Chapter 7
Editor Support
An AsciiDoc syntax highlighter for the Vim text editor is included in the AsciiDoc distribution (see the Vim Syntax Highlighter
appendix in the AsciiDoc User Guide for details).
9 / 17
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/.
David Avsajanishvili has written a source highlighter for AsciiDoc files for GtkSourceView (used by gedit and a number of
other applications). The project is hosted here: https://launchpad.net/asciidoc-gtk-highlight
AsciiDoc resources for the Emacs editor can be found on the AsciiDoc page at the Emacs Wiki.
Christian Zuckschwerdt has written a TextMate bundle for AsciiDoc.
10 / 17
Chapter 8
Andrew Koster has written a Web based application to interactively convert and display AsciiDoc source: http://andrewk.webfactional.com
asciidoc.php
11 / 17
Chapter 9
12 / 17
Dag Wieers has written UNOCONV. UNOCONV can export AsciiDoc outputs to OpenOffice export formats.
Ed Keith has written Code Extractor, it extracts code snippets from source code files and inserts them into AsciiDoc documents.
The JMI website hosts a number of extras for AsciiDoc and Slidy written by Jean-Michel Inglebert.
Ryan Tomayko has written an number of themes for AsciiDoc along with a script for combining the CSS files into single CSS
theme files for AsciiDoc embedded CSS documents.
Ilya Portnov has written a document building system for AsciiDoc, here is short article in Russian describing it.
Lex Trotman has written codiicsa, a program that converts DocBook to AsciiDoc.
Qingping Hou has written an AsciiDoc backend for deck.js. deck.js is a JavaScript library for building modern HTML presentations (slideshows).
The guys from OReilly Media have posted an XSL Stylesheet to github that converts DocBook to AsciiDoc.
Lex Trotman has written flexndex, an index generator tool that be used with AsciiDoc.
Michael Haberler has created a blockdiag filter for Asciidoc which embeds blockdiag images in AsciiDoc documents.
Dan Allen has written a Bootstrap backend for AsciiDoc.
Steven Boscarine has written Maven wrapper for AsciiDoc.
Christian Goltz has written Shaape, an Ascii art to image converter for AsciiDoc.
Eduardo Santana has written an Asciidoc Highlight for Notepad++.
Geany 1.23 adds document structure support for AsciiDoc.
Please let me know if any of these links need updating.
13 / 17
Chapter 10
14 / 17
The Battle for Wesnoth project uses AsciiDoc for its Manual in a number of different languages.
Troy Hanson uses AsciiDoc to generate user guides for the tpl and uthash projects (the HTML versions have a customised
contents sidebar).
Leonid Volnitskys site is generated using AsciiDoc and includes Leonids matplotlib filter.
WeeChat uses AsciiDoc for project documentation.
Clansuite uses AsciiDoc for project documentation.
The Freecell Solver program uses AsciiDoc for its distributed documentation.
Eric Raymonds AIVDM/AIVDO protocol decoding documentation is written using AsciiDoc.
Dwight Schauer has written an LXC HOWTO in AsciiDoc.
The Free Telephony Project website is generated using AsciiDoc.
Warren Block has posted a number of articles written using AsciiDoc.
The Waf projects Waf Book is written using AsciiDoc, there is an HTML and a PDF version.
The DiffKit projects documentation and website have been written using Asciidoc.
The Network UPS Tools project documentation is an example of a large documentation project written using AsciiDoc.
Pacman, the Arch Linux package manager, has been documented using AsciiDoc.
Suraj Kurapati has written a number of customized manuals for his Open Source projects using AsciiDoc:
http://snk.tuxfamily.org/lib/detest/
http://snk.tuxfamily.org/lib/ember/
http://snk.tuxfamily.org/lib/inochi/
http://snk.tuxfamily.org/lib/rumai/
The CxxTest project (unit testing for C++ language) has written its User Guide using AsciiDoc.
Please let me know if any of these links need updating.
15 / 17
Chapter 11
16 / 17
Chapter 12
LaTeX Backend
An experimental LaTeX backend was written for AsciiDoc in 2006 by Benjamin Klum. Benjamin did a superhuman job (I admit
it, I didnt think this was doable due to AsciiDocs SGML/XML bias). Owning to to other commitments, Benjamin was unable
to maintain this backend. Heres Benjamins original documentation. Incompatibilities introduced after AsciiDoc 8.2.7 broke the
LaTeX backend.
In 2009 Geoff Eddy stepped up and updated the LaTeX backend, thanks to Geoffs efforts it now works with AsciiDoc 8.4.3.
Geoffs updated latex.conf file shipped with AsciiDoc version 8.4.4. The backend still has limitations and remains experimental (see Geoffs notes).
Its probably also worth pointing out that LaTeX output can be generated by passing AsciiDoc generated DocBook through
dblatex(1).
17 / 17
Chapter 13
13.1
Bug reports
When reporting problems please illustrate the problem with the smallest possible example that replicates the issue (and please
test your example before posting). This technique will also help to eliminate red herrings prior to posting.
Paste the commands that you executed along with any relevant outputs.
Include the version of AsciiDoc and the platform youre running it on.
If you can program please consider writing a patch to fix the problem.
13.2
Patches
Keep patches small and atomic (one issue per patch) no patch bombs.
If possible test your patch against the current trunk.
If your patch adds or modifies functionality include a short example that illustrates the changes.
Send patches in diff -u format, inline inside the mail message is usually best; if it is a very long patch then send it as an
attachment.
Include documentation updates if youre up to it; otherwise insert TODO comments at relevant places in the documentation.