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

.{date}: AsciiDoc {revision} Released
************************************************************************
This release fixes couple of bugs in 8.2.4, in particular a nasty
regression bug (`future feature with_statement is not defined`). *No
new features have been added*.

************************************************************************

.10 November 2007: AsciiDoc 8.2.4 Released
************************************************************************
This release adds support for language specific configuration files
along with a couple of other fairly minor additions.

A read-only copy of the AsciiDoc Mercurial repository is now
link:downloads.html#X3[available online].

The big news is the upcoming link:version9.html[AsciiDoc version 9]
release which has been undertaken by Yannick Gingras. See
link:version9.html[here] for details.

Read the link:CHANGELOG.html[CHANGELOG] for a full description of
additions and changes.

mailto:srackham@methods.co.nz['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, 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 using `xsltproc(1)`, DocBook XSL
  Stylesheets and FOP.

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


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.


[[X3]]
Mathematical Formulae
---------------------
You can include mathematical formulae in your AsciiDoc documents using
link:asciimath.html[ASCIIMathML] or link:latexmath.html[LaTeXMathML]
notation.


Vim Syntax Highlighter
----------------------
An AsciiDoc syntax highlighter for the Vim text editor is included in
the AsciiDoc distribution (see 'Appendix J' 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.
- Thomas Berker has written an
  http://liksom.info/blog/?q=node/114[AsciiDoc Cheatsheet].
- 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].
- 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].

[[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].


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


AsciiDoc version 9
-----------------
The next version of AsciiDoc is underway -- details
link:version9.html[here].
