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

1. Overview

You’ll find the information you need on this page to install AsciiDoc3 via pip/pip3.
To avoid some annoying issues please consider the following annotations, especially do not forget the steps described in asciidoc3_postinstall, see here!

1.1. PyPI

Tip AsciiDoc3 PyPI works seamlessly with POSIX systems like GNU/Linux. PyPI is also available for Windows - with some minor limitations (see below). The files are avalable here.

1.2. Pip3

Before you start, be sure to have pip3 installed.

$ pip3
Usage:
  pip <command> [options]
Commands:
  install                     Install packages.
  download                    Download packages.
  ....

It’s not a must, but you may verify your version:

python3 -m pip install --upgrade pip 1
1 as root/sudo

It is impossible to cover all pip issues on every operating system out there …, when needed take a look here.

1.3. Scenarios

We have the following three scenarios - each with GNU/Linux and Windows - , see the information given in the sections below:

  • AsciiDoc3 local in the user’s virtual env: pip install asciidoc3, recommended for GNU/Linux, works unfortunately not yet smooth on Windows.

  • AsciiDoc3 local in the user’s home directory ~/.local/… or C:/Users/username, no virtual env: pip install --user asciidoc3, recommended for Windows.

  • AsciiDoc3 system wide: (admin/su/sudo) pip install asciidoc3 — definitely not recommended neither for GNU/Linux or Windows: use tarball/zip instead.

2. AsciiDoc3 Pip Install (GNU/Linux, Posix)

This is the recommended way: install AsciiDoc3 local in the user’s virtual env. Look at this example:

$ apt-get install python3-venv 1
$ python3 -m venv /home/<username>/ad3 2
$ cd /home/<username>/ad3
~ad3$ source bin/activate
(ad3): ~ad3$ pip install wheel    3
(ad3): ~ad3$ pip install asciidoc3  4
Collecting asciidoc3
  Downloading https://files.pythonhosted.org/packages/6b/e5/0bc6...cb/asciidoc3-3.1.0.tar.gz (769kB)
    100% -------| 778kB 1.1MB/s
Building wheels for collected packages: asciidoc3
  Running setup.py bdist_wheel for asciidoc3 ... done
  Stored in directory: /home/<username>/.cache/pip/wheels/15/45/eb/508...e4fe679
Successfully built asciidoc3
Installing collected packages: asciidoc3
Successfully installed asciidoc3-3.1.0  ...
  Successfully installed asciidoc3
(ad3): ~ad3$
1 as root/sudo, if not already present
2 from now on as user <username>, ad3 may be an yet inexistent new directory
3 to avoid an error in the next step: "invalid command bdist_wheel" (probably not necessary - depends on your system).
4 do NOT use option --user

The files are now installed in directory ~ad3/bin and/or ~ad3/lib/python3.5/site-packages/asciidoc3.

Unfortunately we are not ready now! AsciiDoc3 comes with a bundle of configuration files. They are now hidden in your venv-directory
(e.g. ~ad3/lib/python3.5/site-packages/asciidoc3/asciidoc3.conf).
If you try …

(ad3):~/ad3$ asciidoc3
asciidoc3: no help topics found
(ad3):~/ad3$

AsciiDoc3 does not know where the files are. And a second issue pops up: pip installs no symlinks which are needed for convenient work (e. g., the images are not found when running a filter).
But there is a solution: run asciidoc3_postinstall:

(ad3):~/ad3$ asciidoc3_postinstall 1
1 no superuser permission necessary, start this as normal user

You’ll find two new directories:
~/asciidoc3
~/.asciidoc3 (with dot and therefore hidden)
What is this good for? These two directories are symlinks and do not waste any noteworthy memory. And now we can work as usual:

(ad3):~/ad3$ cd
(ad3):~$ cd asciidoc3
(ad3):~/asciidoc3$ cd doc
(ad3):~/asciidoc3/doc$ asciidoc3 -a toc -a icons -n -v test.txt
asciidoc3: reading: /home/ttest/.asciidoc3/asciidoc3.conf
...
asciidoc3: test.txt: line 1: evaluating: {template:toc}
(ad3):~/asciidoc3/doc$ asciidoc3 -a toc -a icons -n -v userguide.txt
asciidoc3: reading: /home/ttest/.asciidoc3/asciidoc3.conf
...
asciidoc3: userguide.txt: line 6222: evaluating: {counter:appendix-number:A}
(ad3):~/asciidoc3/doc$
(ad3):~/asciidoc3/doc$ a2x3 -f pdf -v test.txt
...
(ad3):~/asciidoc3/doc$ a2x3 -f pdf -v --fop userguide.txt
...

Yes it works! You can step to the information given on page quickstart.

Uninstall

This is almost as easy as

(ad3):~$ pip uninstall asciidoc3

