AsciiDoc Installation
=====================

NOTE: The current version of AsciiDoc requires *Python 3.5 or later*
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
-------------

- Python 3.5+
- DocBook XSL Stylesheets
- xsltproc
- w3m
- dblatex
- FOP
- make

Installing from PyPI
--------------------
Starting from 10.0 release, AsciiDoc.py can be installed from PyPI repository
by doing the following:

  $ python3 -m pip install asciidoc

Installing from the GitHub repository
-------------------------------------
The AsciiDoc repository is hosted by https://github.com[GitHub].
To browse the repository go to https://github.com/asciidoc/asciidoc-py3.
You can install AsciiDoc from the repository if you don't have an up to
date packaged version, or you want to get the latest version from the master
branch:

- Make sure you have https://git-scm.com/[Git]
  installed; you can check with:

  $ git --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
  $ git clone https://github.com/asciidoc/asciidoc-py3 asciidoc-{revnumber}
  $ cd asciidoc-{revnumber}
  $ git checkout {revnumber}

You now have two choices: you can run asciidoc locally from your
repository (e.g. `python3 -m asciidoc` or `python3 -m asciidoc.a2x`) or you
can use 'autoconf(1)' and 'make(1)' to perform a system-wide install. If you
wish to update your installation, run `git pull` and re-run `make(1)` to
re-install the updated version

Uninstalling AsciiDoc.py
------------------------

To uninstall AsciiDoc.py, if you installed it via PyPI, then simply do the
following:

  $ python3 -m pip uninstall asciidoc

If you installed it via `make(1)`, please do the following:

  $ sudo make uninstall


[[X1]]
Distribution tarball installation
---------------------------------
The distribution source tarballs can be downloaded from GitHub
releases page https://github.com/asciidoc/asciidoc-py3/releases.

If your flavor of 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 `Makefile`
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 are already installed as built into the vim runtime.


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

[subs="attributes"]
  $ unzip asciidoc-{revnumber}.zip

This will create the folder +asciidoc-{revnumber}+ containing the
`asciidoc.py` and `a2x.py` executables along with configuration files
and documentation.

To generate DocBook based outputs (e.g. PDFs) you will also need a
working DocBook toolchain. Installing and configuring a DocBook
toolchain on Windows can be a challenge -- this blog post explains
http://blog.rainwebs.net/2010/02/25/how-to-create-handsome-pdf-documents-without-frustration/[How
to Create Handsome PDF Documents Without Frustration] using
http://www.cygwin.com/[Cygwin],
http://dblatex.sourceforge.net/[dblatex] and AsciiDoc.


Testing your installation
-------------------------
To test out AsciiDoc.py, you will need to install `pytest` and `pytest-mock`
from PyPI.

Test out asciidoc by changing to the AsciiDoc application directory
and converting the User Guide document (`./doc/asciidoc.txt`) to XHTML
(`./doc/asciidoc.html`):

  $ python3 asciidoc.py doc/asciidoc.txt

The link:testasciidoc.html[testasciidoc] tool offers a more extensive set of
conformance tests. You can run the tests by executing this command:

  $ python3 ./tests/testasciidoc.py run

Unit tests can be run by doing:

  $ python3 -m pytest

Doctests can be run by doing:

  $ python3 -m asciidoc.asciidoc --doctest

Running all three of these can be accomplished through the Makefile:

  $ make test


[[X2]]
Prepackaged AsciiDoc installation
---------------------------------
The following platform-specific AsciiDoc packages are available:

*Fedora Linux*::
  AsciiDoc is included in Fedora Extras, which is available in
  the default Fedora installation. To install asciidoc, execute the
  following command:

  $ yum install asciidoc

*Ubuntu / Debian*::
  AsciiDoc is included in Ubuntu / Debian package manager. To install,
  execute the following command:

  $ apt install asciidoc

*macOS Homebrew*::
  AsciiDoc has been packaged in homebrew and is installable using the
  following command:

  $ brew install asciidoc

See also link:userguide.html#X38[Packager Notes] in the 'AsciiDoc User
Guide'.