1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
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
|
