AsciiDoc3
Text based document generation using Python 3.x

»Home  »User Guide  »Download  »Install  »Quickstart  »AsciiDoc3port  »Release Notes  »Blog  »Donate  »Contact  »Legal Stuff

Note AsciiDoc3 requires Python 3.0 or newer to run. AsciiDoc3 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 or 3.3 any more. Python 3.4 / 3.5 / 3.6 / 3.7 is a good choice - but 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. In almost every Unix and GNU/Linux distribution this is a given. When not, you can easily add a symlink python3 → python3.6 (please take your current version) and add python3 to your PATH …
Windows users need probably a windows alias for python 3 - use this as a search phrase on the net. You can find more information about this issue here:
https://docs.python.org/3/using/windows.html
https://stackoverflow.com/questions/38532440/running-both-python-2-7-and-3-5-on-pc

1. Obtaining AsciiDoc3

See here.

2. Installation

2.1. Unix, GNU/Linux, BSD (and probably OS X, too)

Posix systems (Unix, GNU/Linux, BSD, and assumably OS X) go here.

You have two options to install AsciiDoc3:
- system wide (you need su/sudo/admin rights)
- 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.

2.1.1. Install system wide (default)

  • 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.0.2: tar -xzf asciidoc3-3.0.2.tar.gz.

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

  • 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: sudo ./installscript Other POSIX os like Debian, Fedora, BSD: su <password> ./installscript

  • AsciiDoc3 is ready to use … continue here.

  • To avoid some configuration steps during daily routine you may consider the following directory layout: Copy/rename the deflated directory ~/download/asciidoc3-3.0.1 to ~/.asciidoc3 (with a dot - not visible to ls) and create a symlink to directory ~/ad3. This is because asciidoc3.py tries to find some configuration files in ~/.asciidoc3. See Userguide 26.11. Configuration file names, precedence and locations. But that’s optionally, everything works somehow or other. Symlinks don’t work on partitions formatted as fat/vfat.

2.1.2. Install local

  • 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.0.2: tar -xzf asciidoc3-3.0.2.tar.gz.

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

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

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

  • Start using AsciiDoc3: … continue here.

  • To avoid some configuration steps during daily routine you may consider the following directory layout: Copy/rename the deflated directory ~/download/asciidoc3-3.0.1 to ~/.asciidoc3 (with a dot - not visible to ls) and create a symlink to directory ~/ad3. This is because asciidoc3.py tries to find some configuration files in ~/.asciidoc3. See Userguide 26.11. Configuration file names, precedence and locations. But that’s optionally, everything works somehow or other. Symlinks don’t work on partitions formatted as fat/vfat.

  • To install local as described before makes is easier to uninstall: just delete ~/ad3.

2.2. Windows (pending)

Zip Installation: Windows users may go here.
AsciiDoc3 is developed and tested on GNU/Linux. I have only limited access to machines with Windows OS. But as said in the AsciiDoc v2 homepage, there seem to be quite a few people using it on Windows (I use the informations given there:).

  • To install AsciiDoc3 on Windows unzip the Zip file: unzip asciidoc3-3.0.2.zip,

  • this will create the folder asciidoc3-3.0.2 containing the asciidoc3.py and a2x3.py executables along with configuration files,

  • try python3 asciidoc3.py -n -a icons -o ad3test.html ad3test.txt… (continue here).

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. If possible, I give you more information about this later on if this website will be updated.

2.3. Testing your installation

See here.

3. Uninstall

(this information is also given in file UNINSTALL of the AsciiDoc3 distribution)

3.1. Uninstall local installation

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

3.2. Uninstall system wide installation

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.