← Back to branch summary

~ubuntu-branches/ubuntu/utopic/asciidoc/utopic

« back to all changes in this revision

Viewing changes to examples/website/INSTALL.html

  • Committer: Bazaar Package Importer
  • Author(s): Alexander Wirt
  • Date: 2010-11-27 23:19:57 UTC
  • mfrom: (1.1.12 upstream) (3.1.6 sid)
  • Revision ID: james.westby@ubuntu.com-20101127231957-jxdmrk7z7lkcqy3l
Tags: 8.6.3-1
http://bugs.debian.org/595324
http://bugs.debian.org/526351
http://bugs.debian.org/571303
http://bugs.debian.org/592423
http://bugs.debian.org/499497
http://bugs.debian.org/564015
* New upstream version (Closes: #595324)
* Support asciidoc API (Closes: #526351)
* Depend on python >= 2.4 (Closes: #571303)
* Do not compress .txt files (Closes: #592423)
* Enhance asciidoc manpage (Closes: #499497)
* Move some of the Recommends (vim-addon-manager, source-highlight) to 
  Suggests (Closes: #564015)
* Bump standards version (No changes)
* Add README.Source file

Show diffs side-by-side

added added

removed removed

Lines of Context:
examples/website/INSTALL.html
1
 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2
 
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3
 
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4
 
<head>
5
 
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6
 
<meta name="generator" content="AsciiDoc 8.5.2" />
7
 
<link rel="stylesheet" href="./xhtml11.css" type="text/css" />
8
 
<link rel="stylesheet" href="./xhtml11-quirks.css" type="text/css" />
9
 
<link rel="stylesheet" href="./layout1.css" type="text/css" />
10
 
<script type="text/javascript">
11
 
/*<![CDATA[*/
12
 
window.onload = function(){asciidoc.footnotes(); asciidoc.toc(1);}
13
 
/*]]>*/
14
 
</script>
15
 
<script type="text/javascript" src="./asciidoc-xhtml11.js"></script>
16
 
<title>AsciiDoc Installation</title>
17
 
</head>
18
 
<body style="max-width:70em">
19
 
<div id="layout-banner">
20
 
  <div id="layout-title">AsciiDoc</div>
21
 
  <div id="layout-description">Text based document generation</div>
22
 
</div>
23
 
<table>
24
 
<tr valign="top">
25
 
<td id="layout-menu">
26
 
  <div>&#187;<a href="index.html">Home</a></div>
27
 
  <div>&#187;<a href="manpage.html">Man&nbsp;Page</a></div>
28
 
  <div>&#187;<a href="userguide.html">User&nbsp;Guide</a></div>
29
 
  <div>&#187;<a href="INSTALL.html">Installation</a></div>
30
 
  <div>&#187;<a href="faq.html">FAQ</a></div>
31
 
  <div>&#187;<a href="a2x.1.html">a2x</a></div>
32
 
  <div>&#187;<a href="asciidocapi.html">API</a></div>
33
 
  <div>&#187;<a href="http://powerman.name/doc/asciidoc">Cheatsheet</a></div>
34
 
  <div>&#187;<a href="testasciidoc.html">Tests</a></div>
35
 
  <div>&#187;<a href="CHANGELOG.html">ChangeLog</a></div>
36
 
  <div>&#187;<a href="support.html">Support</a></div>
37
 
  <div id="page-source">&#187;<a href="INSTALL.txt">Page&nbsp;Source</a></div>
38
 
</td>
39
 
<td>
40
 
<div id="layout-content">
41
 
<div id="header">
42
 
<h1>AsciiDoc Installation</h1>
43
 
<div id="toc">
44
 
  <div id="toctitle">Table of Contents</div>
45
 
  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
46
 
</div>
47
 
</div>
48
 
<div id="content">
49
 
<div id="preamble">
50
 
<div class="sectionbody">
51
 
<div class="admonitionblock">
52
 
<table><tr>
53
 
<td class="icon">
54
 
<img src="./images/icons/note.png" alt="Note" />
55
 
</td>
56
 
<td class="content">The current version of AsciiDoc requires <strong>Python 2.4 or newer</strong>
57
 
to run.  If you don&#8217;t already have an up-to-date version of Python
58
 
installed it can be downloaded from the official Python website
59
 
<a href="http://www.python.org/">http://www.python.org/</a>.</td>
60
 
</tr></table>
61
 
</div>
62
 
</div>
63
 
</div>
64
 
<h2 id="_prerequisites">Prerequisites</h2>
65
 
<div class="sectionbody">
66
 
<div class="paragraph"><p>See the <a href="README.html">README</a> page.</p></div>
67
 
</div>
68
 
<h2 id="_installing_from_the_mercurial_repository">Installing from the Mercurial repository</h2>
69
 
<div class="sectionbody">
70
 
<div class="paragraph"><p>The AsciiDoc <a href="http://www.selenic.com/mercurial/">Mercurial</a> repository
71
 
is hosted by <a href="http://sharesource.org">ShareSource</a>.  ShareSource is a
72
 
Mercurial friendly website for hosting Open Source projects.
73
 
To browse the repository go to <a href="http://hg.sharesource.org/asciidoc/">http://hg.sharesource.org/asciidoc/</a>.
74
 
You can install AsciiDoc from the repository if you don&#8217;t have an up to
75
 
date packaged version or want to get the latest version from the trunk:</p></div>
76
 
<div class="ulist"><ul>
77
 
<li>
78
 
<p>
79
 
Make sure you have <a href="http://www.selenic.com/mercurial/">Mercurial</a>
80
 
  installed, you can check with:
81
 
</p>
82
 
<div class="literalblock">
83
 
<div class="content">
84
 
<pre><tt>$ hg --version</tt></pre>
85
 
</div></div>
86
 
</li>
87
 
<li>
88
 
<p>
89
 
Go to the directory you want to install AsciiDoc into and download
90
 
  the repository.  This example gets the 8.5.2 tagged release:
91
 
</p>
92
 
<div class="literalblock">
93
 
<div class="content">
94
 
<pre><tt>$ cd ~/bin
95
 
$ hg clone -r 8.5.2 http://hg.sharesource.org/asciidoc asciidoc-8.5.2</tt></pre>
96
 
</div></div>
97
 
</li>
98
 
</ul></div>
99
 
<div class="sidebarblock">
100
 
<div class="sidebar-content">
101
 
<div class="sidebar-title">Repository source archives</div>
102
 
<div class="paragraph"><p>Another way to get the latest asciidoc sources without installing
103
 
Mercurial is to download and extract a Zip or Tar formatted archive:</p></div>
104
 
<div class="paragraph"><p><a href="http://hg.sharesource.org/asciidoc/archive/tip.tar.bz2">http://hg.sharesource.org/asciidoc/archive/tip.tar.bz2</a></p></div>
105
 
<div class="paragraph"><p>or:</p></div>
106
 
<div class="paragraph"><p><a href="http://hg.sharesource.org/asciidoc/archive/tip.zip">http://hg.sharesource.org/asciidoc/archive/tip.zip</a></p></div>
107
 
<div class="paragraph"><p>Archives of all revisions (not just the tip) are available at the
108
 
repository website.</p></div>
109
 
</div></div>
110
 
<div class="paragraph"><p>You now have two choices: you can run asciidoc directly from you local
111
 
repository or you can use <em>autoconf(1)</em> and <em>make(1)</em> to perform a
112
 
normal install from the repository.</p></div>
113
 
<h3 id="_running_asciidoc_from_your_local_copy">Running asciidoc from your local copy</h3><div style="clear:left"></div>
114
 
<div class="paragraph"><p>Create a symlink to the AsciiDoc script in a search <tt>PATH</tt> directory
115
 
so it&#8217;s easy to execute <tt>asciidoc</tt> from the command-line, for example:</p></div>
116
 
<div class="literalblock">
117
 
<div class="content">
118
 
<pre><tt>$ ln -s ~/bin/asciidoc-8.5.2/asciidoc.py ~/bin/asciidoc
119
 
$ ln -s ~/bin/asciidoc-8.5.2/a2x.py ~/bin/a2x</tt></pre>
120
 
</div></div>
121
 
<div class="paragraph"><p>Use the Mercurial <tt>pull</tt> command to update your local AsciiDoc repository.</p></div>
122
 
<h3 id="_installing_asciidoc_for_all_users">Installing asciidoc for all users</h3><div style="clear:left"></div>
123
 
<div class="paragraph"><p>Create <tt>configure</tt> using <em>autoconf(1)</em>; use <tt>configure</tt> to create the
124
 
<tt>Makefile</tt>; run <em>make(1)</em>; build the man pages; install:</p></div>
125
 
<div class="listingblock">
126
 
<div class="content">
127
 
<pre><tt>$ autoconf
128
 
$ ./configure
129
 
$ make
130
 
$ python a2x.py -f manpage doc/asciidoc.1.txt
131
 
$ python a2x.py -f manpage doc/a2x.1.txt
132
 
$ sudo make install</tt></pre>
133
 
</div></div>
134
 
<div class="paragraph"><p>To uninstall:</p></div>
135
 
<div class="listingblock">
136
 
<div class="content">
137
 
<pre><tt>$ sudo make uninstall</tt></pre>
138
 
</div></div>
139
 
</div>
140
 
<h2 id="X1">Distribution tarball installation</h2>
141
 
<div class="sectionbody">
142
 
<div class="paragraph"><p>The distribution source tarballs can be downloaded from the
143
 
SourceForge <a href="http://sourceforge.net/projects/asciidoc/">http://sourceforge.net/projects/asciidoc/</a>.</p></div>
144
 
<div class="paragraph"><p>If your flavor or UNIX or Linux does not have a packaged AsciiDoc
145
 
distribution or if you prefer to install the latest AsciiDoc version
146
 
from source use the <tt>configure</tt> shell script in the tarball root
147
 
directory.</p></div>
148
 
<div class="paragraph"><p>The <tt>autoconf(1)</tt> generated <tt>configure</tt> script creates a make file
149
 
that is tailored for your system. To install:</p></div>
150
 
<div class="literalblock">
151
 
<div class="content">
152
 
<pre><tt>$ tar -xzf asciidoc-8.5.2.tar.gz
153
 
$ cd asciidoc-8.5.2
154
 
$ ./configure
155
 
$ sudo make install</tt></pre>
156
 
</div></div>
157
 
<div class="paragraph"><p>To install the documentation:</p></div>
158
 
<div class="literalblock">
159
 
<div class="content">
160
 
<pre><tt>$ sudo make docs</tt></pre>
161
 
</div></div>
162
 
<div class="paragraph"><p>To uninstall AsciiDoc:</p></div>
163
 
<div class="literalblock">
164
 
<div class="content">
165
 
<pre><tt>$ sudo make uninstall</tt></pre>
166
 
</div></div>
167
 
<div class="paragraph"><p>If Vim is installed on your system the AsciiDoc Vim syntax highlighter
168
 
and filetype detection scripts will be install in the global Vim
169
 
configuration file directory (<tt>asciidoc.vim</tt> in the <tt>syntax</tt> directory
170
 
and <tt>asciidoc_filetype.vim</tt> in the <tt>ftdetect</tt> directory).</p></div>
171
 
<div class="sidebarblock">
172
 
<div class="sidebar-content">
173
 
<div class="sidebar-title">Building the distribution</div>
174
 
<div class="paragraph"><p>The AsciiDoc distribution tarball is built using
175
 
<a href="http://www.a-a-p.org/">A-A-P</a> (a software build system written by Bram
176
 
Moolenaar). The AsciiDoc A-A-P scripts are:</p></div>
177
 
<div class="dlist"><dl>
178
 
<dt class="hdlist1">
179
 
<tt>./common.aap</tt>
180
 
</dt>
181
 
<dd>
182
 
<p>
183
 
Included in all scripts.
184
 
</p>
185
 
</dd>
186
 
<dt class="hdlist1">
187
 
<tt>./main.aap</tt>
188
 
</dt>
189
 
<dd>
190
 
<p>
191
 
Builds distribution tarball and zip files.
192
 
</p>
193
 
</dd>
194
 
<dt class="hdlist1">
195
 
<tt>./doc/main.aap</tt>
196
 
</dt>
197
 
<dd>
198
 
<p>
199
 
Builds distribution documentation.
200
 
</p>
201
 
</dd>
202
 
<dt class="hdlist1">
203
 
<tt>./examples/website/main.aap</tt>
204
 
</dt>
205
 
<dd>
206
 
<p>
207
 
Builds AsciiDoc website.
208
 
</p>
209
 
</dd>
210
 
</dl></div>
211
 
<div class="paragraph"><p>It&#8217;s arguable that build and install should be done with a single tool
212
 
but I wrote the A-A-P build scripts before the installer (because I
213
 
find make/autoconf tedious). The make/autoconf installer was added as
214
 
the canonical installer for packagers and for users who don&#8217;t have
215
 
pre-built AsciiDoc packages and/or don&#8217;t want to install from the
216
 
Mercurial repository.</p></div>
217
 
</div></div>
218
 
</div>
219
 
<h2 id="X2">Prepackaged AsciiDoc installation</h2>
220
 
<div class="sectionbody">
221
 
<div class="paragraph"><p>The following platform specific AsciiDoc packages are available:</p></div>
222
 
<div class="dlist"><dl>
223
 
<dt class="hdlist1">
224
 
<strong>Debian GNU/Linux</strong>
225
 
</dt>
226
 
<dd>
227
 
<p>
228
 
  If you use Debian or a Debian based distribution there&#8217;s an
229
 
  <a href="http://packages.debian.org/asciidoc">AsciiDoc Debian package</a>
230
 
  available.  Thanks to <a href="mailto:stone@debian.org">Fredrik Steen</a> who
231
 
  built and maintains the Debian AsciiDoc package.
232
 
</p>
233
 
</dd>
234
 
<dt class="hdlist1">
235
 
<strong>Gentoo Linux</strong>
236
 
</dt>
237
 
<dd>
238
 
<p>
239
 
  If you use Gentoo Linux there&#8217;s a
240
 
  <a href="http://packages.gentoo.org/packages/?category=app-text;name=asciidoc">Gentoo
241
 
  AsciiDoc package</a> available. Thanks to
242
 
  <a href="mailto:brandon@ifup.org">Brandon Philips</a> for writing the ebuild.
243
 
</p>
244
 
</dd>
245
 
<dt class="hdlist1">
246
 
<strong>Fedora Linux</strong>
247
 
</dt>
248
 
<dd>
249
 
<p>
250
 
  With help from Terje Røsten, Chris Wright added asciidoc to Fedora
251
 
  Extras which is available in the default installation. To install
252
 
  asciidoc execute the following command:
253
 
</p>
254
 
<div class="literalblock">
255
 
<div class="content">
256
 
<pre><tt>$ yum install asciidoc</tt></pre>
257
 
</div></div>
258
 
</dd>
259
 
<dt class="hdlist1">
260
 
<strong>Slackware Linux</strong>
261
 
</dt>
262
 
<dd>
263
 
<p>
264
 
  John Calixto has created a Slackware package for AsciiDoc which can
265
 
  be downloaded from <a href="http://linuxpackages.net/">http://linuxpackages.net/</a>.
266
 
</p>
267
 
</dd>
268
 
<dt class="hdlist1">
269
 
<strong>Ark Linux</strong>
270
 
</dt>
271
 
<dd>
272
 
<p>
273
 
  <a href="mailto:bero@arklinux.org">Bernhard Rosenkraenzer</a> added AsciiDoc to
274
 
  Ark Linux&#8201;&#8212;&#8201;the package is available from the Ark Linux repository
275
 
  at <a href="http://arklinux.osuosl.org/dockyard-devel/">http://arklinux.osuosl.org/dockyard-devel/</a>, so Ark Linux users
276
 
  should just run <tt>apt-get install asciidoc</tt>.
277
 
</p>
278
 
</dd>
279
 
<dt class="hdlist1">
280
 
<strong>T2 Linux</strong>
281
 
</dt>
282
 
<dd>
283
 
<p>
284
 
  <a href="mailto:cw@ixplanet.de">Christian Wiese</a> added AsciiDoc to the
285
 
  <a href="http://www.t2-project.org/">T2 Linux</a> repository at
286
 
  <a href="http://svn.exactcode.de/t2/trunk/package/textproc/asciidoc/">http://svn.exactcode.de/t2/trunk/package/textproc/asciidoc/</a>. To
287
 
  build and install the package on a T2 system, run
288
 
  <tt>./scripts/Emerge-Pkg asciidoc</tt> from within your T2 source directory
289
 
  (default: <tt>/usr/src/t2-src</tt>).
290
 
</p>
291
 
</dd>
292
 
<dt class="hdlist1">
293
 
<strong>Red Hat Enterprise Linux, Fedora and CentOS packages</strong>
294
 
</dt>
295
 
<dd>
296
 
<p>
297
 
  Dag Wieers has built AsciiDoc RPMs for a number of Red Hat based
298
 
  distributions, they can be downloaded from
299
 
  <a href="http://dag.wieers.com/rpm/packages/asciidoc/">http://dag.wieers.com/rpm/packages/asciidoc/</a>.
300
 
</p>
301
 
</dd>
302
 
<dt class="hdlist1">
303
 
<strong>CSW Package for Sun Solaris</strong>
304
 
</dt>
305
 
<dd>
306
 
<p>
307
 
  Ben Walton has created a CSW package for AsciiDoc, you can find it
308
 
  here: <a href="http://opencsw.org/packages/asciidoc">http://opencsw.org/packages/asciidoc</a>.
309
 
</p>
310
 
</dd>
311
 
</dl></div>
312
 
<div class="paragraph"><p>See also <a href="userguide.html#X38">Packager Notes</a> in the <em>AsciiDoc User
313
 
Guide</em>.</p></div>
314
 
</div>
315
 
<h2 id="_microsoft_windows_installation">Microsoft Windows installation</h2>
316
 
<div class="sectionbody">
317
 
<div class="paragraph"><p>AsciiDoc is developed and tested on Linux but there seem to be quite a
318
 
few people using it on Windows.  To install AsciiDoc on Windows unzip
319
 
the distribution Zip file contents to a new folder:</p></div>
320
 
<div class="literalblock">
321
 
<div class="content">
322
 
<pre><tt>$ mkdir asciidoc
323
 
$ cd asciidoc
324
 
$ unzip ../asciidoc-8.5.2.zip</tt></pre>
325
 
</div></div>
326
 
</div>
327
 
<h2 id="_testing_your_installation">Testing your installation</h2>
328
 
<div class="sectionbody">
329
 
<div class="paragraph"><p>Test out asciidoc by changing to the AsciiDoc application directory
330
 
and convert the User Guide document (<tt>./doc/asciidoc.txt</tt>) to XHTML
331
 
(<tt>./doc/asciidoc.html</tt>):</p></div>
332
 
<div class="literalblock">
333
 
<div class="content">
334
 
<pre><tt>$ python asciidoc.py doc/asciidoc.txt</tt></pre>
335
 
</div></div>
336
 
<div class="paragraph"><p><a href="testasciidoc.html">testasciidoc</a> offers a more extensive set of
337
 
conformance tests, though you do need to create the test data before
338
 
running the tests (this in itself is a good post-install test):</p></div>
339
 
<div class="literalblock">
340
 
<div class="content">
341
 
<pre><tt>$ python ./tests/testasciidoc.py update</tt></pre>
342
 
</div></div>
343
 
</div>
344
 
</div>
345
 
<div id="footnotes"><hr /></div>
346
 
<div id="footer">
347
 
<div id="footer-text">
348
 
Version 8.5.2<br />
349
 
Last updated 2009-12-07 17:24:54 NZDT
350
 
</div>
351
 
<div id="footer-badges">
352
 
<a href="http://validator.w3.org/check?uri=referer">
353
 
  <img style="border:0;width:88px;height:31px"
354
 
    src="http://www.w3.org/Icons/valid-xhtml11-blue"
355
 
    alt="Valid XHTML 1.1" height="31" width="88" />
356
 
</a>
357
 
<a href="http://jigsaw.w3.org/css-validator/">
358
 
  <img style="border:0;width:88px;height:31px"
359
 
    src="http://jigsaw.w3.org/css-validator/images/vcss-blue"
360
 
    alt="Valid CSS!" />
361
 
</a>
362
 
<a href="http://www.mozilla.org/products/firefox/">
363
 
  <img style="border:none; width:110px; height:32px;"
364
 
       src="http://www.spreadfirefox.com/community/images/affiliates/Buttons/110x32/safer.gif"
365
 
       alt="Get Firefox!" />
366
 
</a>
367
 
</div>
368
 
</div>
369
 
</div>
370
 
</td>
371
 
</tr>
372
 
</table>
373
 
</body>
374
 
</html>