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 is not supported or you prefer to
install from source use the `install.sh` shell script in the tarball
root directory (thanks to mailto:jlm@ofb.net[Jacob Mandelson] for the
initial implementation of this script).

`install.sh` installs AsciiDoc executables, configuration files and
man pages in the usual locations. Here's how:

[subs="normal"]
  $ tar -xzf asciidoc-{revision}.tar.gz
  $ cd asciidoc-{revision}
  $ sudo ./install.sh

NOTE: This script was tested on Ubuntu Linux.  You may need to edit
`install.sh` if your file locations differ from those wired into the
script.

The `uninstall.sh` script (actually just a symlink to `install.sh`)
will uninstall AsciiDoc.

If Vim is installed on your system `install.sh` will install the Vim
syntax highlighter and filetype detection scripts in the global
`/etc/vim` directory (`asciidoc.vim` in `/etc/vim/syntax/` and
`asciidoc_filetype.vim` in `/etc/vim/ftdetect/`).

To install locally put `asciidoc.vim` in `\~/.vim/syntax/` and
`asciidoc_filetype.vim` in `~/.vim/ftdetect/`.


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

[subs="normal"]
  $ 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`):

  $ asciidoc doc/asciidoc.txt

NOTE: Windows users will need to execute the `asciidoc.py` script
directly or create a suitable `asciidoc.bat` file.