diff options
Diffstat (limited to 'doc/asciidoc/INSTALL.txt')
| -rw-r--r-- | doc/asciidoc/INSTALL.txt | 227 |
1 files changed, 227 insertions, 0 deletions
diff --git a/doc/asciidoc/INSTALL.txt b/doc/asciidoc/INSTALL.txt new file mode 100644 index 0000000..eb07ddd --- /dev/null +++ b/doc/asciidoc/INSTALL.txt @@ -0,0 +1,227 @@ +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 locally from your +repository or you can use 'autoconf(1)' and 'make(1)' to perform a +system-wide install. + +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 +$ 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/. + +NOTE: Unless you are <<X3,installing on Microsoft Windows>> you should +use the tarball and not the zip file to install the the distribution +(the tarball contains symlinks). + +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). + + +[[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 +------------------------- +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 + +Now you can run the tests by executing this command: + + $ python ./tests/testasciidoc.py run + +A full battery of tests can be run from the `main.aap` script in the +distribution root directory: + + $ aap test + + +Building the distribution +------------------------- +The AsciiDoc distribution 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: + +`./main.aap`:: Builds the distribution tarball and zip files, +documentation and example website. +`./doc/main.aap`:: Builds distribution documentation. +`./examples/website/main.aap`:: Builds AsciiDoc website. +`./common.aap`:: Included in all scripts. + +To build the distribution tarball and zip files, documentation and +example website run A-A-P from the distribution root directory: + + $ aap + + +[[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/package/app-text/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'. + + |