PyPI AsciiDoc3

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 / pip /pip3

AsciiDoc3 pip pip3 PyPI works seamlessly with POSIX systems like GNU/Linux and with Windows. The files are available here, but you may install the packages easily with pip, see the next section.

1.2. Pip3

Before you start, be sure to have pip3 installed.

$ pip3 -V

pip 20.0.2 from /usr/lib/python3/dist-packages/pip (python 3.8)

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

python3 -m pip install --upgrade pip

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 and for Windows.
AsciiDoc3 local in the user’s home directory ~/.local/… or C:/Users/username, no virtual env: pip install --user asciidoc3.
This is a efficient way, too; works for GNU/Linux and Windows.
You want to provide AsciiDoc3 system wide for all users? That’s not a job for pip - use tarball/deb/rpm/zip instead; download here.

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

2.1. Recommended: AsciiDoc3 and venv

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

su/sudo $  apt-get install python3-venv 

$ python3 -m venv /home/<username>/ad3 
$ cd /home/<username>/ad3
~ad3$ source bin/activate
(ad3): ~ad3$ pip install wheel    
(ad3): ~ad3$ pip install asciidoc3  
Collecting asciidoc3
  Downloading https://files.pythonhosted.org/packages/6b/e5/0bc6...cb/asciidoc3-3.2.3.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.2.3  ...
  Successfully installed asciidoc3
(ad3): ~ad3$

	as root/sudo, if not already present
	from now on as user <username>. ad3 may be a yet inexistent new directory
	to avoid an error in the next step: "invalid command bdist_wheel" (in most cases not necessary since we provide a whl-file). See the error message given below.
	do NOT use option --user

When you see this error message:
Do pip install wheel in your venv, see above

 ERROR: Command errored out with exit status 1:
   command: /home/username/ad3/bin/python3 -u -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'/tmp/pip-install-inwe67og/asciidoc3/setup.py'"'"'; __file__='"'"'/tmp/pip-install-inwe67og/asciidoc3/setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' bdist_wheel -d /tmp/pip-wheel-cr4dpf1o
 ...
  error: invalid command 'bdist_wheel'
 ...
 running install
    running build
    running install_data
    creating /asciidoc3
    error: could not create '/asciidoc3': Permission denied

The files are now installed in directory ~ad3/bin and/or ~ad3/lib/python3.8/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.8/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

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/<username>/.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/<username>/.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.

Updating

The save way is to uninstall before start installing a newer release - see next section. But this should work, too:

...
(ad3): pip install asciidoc3 -U
...
  Found existing installation asciidoc 3.x.y
  Uninstalling asciidoc3 ...
  Installing collected packages: asciidoc3
  Successfully uninstalled asciidoc3-3.x.y
Successfully installed asciidoc3

Check the new version: asciidoc3 --version

Uninstall

This is almost as easy as

(ad3):~$ pip uninstall asciidoc3

You’ll get a message like …

Uninstalling asciidoc3-3.2.3:
/home/<username>/ad3/bin/a2x3
    ...
    Proceed (y/n)? y
    Successfully uninstalled asciidoc3-3.2.3
(ad3):~$ deactivate 
:~$

deactivate ends your venv-session.

But AsciiDoc3 is not gone. Do not forget to remove your manually added files, the symlinks, and directories:
- ~/asciidoc3
- ~/.asciidoc3
- some files in ~<username>/ad3/lib/python3.8/site-packages/asciidoc3 (to be precise, the entire folder)

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

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. Add the given directory to your PATH:

$ PATH=$PATH:/home/<username>/.local/bin
$ export PATH
$ echo $PATH

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

Do not forget the dot slash ./ before asciidoc3_postinstall.

Or even more simple

~$: asciidoc3_postinstall

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 ~/asciidoc3/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.

Updating

The save way is to uninstall before start installing a newer release - see next section. But this should work, too:

