1 | AsciiDoc Installation |
---|
2 | ===================== |
---|
3 | |
---|
4 | NOTE: The current version of AsciiDoc requires *Python 2.4 or newer* |
---|
5 | to run. If you don't already have an up-to-date version of Python |
---|
6 | installed it can be downloaded from the official Python website |
---|
7 | http://www.python.org/. |
---|
8 | |
---|
9 | |
---|
10 | Prerequisites |
---|
11 | ------------- |
---|
12 | See the link:README.html[README] page. |
---|
13 | |
---|
14 | |
---|
15 | Installing from the Mercurial repository |
---|
16 | ---------------------------------------- |
---|
17 | The AsciiDoc http://www.selenic.com/mercurial/[Mercurial] repository |
---|
18 | is hosted by http://code.google.com/[Google Code]. |
---|
19 | To browse the repository go to |
---|
20 | http://code.google.com/p/asciidoc/source/browse/. |
---|
21 | You can install AsciiDoc from the repository if you don't have an up to |
---|
22 | date packaged version or want to get the latest version from the trunk: |
---|
23 | |
---|
24 | - Make sure you have http://www.selenic.com/mercurial/[Mercurial] |
---|
25 | installed, you can check with: |
---|
26 | |
---|
27 | $ hg --version |
---|
28 | |
---|
29 | - Go to the directory you want to install AsciiDoc into and download |
---|
30 | the repository. This example gets the {revnumber} tagged release: |
---|
31 | |
---|
32 | [subs="attributes"] |
---|
33 | $ cd ~/bin |
---|
34 | $ hg clone -r {revnumber} https://asciidoc.googlecode.com/hg/ asciidoc-{revnumber} |
---|
35 | |
---|
36 | You now have two choices: you can run asciidoc locally from your |
---|
37 | repository or you can use 'autoconf(1)' and 'make(1)' to perform a |
---|
38 | system-wide install. |
---|
39 | |
---|
40 | Running asciidoc from your local copy |
---|
41 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
42 | Create a symlink to the AsciiDoc script in a search `PATH` directory |
---|
43 | so it's easy to execute `asciidoc` from the command-line, for example: |
---|
44 | |
---|
45 | [subs="attributes"] |
---|
46 | $ ln -s ~/bin/asciidoc-{revnumber}/asciidoc.py ~/bin/asciidoc |
---|
47 | $ ln -s ~/bin/asciidoc-{revnumber}/a2x.py ~/bin/a2x |
---|
48 | |
---|
49 | Use the Mercurial `pull` command to update your local AsciiDoc repository. |
---|
50 | |
---|
51 | Installing asciidoc for all users |
---|
52 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
53 | Create `configure` using 'autoconf(1)'; use `configure` to create the |
---|
54 | `Makefile`; run 'make(1)'; build the man pages; install: |
---|
55 | |
---|
56 | --------------------------------------------- |
---|
57 | $ autoconf |
---|
58 | $ ./configure |
---|
59 | $ make |
---|
60 | $ sudo make install |
---|
61 | --------------------------------------------- |
---|
62 | |
---|
63 | To uninstall: |
---|
64 | |
---|
65 | --------------------------------------------- |
---|
66 | $ sudo make uninstall |
---|
67 | --------------------------------------------- |
---|
68 | |
---|
69 | |
---|
70 | [[X1]] |
---|
71 | Distribution tarball installation |
---|
72 | --------------------------------- |
---|
73 | The distribution source tarballs can be downloaded from the |
---|
74 | SourceForge http://sourceforge.net/projects/asciidoc/. |
---|
75 | |
---|
76 | NOTE: Unless you are <<X3,installing on Microsoft Windows>> you should |
---|
77 | use the tarball and not the zip file to install the the distribution |
---|
78 | (the tarball contains symlinks). |
---|
79 | |
---|
80 | If your flavor or UNIX or Linux does not have a packaged AsciiDoc |
---|
81 | distribution or if you prefer to install the latest AsciiDoc version |
---|
82 | from source use the `configure` shell script in the tarball root |
---|
83 | directory. |
---|
84 | |
---|
85 | The `autoconf(1)` generated `configure` script creates a make file |
---|
86 | that is tailored for your system. To install: |
---|
87 | |
---|
88 | [subs="attributes"] |
---|
89 | $ tar -xzf asciidoc-{revnumber}.tar.gz |
---|
90 | $ cd asciidoc-{revnumber} |
---|
91 | $ ./configure |
---|
92 | $ sudo make install |
---|
93 | |
---|
94 | To install the documentation: |
---|
95 | |
---|
96 | $ sudo make docs |
---|
97 | |
---|
98 | To uninstall AsciiDoc: |
---|
99 | |
---|
100 | $ sudo make uninstall |
---|
101 | |
---|
102 | If Vim is installed on your system the AsciiDoc Vim syntax highlighter |
---|
103 | and filetype detection scripts will be install in the global Vim |
---|
104 | configuration file directory (`asciidoc.vim` in the `syntax` directory |
---|
105 | and `asciidoc_filetype.vim` in the `ftdetect` directory). |
---|
106 | |
---|
107 | |
---|
108 | [[X3]] |
---|
109 | Microsoft Windows installation |
---|
110 | ------------------------------ |
---|
111 | AsciiDoc is developed and tested on Linux but there seem to be quite a |
---|
112 | few people using it on Windows. To install AsciiDoc on Windows unzip |
---|
113 | the distribution Zip file contents: |
---|
114 | |
---|
115 | [subs="attributes"] |
---|
116 | $ unzip asciidoc-{revnumber}.zip |
---|
117 | |
---|
118 | This will create the folder +asciidoc-{revnumber}+ containing the |
---|
119 | `asciidoc.py` and `a2x.py` executables along with configuration files |
---|
120 | and documentation. |
---|
121 | |
---|
122 | To generate DocBook based outputs (e.g. PDFs) you will also need a |
---|
123 | working DocBook toolchain. Installing and configuring a DocBook |
---|
124 | toolchain on Windows can be a challenge -- this blog post explains |
---|
125 | http://blog.rainwebs.net/2010/02/25/how-to-create-handsome-pdf-documents-without-frustration/[How |
---|
126 | to Create Handsome PDF Documents Without Frustration] using |
---|
127 | http://www.cygwin.com/[Cygwin], |
---|
128 | http://dblatex.sourceforge.net/[dblatex] and AsciiDoc. |
---|
129 | |
---|
130 | |
---|
131 | Testing your installation |
---|
132 | ------------------------- |
---|
133 | Test out asciidoc by changing to the AsciiDoc application directory |
---|
134 | and convert the User Guide document (`./doc/asciidoc.txt`) to XHTML |
---|
135 | (`./doc/asciidoc.html`): |
---|
136 | |
---|
137 | $ python asciidoc.py doc/asciidoc.txt |
---|
138 | |
---|
139 | link:testasciidoc.html[testasciidoc] offers a more extensive set of |
---|
140 | conformance tests, though you do need to create the test data before |
---|
141 | running the tests (this in itself is a good post-install test): |
---|
142 | |
---|
143 | $ python ./tests/testasciidoc.py update |
---|
144 | |
---|
145 | Now you can run the tests by executing this command: |
---|
146 | |
---|
147 | $ python ./tests/testasciidoc.py run |
---|
148 | |
---|
149 | A full battery of tests can be run from the `main.aap` script in the |
---|
150 | distribution root directory: |
---|
151 | |
---|
152 | $ aap test |
---|
153 | |
---|
154 | |
---|
155 | Building the distribution |
---|
156 | ------------------------- |
---|
157 | The AsciiDoc distribution is built using http://www.a-a-p.org/[A-A-P] |
---|
158 | (a software build system written by Bram Moolenaar). The AsciiDoc |
---|
159 | A-A-P scripts are: |
---|
160 | |
---|
161 | `./main.aap`:: Builds the distribution tarball and zip files, |
---|
162 | documentation and example website. |
---|
163 | `./doc/main.aap`:: Builds distribution documentation. |
---|
164 | `./examples/website/main.aap`:: Builds AsciiDoc website. |
---|
165 | `./common.aap`:: Included in all scripts. |
---|
166 | |
---|
167 | To build the distribution tarball and zip files, documentation and |
---|
168 | example website run A-A-P from the distribution root directory: |
---|
169 | |
---|
170 | $ aap |
---|
171 | |
---|
172 | |
---|
173 | [[X2]] |
---|
174 | Prepackaged AsciiDoc installation |
---|
175 | --------------------------------- |
---|
176 | The following platform specific AsciiDoc packages are available: |
---|
177 | |
---|
178 | *Debian GNU/Linux*:: |
---|
179 | If you use Debian or a Debian based distribution there's an |
---|
180 | http://packages.debian.org/asciidoc[AsciiDoc Debian package] |
---|
181 | available. Thanks to mailto:stone@debian.org[Fredrik Steen] who |
---|
182 | built and maintains the Debian AsciiDoc package. |
---|
183 | |
---|
184 | *Gentoo Linux*:: |
---|
185 | If you use Gentoo Linux there's a |
---|
186 | http://packages.gentoo.org/package/app-text/asciidoc[Gentoo AsciiDoc |
---|
187 | package] available. Thanks to mailto:brandon@ifup.org[Brandon |
---|
188 | Philips] for writing the ebuild. |
---|
189 | |
---|
190 | *Fedora Linux*:: |
---|
191 | With help from Terje RÞsten, Chris Wright added asciidoc to Fedora |
---|
192 | Extras which is available in the default installation. To install |
---|
193 | asciidoc execute the following command: |
---|
194 | |
---|
195 | $ yum install asciidoc |
---|
196 | |
---|
197 | *Slackware Linux*:: |
---|
198 | John Calixto has created a Slackware package for AsciiDoc which can |
---|
199 | be downloaded from http://linuxpackages.net/. |
---|
200 | |
---|
201 | *Ark Linux*:: |
---|
202 | mailto:bero@arklinux.org[Bernhard Rosenkraenzer] added AsciiDoc to |
---|
203 | Ark Linux -- the package is available from the Ark Linux repository |
---|
204 | at http://arklinux.osuosl.org/dockyard-devel/, so Ark Linux users |
---|
205 | should just run `apt-get install asciidoc`. |
---|
206 | |
---|
207 | *T2 Linux*:: |
---|
208 | mailto:cw@ixplanet.de[Christian Wiese] added AsciiDoc to the |
---|
209 | http://www.t2-project.org/[T2 Linux] repository at |
---|
210 | http://svn.exactcode.de/t2/trunk/package/textproc/asciidoc/. To |
---|
211 | build and install the package on a T2 system, run |
---|
212 | `./scripts/Emerge-Pkg asciidoc` from within your T2 source directory |
---|
213 | (default: `/usr/src/t2-src`). |
---|
214 | |
---|
215 | *Red Hat Enterprise Linux, Fedora and CentOS packages*:: |
---|
216 | Dag Wieers has built AsciiDoc RPMs for a number of Red Hat based |
---|
217 | distributions, they can be downloaded from |
---|
218 | http://dag.wieers.com/rpm/packages/asciidoc/. |
---|
219 | |
---|
220 | *CSW Package for Sun Solaris*:: |
---|
221 | Ben Walton has created a CSW package for AsciiDoc, you can find it |
---|
222 | here: http://opencsw.org/packages/asciidoc. |
---|
223 | |
---|
224 | See also link:userguide.html#X38[Packager Notes] in the 'AsciiDoc User |
---|
225 | Guide'. |
---|
226 | |
---|
227 | |
---|