Re-add INSTALL.adoc

Signed-off-by: Matthew Peveler <matt.peveler@gmail.com>

1 files changed, 177 insertions, 0 deletions

diff --git a/INSTALL.adoc b/INSTALL.adoc
new file mode 100644
index 0000000..e1b7526
--- /dev/null
+++ b/INSTALL.adoc
@@ -0,0 +1,177 @@
+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'.