asciidoc / INSTALL.txt

AsciiDoc Installation

NOTE: The current version of AsciiDoc requires *Python 2.3 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[].

The latest AsciiDoc downloads can be found on the AsciiDoc website[] and at the

Prepackaged AsciiDoc installation
The AsciiDoc[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 `` shell script in the tarball
root directory (thanks to[Jacob Mandelson] for the
initial implementation of this script).

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

  $ tar -xzf asciidoc-{revision}.tar.gz
  $ cd asciidoc-{revision}
  $ sudo ./

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

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

If Vim is installed on your system `` 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:

  $ 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

  $ asciidoc doc/asciidoc.txt

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