AsciiDoc Installation

AsciiDoc
Text based document generation

»Home »Man Page »User Guide »Installation »FAQ »a2x »API »Cheatsheet »Tests »ChangeLog »Support »Page Source | # AsciiDoc Installation
| 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/.
- ## Prerequisites See the 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 http://hg.sharesource.org/asciidoc/. Installing from the repository 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 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 8.4.5 tagged release:
      $ cd ~/bin
      $ hg clone -r 8.4.5 http://hg.sharesource.org/asciidoc asciidoc-8.4.5
- 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-8.4.5/asciidoc.py ~/bin/asciidoc
Use the Mercurial `pull` command to update your AsciiDoc repository. ## Distribution tarball installation The distribution source tarballs can be downloaded from the SourceForge http://sourceforge.net/projects/asciidoc/. 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:
    $ tar -xzf asciidoc-8.4.5.tar.gz
    $ cd asciidoc-8.4.5
    $ ./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). 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 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 http://linuxpackages.net/. Ark Linux Bernhard Rosenkraenzer added AsciiDoc to Ark Linux — the package is available from the Ark Linux repository at http://arklinux.osuosl.org/dockyard-devel/, so Ark Linux users should just run `apt-get install asciidoc`. T2 Linux Christian Wiese added AsciiDoc to the T2 Linux repository at http://svn.exactcode.de/t2/trunk/package/textproc/asciidoc/. 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 http://dag.wieers.com/rpm/packages/asciidoc/. CSW Package for Sun Solaris Ben Walton has created a CSW package for AsciiDoc, you can find it here: http://opencsw.org/packages/asciidoc. See also Packager Notes in the AsciiDoc User Guide. ## 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-8.4.5.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
testasciidoc offers a more extensive set of conformance tests:
    $ python ./tests/testasciidoc.py update