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
http://www.python.org/.

The latest AsciiDoc downloads can be found on the AsciiDoc website
http://www.methods.co.nz/asciidoc/downloads.html and at the
SourceForge http://sourceforge.net/projects/asciidoc/.

Prepackaged AsciiDoc installation
---------------------------------
The AsciiDoc
http://www.methods.co.nz/asciidoc/downloads.html[downloads page]
lists AsciiDoc packages for various Linux distributions.


Distribution tarball installation
---------------------------------
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
directory.

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

[subs="attributes"]
  $ tar -xzf asciidoc-{revision}.tar.gz
  $ cd asciidoc-{revision}
  $ ./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).


Installing from the Mercurial repository
----------------------------------------
This is an easy way to install AsciiDoc 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 http://www.selenic.com/mercurial/[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 {revision} tagged release:

[subs="attributes"]
  $ cd ~/bin
  $ hg clone -r {revision} http://hg.sharesource.org/asciidoc asciidoc-{revision}

- 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:

[subs="attributes"]
  $ ln -s ~/bin/asciidoc-{revision}/asciidoc.py ~/bin/asciidoc

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


Microsoft Windows installation
------------------------------
To install the zip formatted distribution just unzip the contents to a
new folder:

[subs="attributes"]
  $ mkdir asciidoc
  $ cd asciidoc
  $ unzip ../asciidoc-{revision}.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
(`./doc/asciidoc.html`):

  $ python asciidoc.py doc/asciidoc.txt

link:testasciidoc.html[testasciidoc] offers a more extensive set of
conformance tests.
