Quickstart AsciiDoc3

You don’t need admin/root-access to run AsciiDoc3: the binaries and/or the Python code files are installed in the user’s home directory.

Prerequisites

The packages are given in order of (assumed) priority. You’ll need most likely the first six.

To install, try apt/yum/rpm install dblatex or visit the corresponding homepage of the above mentioned software to learn more about the package and how to install.

Windows user may try a package manager like chocolatey.org or try cygwin or Windows Subsystem for Linux 2 (WSL2).
Other options are Docker or PyPi. Read the appropriate pages here on https://asciidoc3.org/ tab documentation (work in progress).

empty

Install

GNU/Linux

  • Download the tarball AsciiDoc3_linux_latest here, say into folder Downloads.

  • Create a new folder in your home directory, say ad3.

  • Deflate the tarball into directory ad3: tar xvfz ~/<your_username>/Downloads/tarball.gz -C ~/ad3

  • Change to the new directory: cd ~ad3.

  • You see some files and two subdirectories src and misc. The src again has a few subdirs like images, conf, doc …

  • The src contains the executables asciidoc3.bin, asciidoc3.py, a2x3.bin, and a2x3.py.

  • Be sure that these files are executable. If not, set the permissions like so for all users: chmod +x asciidoc3.py.

  • Check installation: ./asciidoc3.bin --version or ./asciidoc3.py --version or python3 asciidoc3.py --version.
    You see this output:
    asciidoc3 4.0.1

  • Yes, that’s it, go to the section First Steps below!

empty

Windows

  • Download the Windows 10/11 tarball AsciiDoc3_windows_latest here, say into folder Downloads.

  • Create a new folder in your home directory, say ad3.

  • (Do this with admin rights to keep the symlinks!) Deflate the tarball into directory ad3: tar xvfz ~/<your_username>/Downloads/tarball.gz -C ~/ad3

Note You are highly encouraged to use a tool like 7-zip or WinRar (Windows 10) - admin rights -, Windows 11 should work without other tools needed.

  • Change to the new directory: cd ~ad3.

  • You see some files and two subdirectories src and misc. The src again has a few subdirs like images, conf, doc …

  • The src contains the executables asciidoc3.exe, asciidoc3.py, a2x3.exe, and a2x3.py.

  • Be sure that these files are executable. If not, set the permissions for all users.

  • Check installation: ./asciidoc3.exe --version or ./asciidoc3.py --version or python3 asciidoc3.py --version.
    You see this output:
    asciidoc3 4.0.1

  • Especially under Windows 10 (Win 11, too, if you didn’t deflate the tar.gz with admin rights) you have to create some symlinks for convenient usage - gz-archives and/or Win 10 have limitations to handle with.
    1) Erase the files that are not the expected symlinks.
    del .\asciidoc3.conf
    del .\filters\music\images
    del .\filters\graphviz\images
    del .\doc\images
    2) Create the symlinks (with Admin-rights!).
    mklink .\asciidoc3.conf .\conf\asciidoc3.conf
    mklink /J .\filters\music\images .\images
    mklink /J .\filters\graphviz\images .\images
    mklink /J .\doc\images .\images
    Symlinks are not mandatory! You can simply copy the .\images-folder to the mentioned locations; everything will run as expected.

  • Yes, that’s it, go to First Steps!

empty

First Steps

If everything went well, you may try some examples to see AsciiDoc3 working. To do so, open a terminal, go to directory ad3/src and start

python3 ./asciidoc3.py -n -a icons -a toc doc/test.txt

Tip Windows users replace python3 with python.

./asciidoc3.py -n -a icons -a toc doc/test.txt
(if asciidoc3.py is executable)

./asciidoc3.bin -n -a icons -a toc doc/test.txt
(GNU/Linux)

./asciidoc3.exe -n -a icons -a toc doc/test.txt

You’ll find a new file doc/test.html. It shows only a few features of AsciiDoc3.

Another way to see AsciiDoc3 working is

./asciidoc3.bin -a toc -n -a icons userguide.txt

This produces the UserGuide as a HTML-file.
If you have the programs (FOP or dblatex - see above) installed, try - to make a "good-looking" pdf out of userguide.txt:

a2x3 -f pdf doc/userguide.txt
or
asciidoc3.bin --pdf=fop doc/userguide.txt

empty

Verbose Option / More Examples

If you encounter any issue (like no images: probably you have to adjust asciidoc3.conf imagesdir) or just to see what is going on when asciidoc3 / a2x3 are working, add the option verbose:
'asciidoc3.bin -v -n -a icons doc/test.txt

In the directory doc you find more files you may use as examples to study the power of AsciiDoc3.

To Top ↑