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/.


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


Installing from the Mercurial repository
----------------------------------------
The AsciiDoc http://www.selenic.com/mercurial/[Mercurial] repository
is hosted by http://code.google.com/[Google Code].
To browse the repository go to
http://code.google.com/p/asciidoc/source/browse/.
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 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 {revnumber} tagged release:

[subs="attributes"]
  $ cd ~/bin
  $ hg clone -r {revnumber} https://asciidoc.googlecode.com/hg/ asciidoc-{revnumber}

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:

[subs="attributes"]
  $ ln -s ~/bin/asciidoc-{revnumber}/asciidoc.py ~/bin/asciidoc
  $ ln -s ~/bin/asciidoc-{revnumber}/a2x.py ~/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 a2x.py -f manpage doc/asciidoc.1.txt
$ python a2x.py -f manpage doc/a2x.1.txt
$ sudo make install
---------------------------------------------

To uninstall:

---------------------------------------------
$ sudo make uninstall
---------------------------------------------


[[X1]]
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:

[subs="attributes"]
  $ 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
http://www.a-a-p.org/[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.

*********************************************************************


[[X2]]
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
  http://packages.debian.org/asciidoc[AsciiDoc Debian package]
  available.  Thanks to mailto:stone@debian.org[Fredrik Steen] who
  built and maintains the Debian AsciiDoc package.

*Gentoo Linux*::
  If you use Gentoo Linux there's a
  http://packages.gentoo.org/packages/?category=app-text;name=asciidoc[Gentoo
  AsciiDoc package] available. Thanks to
  mailto:brandon@ifup.org[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*::
  mailto:bero@arklinux.org[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*::
  mailto:cw@ixplanet.de[Christian Wiese] added AsciiDoc to the
  http://www.t2-project.org/[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 link:userguide.html#X38[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:

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

  $ python asciidoc.py 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/testasciidoc.py update