asciidoc / INSTALL.txt

Full commit
AsciiDoc Installation

NOTE: The current version of AsciiDoc requires *Python 2.4 or newer*
to run.  If you don't already have an up-to-date version of Python
installed it can be downloaded from the official Python website

See the link:README.html[README] page.

Installing from the Mercurial repository
The AsciiDoc[Mercurial] repository
is hosted by[ShareSource].  ShareSource is a
Mercurial friendly website for hosting Open Source projects.
To browse the repository go to
You can install AsciiDoc from the repository if you don't have an up to
date packaged version or want to get the latest version from the trunk:

- Make sure you have[Mercurial]
  installed, you can check with:

  $ hg --version

- Go to the directory you want to install AsciiDoc into and download
  the repository.  This example gets the {revnumber} tagged release:

  $ cd ~/bin
  $ hg clone -r {revnumber} asciidoc-{revnumber}

.Repository source archives
Another way to get the latest asciidoc sources without installing
Mercurial is to download and extract a Zip or Tar formatted archive:


Archives of all revisions (not just the tip) are available at the
repository website.


You now have two choices: you can run asciidoc directly from you local
repository or you can use 'autoconf(1)' and 'make(1)' to perform a
normal install from the repository.

Running asciidoc from your local copy
Create a symlink to the AsciiDoc script in a search `PATH` directory
so it's easy to execute `asciidoc` from the command-line, for example:

  $ ln -s ~/bin/asciidoc-{revnumber}/ ~/bin/asciidoc
  $ ln -s ~/bin/asciidoc-{revnumber}/ ~/bin/a2x

Use the Mercurial `pull` command to update your local AsciiDoc repository.

Installing asciidoc for all users
Create `configure` using 'autoconf(1)'; use `configure` to create the
`Makefile`; run 'make(1)'; build the man pages; install:

$ autoconf
$ ./configure
$ make
$ python -f manpage doc/asciidoc.1.txt
$ python -f manpage doc/a2x.1.txt
$ sudo make install

To uninstall:

$ sudo make uninstall

Distribution tarball installation
The distribution source tarballs can be downloaded from the

If your flavor or UNIX or Linux does not have a packaged AsciiDoc
distribution or if you prefer to install the latest AsciiDoc version
from source use the `configure` shell script in the tarball root

The `autoconf(1)` generated `configure` script creates a make file
that is tailored for your system. To install:

  $ tar -xzf asciidoc-{revnumber}.tar.gz
  $ cd asciidoc-{revnumber}
  $ ./configure
  $ sudo make install

To install the documentation:

  $ sudo make docs

To uninstall AsciiDoc:

  $ sudo make uninstall

If Vim is installed on your system the AsciiDoc Vim syntax highlighter
and filetype detection scripts will be install in the global Vim
configuration file directory (`asciidoc.vim` in the `syntax` directory
and `asciidoc_filetype.vim` in the `ftdetect` directory).

.Building the distribution
The AsciiDoc distribution tarball is built using[A-A-P] (a software build system written by Bram
Moolenaar). The AsciiDoc A-A-P scripts are:

`./common.aap`:: Included in all scripts.
`./main.aap`:: Builds distribution tarball and zip files.
`./doc/main.aap`:: Builds distribution documentation.
`./examples/website/main.aap`:: Builds AsciiDoc website.

It's arguable that build and install should be done with a single tool
but I wrote the A-A-P build scripts before the installer (because I
find make/autoconf tedious). The make/autoconf installer was added as
the canonical installer for packagers and for users who don't have
pre-built AsciiDoc packages and/or don't want to install from the
Mercurial repository.


Prepackaged AsciiDoc installation
The following platform specific AsciiDoc packages are available:

*Debian GNU/Linux*::
  If you use Debian or a Debian based distribution there's an[AsciiDoc Debian package]
  available.  Thanks to[Fredrik Steen] who
  built and maintains the Debian AsciiDoc package.

*Gentoo Linux*::
  If you use Gentoo Linux there's a;name=asciidoc[Gentoo
  AsciiDoc package] available. Thanks to[Brandon Philips] for writing the ebuild.

*Fedora Linux*::
  With help from Terje Røsten, Chris Wright added asciidoc to Fedora
  Extras which is available in the default installation. To install
  asciidoc execute the following command:

  $ yum install asciidoc

*Slackware Linux*::
  John Calixto has created a Slackware package for AsciiDoc which can
  be downloaded from

*Ark Linux*::[Bernhard Rosenkraenzer] added AsciiDoc to
  Ark Linux -- the package is available from the Ark Linux repository
  at, so Ark Linux users
  should just run `apt-get install asciidoc`.

*T2 Linux*::[Christian Wiese] added AsciiDoc to the[T2 Linux] repository at To
  build and install the package on a T2 system, run
  `./scripts/Emerge-Pkg asciidoc` from within your T2 source directory
  (default: `/usr/src/t2-src`).

*Red Hat Enterprise Linux, Fedora and CentOS packages*::
  Dag Wieers has built AsciiDoc RPMs for a number of Red Hat based
  distributions, they can be downloaded from

*CSW Package for Sun Solaris*::
  Ben Walton has created a CSW package for AsciiDoc, you can find it

See also link:userguide.html#X38[Packager Notes] in the 'AsciiDoc User

Microsoft Windows installation
AsciiDoc is developed and tested on Linux but there seem to be quite a
few people using it on Windows.  To install AsciiDoc on Windows unzip
the distribution Zip file contents to a new folder:

  $ mkdir asciidoc
  $ cd asciidoc
  $ unzip ../asciidoc-{revnumber}.zip

Testing your installation
Test out asciidoc by changing to the AsciiDoc application directory
and convert the User Guide document (`./doc/asciidoc.txt`) to XHTML

  $ python doc/asciidoc.txt

link:testasciidoc.html[testasciidoc] offers a more extensive set of
conformance tests, though you do need to create the test data before
running the tests (this in itself is a good post-install test):

  $ python ./tests/ update