1. Start with AsciiDoc3
-
You don’t need admin/root-access to try AsciiDoc3: install local and/or via venv or via pip.
This is the recommended way. -
Some users want to install system wide: download the tarball / deb- / rpm-package / zip-file of the current AsciiDoc3 distribution, see here.
-
After installation you see a new directory '~/asciidoc3, see here.
-
Details are given here; info about uninstalling, too.
AsciiDoc3 comes with NO dependencies to keep it as simple as possible. Installing assumes that Python3 is available: if not, it fails.
If you want more than producing html-output (PDF, filter like Lilypond, Highlight, Pygments, Graphviz, w3m/lynx …) you’ll need the following packages:
-
dblatex http://dblatex.sourceforge.net/
-
xsltproc http://xmlsoft.org/xslt/
-
xmllint http://xmlsoft.org
-
graphviz https://www.graphviz.org/
-
imagemagick https://www.imagemagick.org/
-
lilypond http://lilypond.org/ !Previous versions depended on Python 2.x This may be a security hole!
The packages are given in order of (assumed) priority. You’ll need most likely the first five: I confess to have never heard before about the w3m text-browser.
To install, try apt install dblatex or rpm --install dblatex and so on, or visit the corresponding homepage of the above mentioned software to learn more about the package and how to install.
 | a lot of data to download (> 300 MB)! |
 | barely the same (FOP needs a Java-runtime)! |
2. Testing your installation
In your new directory, e.g. asciidoc3, you’ll find the following input files:
- ./doc/test.txt: a small document to see everything’s ok (→ asciidoc3.py works …),
- ./doc/userguide.txt: this is nothing else than the AsciiDoc3-User Guide.
2.1. First Test
Open a terminal, go to your directory and start
$ cd ~/asciidoc3/doc
$ python3 ../asciidoc3.py -n -a icons -a toc -o test.html test.txt
|
Windows users replace python3 with python. |
or, when you have installed AsciiDoc3 system wide or via venv
$ asciidoc3 -n -a icons -a toc -o test.html test.txtYou’ll find a new file test.html. It shows only a few features of AsciiDoc3.
2.2. UserGuide
Open a terminal, go to your directory and start
$ cd ~/asciidoc3/doc
$ python3 ../asciidoc3.py -a toc -n -a icons -o userguide.html userguide.txtor
$ asciidoc3 -a toc -n -a icons -o userguide.html userguide.txtThe new file userguide.html contains the current version of the user guide. Processing userguide.txt makes use of many AsciiDoc3-features.
To make a "good-looking" pdf out of userguide.txt, try
$ a2x3 -f pdf userguide.txtor
$ python3 ../a2x3.py -f pdf userguide.txtTo produce an alternative slightly different PDF you may use option fop - this requires that you have installed fop.
$ a2x3 -f pdf --fop userguide.txtor
$ python3 ../a2x3.py -f pdf --fop userguide.txt2.3. Verbose Option
To see what is going on when asciidoc3.py or a2x3.py works, add the option verbose:
$ asciidoc3 -v -n -a icons -o test.html test.txt
$ a2x3 -f pdf -v --fop userguide.txt2.4. More Examples and Further Information
In the directory ~/asciidoc3/doc you find some more files you may use as examples to study the features of AsciiDoc3.
|
|
Even if you don’t want to test your own version of AsciiDoc3, it’s a good idea to study the huge amount of files produced by |
$ cd ./tests
$ python3 testasciidoc3.py --force updateYou’ll see a lot of files written to ./tests/data - they cover all the features of AsciiDoc3. Explore yourself!