You’ll get a message like …

Uninstalling asciidoc3-3.1.0:
    /home/<username>/ad3/bin/a2x3
    ...
    Proceed (y/n)? y
    Successfully uninstalled asciidoc3-3.1.0
(ad3):~$ deactivate 1
:~$
1 deactivate ends your venv-session.

But AsciiDoc3 is not gone. Do not forget to remove your manually added files, the symlinks, and directories:
- ~/asciidoc
- ~/.asciidoc
- some files in ~<username>/ad3/lib/python3.5/site-packages/asciidoc3

Why have we to do this? pip knows nothing about the two asciidoc3 directories and about the symlinks in ../site-packages/asciidoc3 since we added them by our non-pip script asciidoc3_postinstall. So we have to clean up by ourselves.

2.2. AsciiDoc3 in directory ~/.local

You may of course install AsciiDoc3 local without using a virtual enviroment, i.e., you make no use of venv. Check pip running the latest version, see above.
In this case don’t forget to add option --user when using pip:

$ pip install --user asciidoc3 1
1 start this as a normal user

We have the same issue as described in the previous section, the conf-files and the images are hidden.
In addition you may see the message

...
The scripts a2x3, asciidoc3 and asciidoc3_postinstall are installed in '/home/<username>/.local/bin' which is not on PATH. ...
...

This is a known downside of the local pip --user command and has nothing to do with AsciiDoc3. To add the given directory to your PATH:

$ PATH=$PATH:/home/<username>/.local/bin
$ export PATH
$ echo $PATH 1
1 to verify that’s all ok

This is valid only for the current session. To make it permanently, add the first two lines to ~/.bashrc and logout/login (depends on your system configuration).
All right, everything we need is executable; go to the given directory with all the AsciiDoc3-files:

~$: cd /home/<username>/.local/bin
~/.local/bin$ ./asciidoc3_postinstall 1
1 Do not forget the dot slash ./ before asciidoc3_postinstall.

Or even more simple

~$: asciidoc3_postinstall 1
1 from the user’s home directory

You’ll find two new directories:
~/asciidoc3
~/.asciidoc3 (with dot and therefore hidden)

Yes, now we can start using AsciiDoc3

$ cd ~/asciidoc/doc
$ asciidoc3 -n -a icons -a toc -o test.html test.txt

BTW, you may start AsciiDoc3 in a second way:

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

and so on … Follow the steps described here.

Uninstall

This is almost as easy as

$ pip uninstall asciidoc3

You’ll get a message like …

