quickstart

Quickstart AsciiDoc3

You want to use the power of the AsciiDoc(3)-Markup-Language?
There are many ways to take advantage of it:

You want HTML output - nothing more and nothing less?
GNU/Linux goes here, Windows there.
You need HTML and/or PDF output?
GNU/Linux goes here, Windows there.
You want everything: HTML, PDF, PDF (alternative route), plain text, music notation, complex mathematical formulas, ePub, manpage ..?
GNU/Linux goes here, Windows there.

HTML output only (GNU/Linux)

Prerequisites: you need Python3.10 (or higher) installed on your machine. Probably all systems have this feature since they were installed.
Download (or curl or wget) the tarball asciidoc3-latest.tar.gz, say into folder Downloads.
Create a new folder in your home directory, say ad3.
Deflate the tarball into directory ad3: tar xvfz ~/Downloads/asciidoc3-latest.tar.gz -C ~/ad3
Change to the new directory: cd ~ad3.
In ~/ad3 you see among others the files asciidoc3.py, a2x3.py and the subdirectories images, conf, doc, filters, and tests.
Be sure that all files *.py are executable - that should be the case. If not, set the permissions like so for all users: chmod +x asciidoc3.py.
Check installation: ./asciidoc3.py --version or python3 asciidoc3.py --version.
You’ll see this output: asciidoc3 4.0.2
Yes, that’s it, go to the section First Steps below!

This is probably the easiest way - here some additional hints:

Of course you can install in one of the other ways: e.g. via the »latest« or »small« Docker image.
Or you add a symbolic link link so:
(sudo/su) ln --symbolic /home/<username>/<path-to-asciidoc3-folder>/asciidoc3.py /usr/bin/asciidoc3 to establish the command asciidoc3 for convenience.
You may delete some unneccessary files: ./doc/readme-vim, directory tests, lang.conf files, (x)html(4).conf etc. If you need them back any later, download from the GitLab Repo.

HTML and/or PDF (GNU/Linux)

That is almost the same as described in the previous section. In addition you need a tool to generate PDFs. AsciiDoc3 handles Apache’s FOP or the dblatex (docbook to latex) way. Install the first with apt/yum install fop, the second with apt/yum install dblatex.
The corresponding commands to generate a PDF are:
asciidoc3 --pdf=fop doc/test.txt
a2x3 -f pdf doc/test.txt
See the userguide for more info.

Output everything (GNU/Linux)

First option: use the Docker latest image. Easy!
Second option: install all the needed programs. Look here.

HTML output only (Windows)

Setup Exe

This is the recommended way:

Download the install file AsciiDoc3-402-setup.exe, say into folder Downloads. Start installing in the usual way by doubelclicking. Default folder is AsciiDoc3 in your home directory, but you may change that.
Prerequisites: you need Python3.10 (or higher) installed on your machine. If not yet present, look at Python for Windows

No need of a Python interpreter if you use asciidoc3.exe - contains an embedded Python! See the next lines.

Tarball

Of course you may make use of the tarball, but the just mentioned AsciiDoc3-402-setup.exe gives you the same data.

Download asciidoc3-latest.tar.gz, say into folder Downloads. Yes, that is the same file as for the GNU/Linux installation.
Create a new folder in your home directory, say ad3.
Deflate the tarball with admin-rights into directory ad3: tar xvfz C:\<your_username>\Downloads\asciidoc3-latest.tar.gz -C C:\<your_username>\ad3
If you miss to work as admin you’ll see five lines Can’t create … Invalid argument. That’s no problem, we’ll handle it eight lines below …
Change to the new directory: cd ~ad3.
In ~\ad3 you see some files and subdirectories images, conf, doc …
The main dir contains the executables asciidoc3.py, and a2x3.py.
(If you want to use asciidoc3.exe with embedded Python interpreter, look for AsciiDoc3-402-setup.exe, see above)
Check installation: python asciidoc3.py --version; you’ll see this output: asciidoc3 4.0.2.
Yes, that’s it, go to the section First Steps below!
What about the lines Can’t create … Invalid argument? These are symlinks which are not resolved by Windows tar when using it without admin rights. You can do the following to get things right: delete the wrong links and add symlinks manually.

1) Erase the files that are not the expected symlinks, if they exist.
del .\asciidoc3.conf
del .\conf\text.conf
del .\filters\music\images
del .\filters\graphviz\images
del .\doc\images

2) Create the symlinks with admin-rights in cmd.exe only! mklink is not implemented in PowerShell - nobody knows why.
mklink .\asciidoc3.conf .\conf\asciidoc3.conf
mklink .\conf\text.conf .\conf\backends\text.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.

Go to the section First Steps below!

Of course you can install in one of the other ways.

Via the »latest« or »small« Docker/Podman image, the first is recommended. See section docker installation.

HTML and/or PDF (Windows)

[Pending] To compute a PDF AsciiDoc3 needs a tool like Apache’s FOP. Installation is a little bit tricky: (Info asap)

Output everything (Windows)

A case for Docker full image. See section docker installation.

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

Windows users might have to replace python3 with python or use asciidoc3.exe.

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

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

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

Write Your Own Text!

Now it’s time to write your own AsciiDoc3-Text and compute it!
Write your text, say mytext.txt with your favorite editor (Vim, Emacs, VSCode, … or whatever you prefer) and save it as a plain text file in directory ./src/doc. Save the images to ./images. And then:
python3 ./asciidoc3.py -n -a icons -a toc doc/mytext.txt or ./asciidoc3.py -n -a icons -a toc doc/mytext.txt The HTML output mytext.html lives in ./src/doc.
You can use other directories as well, but you have to edit asciidoc3.conf in a proper way to see the images (if any). Or you use asccidoc3api.py - see the doctext.

Unleash the full power of AsciiDoc3

If you want more than producing HTML/PDF-output (e.g. filter like Lilypond, Highlight, Pygments, Graphviz, LaTeX, w3m/lynx …) you’ll need the coresponding packages:

dblatex https://dblatex.sourceforge.net/
fop https://xmlgraphics.apache.org/fop/
xsltproc https://xmlsoft.org/xslt/
xmllint https://xmlsoft.org
graphviz https://www.graphviz.org/
imagemagick https://www.imagemagick.org/
dvipng https://www.nongnu.org/dvipng/
lilypond https://lilypond.org/
lynx https://lynx.invisible-island.net/
w3m https://sourceforge.net/projects/w3m/

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