AsciiDoc3
Text based document generation using Python 3.x

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

Tip AsciiDoc3 requires Python 3.4 (or higher) to run, it will definitely crash when using Python2.x. Probably there are few systems in the real world running with Python 3.0, 3.1, 3.2, 3.3 or 3.4 any more - these versions have reached their end of live. Please consider updating to a newer version! Python 3.5 / 3.6 / 3.7 is a good choice - you don’t need the most recent branch at all. Python is installed by default in most Unix and GNU/Linux distributions. If you don’t find an up-to-date version of Python installed it can be downloaded from the official Python website https://www.python.org/.
Warning Command line python3 obligatory! Please note: To run AsciiDoc3, the executable command python3 is a must-have. That means, typing python3 at the command line starts the Python3 executable and you see something like
$ python3
$ Python 3.7.3 (default, Apr 3 2019, 05:39:12) [GCC 8.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
In almost every Unix and GNU/Linux distribution this is a given. When not, you can easily add a symlink python3 → python3.7 (please take your current version) and add python3 to your PATH …
Windows users need probably a windows alias for python 3. For further information about AsciiDoc3 and Windows see here.

1. Obtaining AsciiDoc3

You may download the files here.
The PyPI source is here, please visit the distinct page before installing.

2. Installation

Unix, GNU/Linux, BSD, OS X

This page covers GNU/Linux and other POSIX systems (Unix, BSD, and assumably OS X) - except PyPI.
Windows users go here, - except PyPI.

You have a bundle of options to install AsciiDoc3:
- System wide (you need su/sudo/admin rights): Tarball or deb/rpm-package.
- Local in your home directory, no admin rights required (if Python3 is already installed …). Doing so, you have to use the python3 asciidoc3.py … syntax to execute AsciiDoc3. - Experienced users may consider to run AsciiDoc3 via pip in a virtual environment created with venv.

2.1. System Wide (Tarball)

2.1.1. Install

  • Download the tarball in any directory with read-write access, e.g. ~/download.

  • Open a terminal and change to ~/download (cd ~/download).

  • Deflate the tarball to a new dir, say asciidoc3-3.1.0: tar -xzf asciidoc3-3.1.0.tar.gz.

  • You see a new directory ~/download/asciidoc3-3.1.0

  • Recommended (but optional): Copy this new directory to your home directory and rename it to something like ~/ad3 (so you have less typing labour …).

  • In the terminal: change to the new directory, e.g. ~/ad3.

  • Run installscript as root/superuser: Ubuntu-like systems: sudo ./installscript (don’t forget the dot-slash) Other POSIX os like Debian, Fedora, BSD: su <password> ./installscript (don’t forget the dot-slash)

  • AsciiDoc3 is ready to use … continue here.

2.1.2. Uninstall

If you ran the AsciiDoc3 installscript as root/superuser - that means, you have directories/files like /etc/asciidoc3/*.* or /usr/share/asciidoc3/ et al. (you have used asciidoc3 -a toc -a icons -n mytext.txt or so):
1. make uninstallscript executable: chmod u+x uninstallscript,
2. su/sudo ./uninstallscript,
3. delete your local files, e.g. in ~/asciidoc3.

2.2. Local (Tarball)

2.2.1. Install

  • Download the tarball in any directory with read-write access, e.g. ~/download.

  • Open a terminal and change to ~/download (cd ~/download).

  • Deflate the tarball to a new dir, say asciidoc3-3.1.0: tar -xzf asciidoc3-3.1.0.tar.gz

  • You see a new directory ~/download/asciidoc3-3.1.0

  • Optional: Copy this directory and rename it to ~/ad3 (so you have less typing labour …)

  • In the terminal: change to the new directory, e.g. ~/ad3.

  • Start using AsciiDoc3 by using python3 asciidoc3.py -a toc -a icons -n doc/test.txt … continue here.

2.2.2. Uninstall

To uninstall local as described before makes it easy to uninstall: just delete ~/ad3. Do not forget to backup your private data.

If you have AsciiDoc3 installed local - that means, you have all files in one directory (e.g., ~/asciidoc3) and never ran installscript (you have used python3 asciidoc3.py -a toc -a icons -n mytext.txt or so): just delete the directory ~/asciidoc3 (or wherever you have installed the distribution).

2.3. Debian-like Systems

2.3.1. Install

  • Download the deb-file in any directory with read-write access, e.g. ~/download.

  • Open a terminal and change to ~/download (cd ~/download).

  • Change user to root with command su and then apt install ./asciidoc3.deb or sudo apt install ./asciidoc3.deb

  • You see a new directory ~/asciidoc3.

  • If this directory already exists the old directory is saved to ~/asciidoc3_<random_number>.

  • You may also use tools like GDebi or so to install the downloaded file asciidoc3.deb (rightclick in your FileManager).

2.3.2. Uninstall

To uninstall open a terminal, change to root and apt remove asciidoc3 or sudo apt remove asciidoc3. You can use the well-known graphical interfaces, too.

Tip Please keep in mind, that the folder ~/asciidoc3 will not be removed. Do that by yourself to make everything gone. Do not forget to backup your private data.

2.4. RPM-using Systems

2.4.1. Install

  • Download the rpm-file in any directory with read-write access, e.g. ~/download.

  • Open a terminal and change to ~/download (cd ~/download).

  • Change user to root with command su and then rpm --install ./asciidoc3-3.1.0-2.noarch.rpm

  • You’ll see a warning message package is damaged / not signed. Just ignore that, when in doubt please check the md5sum.

  • There is a new directory ~/asciidoc3.

  • If this directory already exists the old directory is saved to ~/asciidoc3_<random_number>.

  • You may also use tools like yast or so to install the downloaded file asciidoc3-3.1.0-2.noarch.rpm (rightclick in your FileManager).

2.4.2. Uninstall

To uninstall open a terminal, change to root and rpm -e asciidoc3. You can use the well-known graphical interfaces, too.

Tip Please keep in mind, that the folder ~/asciidoc3 will not be removed. Do that by yourself to make everything gone. Do not forget to backup your private data.

2.5. Testing your installation

See here.

3. Uninstall

Information is given in the apropriate chapter on this page above.