AsciiDoc3
Text based document generation using Python 3.x

»Home  »User Guide  »Blog  »Quickstart  »Download  »Install  »PyPI  »Windows  »Cheatsheet  »Release Notes  »Contact / Donate  »Imprint / Impressum / Datenschutz / Privacy

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.

  • Be sure python3 is in your PATH and starts Python3, see here.
    Please note: This is a given for Linux users, Windows users installing local with venv do not need to care about, too.

  • Details are given here; info about uninstalling, too.

Dependencies and other Packages

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:

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.

1 a lot of data to download (> 300 MB)!
2 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 ~/asciidoc/doc

$ python3 ../asciidoc3.py -n -a icons -a toc -o test.html test.txt

or, when you have installed AsciiDoc3 system wide or via venv

$ asciidoc3 -n -a icons -a toc -o test.html test.txt

You’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.txt

or

$ asciidoc3 -a toc -n -a icons -o userguide.html userguide.txt

The 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.txt

or

$ python3 ../a2x3.py -f pdf userguide.txt

To produce an alternative slightly different PDF you may use option fop - this requires that you have installed fop.

$ a2x3 -f pdf --fop userguide.txt

or

$ python3 ../a2x3.py -f pdf --fop userguide.txt

2.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.txt

2.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.

Tip 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 update

You’ll see a lot of files written to ./tests/data - they cover all the features of AsciiDoc3. Explore yourself!

3. asciidoc3.conf required

Experienced AsciiDoc (Python2) users please note:
The use of a file named asciidoc.conf is not allowed in AsciiDoc3 - a file with this name will be ignored. Use asciidoc3.conf instead.