AsciiDoc Home Page
==================

.{revdate}: AsciiDoc {revnumber} Released
************************************************************************
In addition to Vim syntax highlighter improvements this release
contains quite a few (fairly minor) improvements plus a few bug fixes.

Read the link:CHANGELOG.html[CHANGELOG] for a full list of all
additions, changes and bug fixes. Changes are documented in the
updated link:userguide.html[User Guide]. See the
link:INSTALL.html[Installation page] for downloads and and
installation instructions.

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, EPUB, 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].

- AsciiDoc generated this link:article-standalone.html[stand-alone
  HTML file] containing embedded CSS, JavaScript and images from this
  link:article.txt[AsciiDoc article template] with this command:

  asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt

- The same 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.

- This link:article.epub[EPUB formatted article] was generated using
  link:a2x.1.html[a2x].

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
~~~~~~~~~~~~~
- See below: <<X6,'Documents written using AsciiDoc'>>.
- Example link:newtables.html[Tables].


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/.


[[X5]]
matplotlib Filter
-----------------
Leonid Volnitsky has written a
http://volnitsky.com/project/mplw/index.html[matplotlib] filter for
AsciiDoc.  Using this filter you can generate charts from inline
matplotlib scripts.


Try AsciiDoc on the Web
-----------------------
Andrew Koster has written a Web based application to interactively
convert and display AsciiDoc source:
http://andrewk.webfactional.com/asciidoc.php


[[X2]]
Resources
---------
Here are resources that I know of, if you know of more drop me a line
and I'll add them to the list.

- David Avsajanishvili has written a source highlighter for AsciiDoc
  files for http://projects.gnome.org/gtksourceview/[GtkSourceView]
  (used by http://projects.gnome.org/gedit/[gedit] and a number of
  other applications). The project is hosted here:
  https://launchpad.net/asciidoc-gtk-highlight
- Check the link:INSTALL.html#X2[installation 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].
- David Hajage has written an AsciiDoc package for the
  http://www.r-project.org/[R Project] (R is a free software
  environment for statistical computing).  'ascii' is available on
  'CRAN' (just run `install.package("ascii")` from R).  Briefly,
  'ascii' replaces R results in AsciiDoc document with AsciiDoc
  markup.  More information and examples here:
  http://eusebe.github.com/ascii/.
- 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.
- 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.
- Brad Adkins has written
  http://dbixjcl.org/jcl/asciidocgen/asciidocgen.html[AsciiDocGen], a
  web site generation and deployment tool that allows you write your
  web site content in AsciiDoc. The
  http://dbixjcl.org/jcl/asciidocgen/asciidocgen.html[AsciiDocGen web
  site] is managed using 'AsciiDocGen'.
- Filippo Negroni has developed a set of tools to facilitate 'literate
  programming' using AsciiDoc.  The set of tools is called
  http://eweb.sourceforge.net/[eWEB].

Please let me know if any of these links need updating.


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.


[[X6]]
Documents written using AsciiDoc
--------------------------------
Here are some documents I know of, if you know of more drop me a line
and I'll add them to the list.

- The book
  http://oreilly.com/catalog/9780596155957/index.html[Programming
  Scala] by Dean Wampler and Alex Payne (O'Reilly) was
  http://groups.google.com/group/asciidoc/browse_frm/thread/449f1199343f0e27[written
  using Asciidoc].

- The http://www.ncfaculty.net/dogle/fishR/index.html[fishR] website
  has a number of
  http://www.ncfaculty.net/dogle/fishR/bookex/AIFFD/AIFFD.html[book
  examples] written using AsciiDoc.

- http://frugalware.org/[Frugalware Linux] uses AsciiDoc for
  http://frugalware.org/docs[documentation].
- http://www.cherokee-project.com/doc/[Cherokee documentation].

- Henrik Maier produced this professional User manual using AsciiDoc:
  http://www.proconx.com/gcpmg/UMGCPMG-0801.pdf.

- Henrik also produced this folded single page brochure format
  example: http://www.proconx.com/gcpmg/IGGCPMG-0801-up.pdf.
+
See this
http://groups.google.com/group/asciidoc/browse_thread/thread/16ab5a06864b934f[AsciiDoc
discussion group thread] for details.

- The
  http://www.kernel.org/pub/software/scm/git/docs/user-manual.html[Git
  User's Manual].
- 'Git Magic' +
  http://www-cs-students.stanford.edu/~blynn/gitmagic/ +
  http://github.com/blynn/gitmagic/tree/1e5780f658962f8f9b01638059b27275cfda095c
- 'CouchDB: The Definitive Guide' +
  http://books.couchdb.org/relax/ +
  http://groups.google.com/group/asciidoc/browse_thread/thread/a60f67cbbaf862aa/d214bf7fa2d538c4?lnk=gst&q=book#d214bf7fa2d538c4
- 'Ramaze Manual' +
  http://book.ramaze.net/ +
  http://github.com/manveru/ramaze-book/tree/master
- 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.
- 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 its 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).
- http://volnitsky.com/[Leonid Volnitsky's site] is generated using
  AsciiDoc and includes Leonid's <<X5,matplotlib filter>>.
- http://www.weechat.org/[WeeChat] uses AsciiDoc for
  http://www.weechat.org/doc[project documentation].
- http://www.clansuite.com/[Clansuite] uses AsciiDoc for
  http://www.clansuite.com/documentation/[project documentation].
- The http://fc-solve.berlios.de/[Freecell Solver program] uses
  AsciiDoc for its
  http://fc-solve.berlios.de/docs/#distributed-docs[distributed
  documentation].
- Eric Raymond's http://gpsd.berlios.de/AIVDM.html[AIVDM/AIVDO
  protocol decoding] documentation is written using AsciiDoc.
- Dwight Schauer has written an http://lxc.teegra.net/[LXC HOWTO] in
  AsciiDoc.

Please let me know if any of these links need updating.


[[X1]]
LaTeX Backend
-------------
An experimental LaTeX backend was written for AsciiDoc in 2006 by
Benjamin Klum.  Benjamin did a superhuman job (I admit it, I didn't
think this was doable due to AsciiDoc's SGML/XML bias).  Owning to to
other commitments, Benjamin was unable to maintain this backend.
Here's link:latex-backend.html[Benjamin's 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
Geoff's efforts it now works with AsciiDoc 8.4.3. Geoff's updated
`latex.conf` file shipped with AsciiDoc version 8.4.4. The backend
still has limitations and remains experimental (see
link:latex-bugs.html[Geoff's notes]).

It's probably also worth pointing out that LaTeX output can be
generated by passing AsciiDoc generated DocBook through `dblatex(1)`.
