mirror of
https://git.rtems.org/rtems-source-builder
synced 2024-10-09 07:15:10 +08:00
236 lines
8.7 KiB
Plaintext
236 lines
8.7 KiB
Plaintext
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
|