diff options
Diffstat (limited to 'doc/asciidoc/INSTALL')
| -rw-r--r-- | doc/asciidoc/INSTALL | 235 |
1 files changed, 235 insertions, 0 deletions
diff --git a/doc/asciidoc/INSTALL b/doc/asciidoc/INSTALL new file mode 100644 index 0000000..cfca794 --- /dev/null +++ b/doc/asciidoc/INSTALL @@ -0,0 +1,235 @@ + AsciiDoc Installation + + version 8.6.8, 17 July 2012 + + 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 + [1]http://www.python.org/. + __________________________________________________________________ + +1. Prerequisites + + See the [2]README page. + __________________________________________________________________ + +2. Installing from the Mercurial repository + + The AsciiDoc [3]Mercurial repository is hosted by [4]Google Code. To + browse the repository go to + [5]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 [6]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.6.8 tagged release: + $ cd ~/bin + $ hg clone -r 8.6.8 https://asciidoc.googlecode.com/hg/ asciidoc-8.6.8 + + 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. + + 2.1. 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: + $ ln -s ~/bin/asciidoc-8.6.8/asciidoc.py ~/bin/asciidoc + $ ln -s ~/bin/asciidoc-8.6.8/a2x.py ~/bin/a2x + + Use the Mercurial pull command to update your local AsciiDoc + repository. + + 2.2. 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 + __________________________________________________________________ + +3. Distribution tarball installation + + The distribution source tarballs can be downloaded from the SourceForge + [7]http://sourceforge.net/projects/asciidoc/. + + Note + Unless you are [8]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: + $ tar -xzf asciidoc-8.6.8.tar.gz + $ cd asciidoc-8.6.8 + $ ./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). + __________________________________________________________________ + +4. 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: + $ unzip asciidoc-8.6.8.zip + + This will create the folder asciidoc-8.6.8 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 + [9]How to Create Handsome PDF Documents Without Frustration using + [10]Cygwin, [11]dblatex and AsciiDoc. + __________________________________________________________________ + +5. 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 + + [12]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 + __________________________________________________________________ + +6. Building the distribution + + The AsciiDoc distribution is built using [13]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 + __________________________________________________________________ + +7. 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 + [14]AsciiDoc Debian package available. Thanks to [15]Fredrik + Steen who built and maintains the Debian AsciiDoc package. + + Gentoo Linux + If you use Gentoo Linux there’s a [16]Gentoo AsciiDoc package + available. Thanks to [17]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 [18]http://linuxpackages.net/. + + Ark Linux + [19]Bernhard Rosenkraenzer added AsciiDoc to Ark Linux — the + package is available from the Ark Linux repository at + [20]http://arklinux.osuosl.org/dockyard-devel/, so Ark Linux + users should just run apt-get install asciidoc. + + T2 Linux + [21]Christian Wiese added AsciiDoc to the [22]T2 Linux + repository at + [23]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 + [24]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: [25]http://opencsw.org/packages/asciidoc. + + See also [26]Packager Notes in the AsciiDoc User Guide. + __________________________________________________________________ + + Version 8.6.8 + Last updated 2010-11-15 08:44:54 NZDT + +References + + 1. http://www.python.org/ + 2. file://localhost/tmp/lynxXXXXr4pa6e/README.html + 3. http://www.selenic.com/mercurial/ + 4. http://code.google.com/ + 5. http://code.google.com/p/asciidoc/source/browse/ + 6. http://www.selenic.com/mercurial/ + 7. http://sourceforge.net/projects/asciidoc/ + 8. file://localhost/tmp/lynxXXXXr4pa6e/L12440-2561TMP.html#X3 + 9. http://blog.rainwebs.net/2010/02/25/how-to-create-handsome-pdf-documents-without-frustration/ + 10. http://www.cygwin.com/ + 11. http://dblatex.sourceforge.net/ + 12. file://localhost/tmp/lynxXXXXr4pa6e/testasciidoc.html + 13. http://www.a-a-p.org/ + 14. http://packages.debian.org/asciidoc + 15. mailto:stone@debian.org + 16. http://packages.gentoo.org/package/app-text/asciidoc + 17. mailto:brandon@ifup.org + 18. http://linuxpackages.net/ + 19. mailto:bero@arklinux.org + 20. http://arklinux.osuosl.org/dockyard-devel/ + 21. mailto:cw@ixplanet.de + 22. http://www.t2-project.org/ + 23. http://svn.exactcode.de/t2/trunk/package/textproc/asciidoc/ + 24. http://dag.wieers.com/rpm/packages/asciidoc/ + 25. http://opencsw.org/packages/asciidoc + 26. file://localhost/tmp/lynxXXXXr4pa6e/userguide.html#X38 |