...
$ pip install asciidoc3 -U
...
  Found existing installation asciidoc 3.x.y
  Uninstalling asciidoc3 ...
  Installing collected packages: asciidoc3
  Successfully uninstalled asciidoc3-3.x.y
Successfully installed asciidoc3

Check the new version: asciidoc3 --version

Uninstall

This is almost as easy as

$ pip uninstall asciidoc3

You’ll get a message like …

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

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

2.3. asciidoc3_postinstall

To run asciidoc3_postinstall immediately after install via pip is highly recommendable as described before (or to say it in other words, to run asciidoc3_postinstall is a must).
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 additional disk space, makes AsciiDoc3 available for the user - do not delete these directories.

3. AsciiDoc3 Pip Install (Windows)

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

3.1. AsciiDoc3 and venv on Windows

This is the recommended way: install AsciiDoc3 local in a user’s virtual env. Look at this example (some whitespace added) - username is of course your username and ad3 is the directory where the virtual Python will live. Please note: you don’t need the Python3 executable yet, asciidoc3_postinstall arranges this for you.

C:\Users\username> python -m venv 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.2.3
(ad3) C:\Users\username\ad3>  asciidoc3 
asciidoc3: FAILED: Missing asciidoc3 command: C:\Users\username\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>

	Use python and not python3 - even if the latter is available.
	To say it once again: no option --user here.
	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.

Updating

The save way is to uninstall before start installing a newer release - see next section. But this should work, too:

ad3) C:\Users\username\ad3\ $ pip install asciidoc3 -U
...
  Found existing installation asciidoc 3.x.y
  Uninstalling asciidoc3 ...
  Installing collected packages: asciidoc3
  Successfully uninstalled asciidoc3-3.x.y
Successfully installed asciidoc3

Check the new version: asciidoc3 --version

Uninstall

Unfortunately this is not as easy as we know it:

(ad3) C:\Users\username\ad3> pip uninstall asciidoc3 
...
   c:\users\username\ad3\scripts\asciidoc3_postinstall.exe
   c:\users\username\ad3\scripts\asciidoc3_postinstall.exe.manifest
...
Proceed (y/n)? y
  Successfully uninstalled asciidoc3-3.2.3

But we are not ready now and have to delete some 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

$ pip install --user asciidoc3

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\python38\site-packages\asciidoc3\filters\music\images <<===>> c:\users\username\appdata\roaming\python\python38\site-packages\asciidoc3\images
... c:\users\username\appdata\roaming\python\python38\site-packages\asciidoc3\filters\graphviz\images <<===>> c:\users\username\appdata\roaming\python\python38\site-packages\asciidoc3\images
... c:\users\username\appdata\roaming\python\python38\site-packages\asciidoc3\doc\images <<===>> c:\users\username\appdata\roaming\python\python38\site-packages\asciidoc3\images
...
... C:\Users\username\asciidoc3 <<===>> c:\users\username\appdata\roaming\python\python38\site-packages\asciidoc3
... C:\Users\username\.asciidoc3 <<===>> c:\users\username\appdata\roaming\python\python38\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.2.3:
  Would remove:
    c:\users\username\appdata\roaming\python\python37\scripts\a2x3-script.py
    c:\users\username\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.2.3

C:\Users\username>

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

C:\Users\username>  rd asciidoc3
C:\Users\username>  rd .asciidoc3
C:\Users\username>  del C:\Users\username\AppData\Roaming\Python\Python38\Scripts\a2x3
C:\Users\username>  del C:\Users\username\AppData\Roaming\Python\Python38\Scripts\asciidoc3
C:\Users\username>  rd /Q /S C:\Users\username\AppData\Roaming\Python\Python38\site-packages\asciidoc3
C:\Users\username>

4. Anaconda and AsciiDoc3

Works without any problems! Build a new env, activate it and then install AsciiDoc3 via pip install asciidoc3.
For anything else look at the sections above.