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
|
AsciiDoc Installation
=====================
NOTE: The current version of AsciiDoc requires *Python 3.5 or later*
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
http://www.python.org/.
Prerequisites
-------------
- Python 3.5+
- DocBook XSL Stylesheets
- xsltproc
- w3m
- dblatex
- FOP
- make
Installing from PyPI
--------------------
Starting from 10.0 release, AsciiDoc.py can be installed from PyPI repository
by doing the following:
$ python3 -m pip install asciidoc
Installing from the GitHub repository
-------------------------------------
The AsciiDoc repository is hosted by https://github.com[GitHub].
To browse the repository go to https://github.com/asciidoc/asciidoc-py3.
You can install AsciiDoc from the repository if you don't have an up to
date packaged version, or you want to get the latest version from the master
branch:
- Make sure you have https://git-scm.com/[Git]
installed; you can check with:
$ git --version
- Go to the directory you want to install AsciiDoc into and download
the repository. This example gets the {revnumber} tagged release:
[subs="attributes"]
$ cd ~/bin
$ git clone https://github.com/asciidoc/asciidoc-py3 asciidoc-{revnumber}
$ cd asciidoc-{revnumber}
$ git checkout {revnumber}
You now have two choices: you can run asciidoc locally from your
repository (e.g. `python3 -m asciidoc` or `python3 -m asciidoc.a2x`) or you
can use 'autoconf(1)' and 'make(1)' to perform a system-wide install. If you
wish to update your installation, run `git pull` and re-run `make(1)` to
re-install the updated version
Uninstalling AsciiDoc.py
------------------------
To uninstall AsciiDoc.py, if you installed it via PyPI, then simply do the
following:
$ python3 -m pip uninstall asciidoc
If you installed it via `make(1)`, please do the following:
$ sudo make uninstall
[[X1]]
Distribution tarball installation
---------------------------------
The distribution source tarballs can be downloaded from GitHub
releases page https://github.com/asciidoc/asciidoc-py3/releases.
If your flavor of 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 `Makefile`
that is tailored for your system. To install:
[subs="attributes"]
$ tar -xzf asciidoc-{revnumber}.tar.gz
$ cd asciidoc-{revnumber}
$ ./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 are already installed as built into the vim runtime.
[[X3]]
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:
[subs="attributes"]
$ unzip asciidoc-{revnumber}.zip
This will create the folder +asciidoc-{revnumber}+ 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
http://blog.rainwebs.net/2010/02/25/how-to-create-handsome-pdf-documents-without-frustration/[How
to Create Handsome PDF Documents Without Frustration] using
http://www.cygwin.com/[Cygwin],
http://dblatex.sourceforge.net/[dblatex] and AsciiDoc.
Testing your installation
-------------------------
To test out AsciiDoc.py, you will need to install `pytest` and `pytest-mock`
from PyPI.
Test out asciidoc by changing to the AsciiDoc application directory
and converting the User Guide document (`./doc/asciidoc.txt`) to XHTML
(`./doc/asciidoc.html`):
$ python3 asciidoc.py doc/asciidoc.txt
The link:testasciidoc.html[testasciidoc] tool offers a more extensive set of
conformance tests. You can run the tests by executing this command:
$ python3 ./tests/testasciidoc.py run
Unit tests can be run by doing:
$ python3 -m pytest
Doctests can be run by doing:
$ python3 -m asciidoc.asciidoc --doctest
Running all three of these can be accomplished through the Makefile:
$ make test
[[X2]]
Prepackaged AsciiDoc installation
---------------------------------
The following platform-specific AsciiDoc packages are available:
*Fedora Linux*::
AsciiDoc is included in Fedora Extras, which is available in
the default Fedora installation. To install asciidoc, execute the
following command:
$ yum install asciidoc
*Ubuntu / Debian*::
AsciiDoc is included in Ubuntu / Debian package manager. To install,
execute the following command:
$ apt install asciidoc
*macOS Homebrew*::
AsciiDoc has been packaged in homebrew and is installable using the
following command:
$ brew install asciidoc
See also link:userguide.html#X38[Packager Notes] in the 'AsciiDoc User
Guide'.
|