Uninstalling asciidoc3-3.1.0:
  Would remove:
    /home/<username>/.local/bin/a2x3
    ...
    /home/<username>/.local/lib/python3.5/site-packages/asciidoc3/*
  Would not remove (might be manually added):
    /home/<username>/.local/lib/python3.5/site-packages/asciidoc3/doc/test.html
    /home/<username>/.local/lib/python3.5/site-packages/asciidoc3/doc/test.pdf
    /home/<username>/.local/lib/python3.5/site-packages/asciidoc3/doc/userguide.html
Proceed (y/n)? y
  Successfully uninstalled asciidoc3-3.1.0

But AsciiDoc3 is not gone. Do not forget to remove your manually added files, the symlinks, and directories:
- ~/asciidoc
- ~/.asciidoc
- some files in /home/<username>/.local/lib/python3.5/site-packages/asciidoc3

Why have we to do this? pip knows nothing about the two asciidoc3 directories and about the symlinks in ../site-packages/asciidoc3 since we added them by our non-pip script asciidoc3_postinstall. So we have to clean up by ourselves.

2.3. Pip system wide: Don’t do this!

This is not recommended, but - at your choice, of course - possible. You are on your own to manage the symlinks in a proper way.
If you like to install system wide you better choose the tarball or the deb/rpm package; download here.

(root su/sudo): pip install asciidoc3 1
1 doing so makes no sense …

The files are installed in the directories /usr/local/bin/asciidoc3 and /usr/local/lib/python3.5/dist-packages/asciidoc3. Script asciidoc3_postinstall does nothing when running as root!

2.4. asciidoc3_postinstall

To run asciidoc3_postinstall immediately after install via pip is highly recommendable as described before.
Python’s setuptools and pip do not support symlinks. The script sets the appropriate relative symlinks inside the AsciiDoc3-directories to make the images available from the diverse subdirectories. You may skip this, but in this case you have to set manually the options in the command line or in the conf-files (a very annoying thing btw!).
In a second step asciidoc3_postinstall creates the new directories ~/.asciidoc3 and ~/asciidoc3, which are both symlinks to directory asciidoc3 created via pip.
To have these two symlinks, which spend no aditional disk space, makes AsciiDoc3 available for the user - do not delete these directories.

3. AsciiDoc3 Pip Install (Windows)

All Windows-users please look here to see how to install the additional software you need to produce pdf’s and so on …

3.1. AsciiDoc3 and venv on Windows

This is the recommended way: install AsciiDoc3 local in the user’s virtual env. Look at this example (somme whitespace added)- username is of course your username and ad3 is the directory where the virtual Python3 will live:

C:\Users\username>   "C:\Program Files (x86)\Python37-32\python" -m venv C:\Users\username\ad3
C:\Users\username>    cd ad3
C:\Users\username\ad3>     Scripts\activate
(ad3) C:\Users\username\ad3>   pip install asciidoc3
...
Installing collected packages: asciidoc3
  Running setup.py install for asciidoc3 ... done
Successfully installed asciidoc3-3.1.0.post4
(ad3) C:\Users\username\ad3>  asciidoc3 1
asciidoc3: FAILED: Missing asciidoc3 command: C:\Users\bge\ad3\Scripts\asciidoc3
(ad3) C:\Users\username\ad3>  asciidoc3_postinstall
created symlink c:\users\username\ad3\\asciidoc3\filters\music\images <<===>> c:\users\username\ad3\\asciidoc3\images
created symlink c:\users\username\ad3\\asciidoc3\filters\graphviz\images <<===>> c:\users\username\ad3\\asciidoc3\images
created symlink c:\users\username\ad3\\asciidoc3\doc\images <<===>> c:\users\username\ad3\\asciidoc3\images
created symlink c:\users\username\ad3\\asciidoc3 <<===>> c:\users\username\ad3\lib\site-packages\asciidoc3
        1 file copied.
created symlink C:\Users\username\.asciidoc3 <<===>> c:\users\username\ad3\lib\site-packages\asciidoc3
(ad3) C:\Users\username\ad3>  cd asciidoc3
(ad3) C:\Users\username\ad3\asciidoc3>  cd doc
(ad3) C:\Users\username\ad3\asciidoc3\doc>  asciidoc3
Man page:     asciidoc3 --help manpage
Syntax:       asciidoc3 --help syntax
(ad3) C:\Users\username\ad3\asciidoc3\doc>   asciidoc3 -a toc -a icons -n test.txt
(ad3) C:\Users\username\ad3\asciidoc3\doc>   asciidoc3 -a toc -a icons -n userguide.txt
(ad3) C:\Users\username\ad3\asciidoc3\doc>   a2x3 -f pdf --no-xmllint --fop test.txt
(ad3) C:\Users\username\ad3\asciidoc3\doc>
...
(ad3) C:\Users\username>   deactivate
C:\Users\username>
1 Unfortunately we are not ready now! AsciiDoc3 comes with a bundle of configuration files. They are now hidden in your venv-directory. AsciiDoc3 does not know where the files are. But there is a solution: run asciidoc3_postinstall

You’ll find two new directories:
C:\Users\username\.asciidoc3 (with dot and therefore hidden)
C:\Users\username\ad3\asciidoc3
These two directories are symlinks and do not waste any noteworthy memory. And now we can work as usual. You can step to the information given on page quickstart.

Uninstall

Unfortunately this is not as easy as we know it:

(ad3) C:\Users\username\ad3> pip uninstall asciidoc3 1
1 Don’t do this!

You’ll get a error message like …

...
   c:\users\username\ad3\scripts\asciidoc3_postinstall.exe
   c:\users\username\ad3\scripts\asciidoc3_postinstall.exe.manifest
Proceed (y/n)? y
Exception:
Traceback (most recent call last):
  File "C:\Program Files (x86)\Python37-32\lib\shutil.py", line 563, in move
    os.rename(src, real_dst)
FileNotFoundError: [WinError 3] ...

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "C:\Program Files (x86)\Python37-32\lib\shutil.py", line 120, in copyfile
    with open(src, 'rb') as fsrc:
FileNotFoundError: [Errno 2] No such file or directory: ...

We have to delete the files manually since we changed the pip-installed layout by executing asciidoc3_poistinstall. pip knows nothing about the two new asciidoc3 directories and about the symlinks. So we have to clean up by ourselves.

Windows PowerShell
PS C:\Users\username> cd ad3
PS C:\Users\username\ad3> rd -Recurse -Force ..\.asciidoc3
PS C:\Users\username\ad3> rd -Recurse -Force asciidoc3
PS C:\Users\username\ad3> rd -Recurse -Force Lib\site-packages\asciidoc3*
PS C:\Users\username\ad3> rd -Recurse -Force Scripts\asciidoc3*
PS C:\Users\username\ad3> rd -Recurse -Force Scripts\a2x3*
PS C:\Users\username\ad3>

Or the same at one single line

Windows PowerShell
PS C:\Users\username> cd ad3
rd -Recurse -Force ..\.asciidoc3; rd -Recurse -Force asciidoc3; rd -Recurse -Force Lib\site-packages\asciidoc3*; rd -Recurse -Force Scripts\asciidoc3*; rd -Recurse -Force Scripts\a2x3*
PS C:\Users\username\ad3>

3.2. AsciiDoc3 pip without venv

You may of course install AsciiDoc3 local without using a virtual enviroment, i.e., you make no use of venv. Check pip running the latest version, see above.
In this case don’t forget to add option --user when using pip:

$ pip install --user asciidoc3 1
1 start this as a normal user

We have the same issue as described in the previous section, the conf-files and the images are hidden.
In addition you may see the message

...
The scripts a2x3, asciidoc3 and asciidoc3_postinstall are installed in '...<username>\AppData\Roaming\Python\Python37\Scripts' which is not on PATH. ...
...

This is a known downside of the local pip --user command and has nothing to do with AsciiDoc3. To add the given directory to your PATH please refer to your documentation, take a look here or look for PATH in your start menu…
Sometimes you have to logout/login before you can go on. All right, everything we need is executable:

C:\Users\username\>  asciidoc3_postinstall
... c:\users\username\appdata\roaming\python\python37\site-packages\asciidoc3\filters\music\images <<===>> c:\users\username\appdata\roaming\python\python37\site-packages\asciidoc3\images
... c:\users\username\appdata\roaming\python\python37\site-packages\asciidoc3\filters\graphviz\images <<===>> c:\users\username\appdata\roaming\python\python37\site-packages\asciidoc3\images
... c:\users\username\appdata\roaming\python\python37\site-packages\asciidoc3\doc\images <<===>> c:\users\username\appdata\roaming\python\python37\site-packages\asciidoc3\images
... C:\Users\username\asciidoc3 <<===>> c:\users\username\appdata\roaming\python\python37\site-packages\asciidoc3
... C:\Users\username\.asciidoc3 <<===>> c:\users\username\appdata\roaming\python\python37\site-packages\asciidoc3
C:\Users\username\>
...

You’ll find two new directories:
~/asciidoc3
~/.asciidoc3 (with dot and therefore hidden)

Yes, now we can start using AsciiDoc3

C:\Users\username\> cd asciidoc\doc
C:\Users\username\asciidoc\doc> asciidoc3 -n -a icons -a toc -o test.html test.txt

and so on … Follow the steps described here.

Uninstall

This is almost as easy as

C:\Users\username> pip uninstall asciidoc3

You’ll get a message like …

C:\Users\username>  pip uninstall asciidoc3
Uninstalling asciidoc3-3.1.0.post4:
  Would remove:
    c:\users\username\appdata\roaming\python\python37\scripts\a2x3-script.py
    c:\users\usernamebge\appdata\roaming\python\python37\scripts\a2x3.exe
...
    c:\users\username\appdata\roaming\python\python37\site-packages\asciidoc3\xhtml11.conf
Proceed (y/n)? y
  Successfully uninstalled asciidoc3-3.1.0.post4

C:\Users\username>

But AsciiDoc3 is not gone. Do not forget to remove your manually added files, the symlinks, and directories:
- ~/asciidoc
- ~/.asciidoc
- some files in /home/<username>/.local/lib/python3.5/site-packages/asciidoc3

Why have we to do this? pip knows nothing about the two asciidoc3 directories and about the symlinks in ../site-packages/asciidoc3 since we added them by our non-pip script asciidoc3_postinstall. So we have to clean up by ourselves.

C:\Users\username>  rd asciidoc3

C:\Users\username>  rd .asciidoc3

C:\Users\username>  del C:\Users\bge\AppData\Roaming\Python\Python37\Scripts\a2x3

C:\Users\username>  del C:\Users\bge\AppData\Roaming\Python\Python37\Scripts\asciidoc3

C:\Users\username>  rd /Q /S C:\Users\bge\AppData\Roaming\Python\Python37\site-packages\asciidoc3

C:\Users\username>
Tip Only versions downloaded before 2019-May-9! Workaround for error message FAILED: conf-file asciidoc3.conf missing:
Add a folder ~\.asciidoc3 in your root directory, which is a symlink to …\asciidoc3 in your python ..\site-packages\asciidoc3
Type as admin:
mklink /J c:\users\username\.asciidoc3 c:\users\username\AppData\Roaming\Python\Python35\site-packages\asciidoc3
or wherever your site-packages live (to check this: pip show asciidoc3)
Tip Only versions downloaded before 2019-May-9! Workaround for error FOP-generated PDF’s show the title twice:
Use python3 ..\a2x3.py -f pdf --no-xmllint --fop test.txt.

4. Anaconda and AsciiDoc3

Sorry, this was not tested yet … trying to make up leeway asap.