AsciiDoc3 on Windows

Windows10 (or Windows11) works fine with Docker. Windows user should consider this new option; see here!

AsciiDoc3 was developed on GNU/Linux. That’s a matter of fact. But you can use AsciiDoc3 also on (Windows 7 - works, but EOL), Windows 8, Windows 10, and Windows 11.
This page gives you some hints and shows the limitations of this combination (yes, there are in deed some limitations… but less than you probably suspect!).
Please note, the writer of these very lines isn’t a Windows expert at all, but has tested all the following stuff as well as possible. If you find a mistake or some facts missing, please mail to info_at_asciidoc3.org.

There are different ways to use AsciiDoc3 on Windows OS:
a) you want to compute html (xhtml, html4, html5, slidy) pages or docbook-xml out of your plain input.txt. Or you’d like to see good-looking PDFs of your text generated with Apache’s FOP? You want to apply a filter like Graphviz, LilyPond (ABC), or a source-highlighter? The implementation of this basic usage is described in the following lines; this has enough features for many people out there.
Be prepared to download and install a few (free) software-packages on top of AsciiDoc3 itself.

b) If you need the full package of almost all of the features that AsciiDoc3 has in store and you like to benefit from an "easy install process" …
1. think about to use Cygwin, or
2. use Cygwin and Python’s virtual environments venv and/or PyPI.

Alternative a) allows a good experience for the „normal“ user, it works fine.
Alternative b)1. or b)2. are more "sophisticated", perhaps recommended for the more experienced user. See the information given on this page.

1. Prerequisites

1.1. Install Python 3

Of course you have to install Python 3.x first, if not already done. Go to Python‘s homepage and download (at the time of writing) version 3.9 or 3.10.
Do not use the files offered in Microsoft Store if possible.
I found it handy to check both Install launcher for all users and Add Python3.7 to Path und then use the option Customize Installation (Choose location and features); in this menu Optional Features please check everything and in the next Advanced Options check Install for all users. You are free to choose your own configuration and leave a running system unchanged.
After completing you’ll find Python3.9 here:
C:\Program Files (x86)\Python39-32
when installed for all users or
C:\Users\<username>\AppData\Local\Programs\Python\Python39\python.exe
when installed for the current user or at another location you choosed during installation. It doesn’t matter if you install the 32bit or the 64bit version. Probably it’s a good idea to make the hidden folders like AppData visible in your FileManager.

1.2. Find your Executable

Optional: To verify that’s everything is ok find out the path of the python executable:

C:\Users\<username>: python
>>> Python 3.9.x ...
Type "help", "copyright", "credits" or "license()" for more information.
>>> import sys
>>> print(sys.executable)
C:\Program Files (x86)\Python39-32\python.exe
>>> exit()

2. Run AsciiDoc3

2.1. The manual Way

2.1.1. text2html text2slidy text2docbook

All right, now that we have python, py -3 or python3 running on our system, we download the AsciiDoc3 files here. Choose the current zip-file; to unzip zip-files you need no additional software. The tarball contains symlinks which cause additional manual work to deploy, so cold-shoulder the tar.gz-file (and you need third-party programs like 7z to extract, too).
Extract the zip-file in a (new) folder of your choice, say C:\Users\<username>\ad3 and then change to it’s subdirectory doc, and at last you run:

C:\Users\username> cd C:\Users\<username>\ad3\doc
C:\Users\username\ad3\doc> python..\asciidoc3.py -a toc -a icons -n test.txt

Instead of py -3 you may use of course py or python (or if available python3).
The output test.html shows up in the same folder and may be opened with your browser. Or to see a more extensive input file computed enter

C:\Users\username\ad3\doc> python ..\asciidoc3.py -a toc -a icons -n -v userguide.txt

This results in - you guessed it - the Asciidoc3’s User Guide userguide.html. You may omit the verbose option -v, it shows some steps of computing. See other examples how to use AsciiDoc3 this way here.

Perhaps you want to produce a docbook-xml-file via AsciiDoc3’s docbook backend? Start this, the output is given as test.xml:

C:\Users\username\ad3\doc> python ..\asciidoc3.py -a toc -a icons -n -a "backend=docbook" userguide.txt

And here we achieve html4/html5-files, respectively:

C:\Users\username\ad3\doc> python ..\asciidoc3.py -a toc -a icons -n -a "backend=html4" test.txt

C:\Users\username\ad3\doc> python ..\asciidoc3.py -a toc -a icons -n -a "backend=html5" test.txt

If you encounter an encoding error "… codec can’t decode byte …" you see a example of the well known Windows codepage mess. Go to asciidoc3.conf and edit the input-encoding: try cp1252 or whatever codepage your system runs with (check this with PowerShell [System.Text.Encoding]::Default).

And here we get a "slidy"-html page:

C:\Users\username\ad3\doc> python ..\asciidoc3.py -a toc -a icons -n -a "backend=slidy" slidy-example.txt

2.1.2. text2pdf, dblatex or FOP?

dblatex
You want to produce good looking pdfs? That’s a job for a2x3.py:

C:\Users\username\ad3\doc> python ..\a2x3.py -f pdf test.txt
...
  a2x3: ERROR: xmllint --nonet --noout --valid C:\Users\<username>\ad3\doc\test.xml returned non-zero exit status 1

Why is that? Answer: There is no xmllint installed. I give you an advice: do not try to install xmllint! There is much effort and little return: binaries and sources for Windows seem to be outdated and at all only for Python2, see this post about that mixup …
Let’s try an easy workaround (option -–no-xmllint) and run again:

C:\Users\username\ad3\doc> python ..\a2x3.py -f pdf --no-xmllint test.txt
...
  a2x3: ERROR: ... C:\Users\<username>\ad3\dblatex\asciidoc3-dblatex.sty ... returned non-zero exit status 1

And that means, there is no dblatex installed … The same as for xmllint: you better forget about installing dblatex for Windows - it’s frustrating! Believe me, I tried to install tons of miktex (more than 200MB exe), DTD locally, and so on. And at the end Python2 was required … (the same issue as about xmllint a few lines above). Perhaps there is a solution? But I haven‘t found it …

Sooner or later there will be a Python3 version of dblatex (no timeline is announced): https://sourceforge.net/p/dblatex/mailman/dblatex-devel/?viewmonth=201909

FOP
So let’s go to the alternative PDF-generator FOP, which we have to install first.
But before we do so, we install a java runtime, if not existing yet. FOP needs Java to run. So go to Java and do the work.

The next step is to download FOP for Windows here. If you are not a developer, choose `fop-2.3-bin.zip‘.
Extract it an a folder, say `C:\Users\<username>\fop-2.3\‘. You’ll see two subfolders there, javadocs and bin. The latter contains the files fop, fop.bat, and fop.cmd. We need this directory in PATH to execute.
You can manage this for the current session only or permanently, using the cli or Power Shell, see the information here. In this walkthrough I use the simple way

C:\Users\username\ad3\doc> set PATH=%PATH%;C:\Users\<username>\fop-2.3\fop 
C:\Users\username\ad3\doc> python ..\a2x3.py -f pdf --no-xmllint --fop test.txt
...
  a2x3: ERROR: xsltproc --stringparam callout.graphics 0 --stringparam navig.graphics ... returned non-zero exit status 1

how to edit PATH permanently see here or here. If done, you probably have to do logout/login.

And what is this again? Yes, we have to install a few files more! The appropriate information about this given here: Download the zip-files and extract them wherever you like to and then copy the seven files

libxslt.dll
iconv.dll
xmllint.exe
libxml2.dll
zlib.dll
libexslt.dll
xsltproc.exe

to a directory in your PATH to make them executable. The other files extracted from the zip-files are redundant. As a service you can download a zip-file containing just these seven files here:

--> fop_windows_exe_dll.zip <--

To have all FOP-files in one directory I moved the seven to C:\Users\<username>\fop-2.3\fop. Now we have here four subdirectories (build, conf, examples, lib) and eleven files (4x fop.* plus 7).

And now please start again! Be sure to have edited PATH to have all exe/dll available and do not forget option --no-xmllint!

C:\Users\username\ad3\doc> py -3 ..\a2x3.py -f pdf --no-xmllint --fop test.txt
...
a2x3: deleting C:\Users\<username>\ad3\doc\test.fo
a2x3: deleting C:\Users\<username>\ad3\doc\test.xml
C:\Users\username\ad3\doc>

Yeah, at last it works! Unfortunately FOP works somewhat slow on Windows. See test.pdf in directory C:\Users\username\ad3\doc. We have produced a good-looking PDF.

Summary

If you follow the instructions given above, you can use AsciiDoc3 to produce

xhtml
html4
html5
docbook-xml
PDF

out of your asciidoc3-formatted text.txt.

2.1.3. Filters: Graphviz, LilyPond, Highlight. They work!

Now let’s test the filters (ABC/LilyPond, Graphviz, Source: - Pygments -Source-Highligh -Highlight) in the given order. We skip filter code because this a demo filter only. And we skip filter latex because this filter isn’t been updated for years and not running smooth at all.

LilyPond
First we analyze LilyPond. If you wonder why we do not start with ABC: we do not need this program since LilyPond translates ABC-files for us, so we skip ABC.
Allright, download here and install lilypond-2.18.2-1.mingw.exe as usual. Be sure to add the the folder which contains LilyPond executable files to the environmental variable PATH. See above how to manage this, e.g. set PATH=%PATH%;C:"\Program Files (x86)\LilyPond\usr\bin".
Sometimes we saw a problem regarding Guile,

...
ERROR: In procedure primitive-load-path:
ERROR: Unable to find file "ice-9/boot-9.scm" in load path
...

we could fix this adding an environment variable like so

GUILE_LOAD_PATH="C:\Program Files (x86)\LilyPond\usr\share\guile\1.8"

To see that LilyPond works fine and to trigger some configuring steps it is very useful to enter

C:\Users\username> lilypond -V

If everything is ok

C:\Users\username> cd C:\Users\username\ad3\filters\music
C:\Users\username\ad3\filters\music> python ..\asciidoc3.py -v -a toc -a icons -n music-filter-test.txt

Though we see some warnings, the output music-filter-test.html looks fine - LilyPond works!

Older versions of Lilypond depended on Python2 - probably a security hole; this hole is closed meanwhile.

Graphviz
Thanks to the developers this is an easy thing - almost :-)
Go to the Graphviz download page, grab the file graphviz-2.38.zip, install as usual (say, in folder "C:\Program Files (x86)\Graphviz2.38). But we didn’t make it possible to add this folder to PATH, so eventually we moved the executable files (dot.exe, acyclic.exe, dotty.exe …) to a definitely suitable folder, in our case we choosed C:\Users\<username>\AppData\Local\Programs\Microsoft VS Code\bin\. And what happened? It worked:

C:\Users\username> cd C:\Users\username\ad3\filters\graphviz
C:\Users\username\ad3\filters\graphviz> python ..\asciidoc3.py -v -a toc -a icons -n asciidoc3-graphviz-sample.txt

the output file asciidoc3-graphviz-sample.html looks fine - Graphviz works, too!

Pygments
Pygments, the first of the three AsciiDoc3-included source-highlighter: there seems to be no existing classical installable windows-exe out there - but with Python we have pip/PyPI.
Installing pygments via pip is not a secret:

(admin rights!) > pip3 install pygments

To check if everything goes the right way (normal user again, no admin rights here)

C:\Users\username\ad3> pip show pygments
Name: Pygments
Version: 2.3.1
Summary: Pygments is a syntax highlighting package written in Python.
Home-page: http://pygments.org/
Author: Georg Brandl
Author-email: georg@python.org
License: BSD License
Location: c:\program files (x86)\python37-32\lib\site-packages
Requires:
Required-by:

or just type

C:\Users\username\ad3> pygmentize -V
Pygments version 2.3.1, (c) 2006-2017 by Georg Brandl.

Source-Highlite
To make it short, there are only outdated windows-binaries available, here. The reasons are explained here by the author himself. So we move forward.

Highlight
Go to the download page here and fetch highlight-setup-3.48-x64.exe (or the corresponding zip-file). Install as usual and do not forget to add the target folder to PATH.
The terminal step before starting source-highlighting is to edit asciidoc3.conf:

...
# HTML source code highlighter (source-highlight, pygments or highlight).
# source-highlighter=source-highlight
# source-highlighter=pygments
source-highlighter=highlight                       
# Uncomment to use deprecated quote attributes.
#deprecated-quotes=
...

uncomment this line and comment out the two preceding lines.

When done, start

C:\Users\username\ cd ad3\doc

C:\Users\username\ad3\doc> py -3 ..\asciidoc3.py -a toc -n -a icons source-highlight-filter.txt

and the source-highlight-filter.html shows the exspected formatting.
So we have at last one source-highlighter ready out-of-the-box.

Summary

If you follow the instructions in this section, AsciiDoc3 works together with

Graphviz,
LilyPond (ABC), and
Highlight.

2.2. A second Approach: Cygwin

We have seen it is possible to run AsciiDoc3 on Windows. The downside can not be overseen: many files to download, to install, many manipulations of PATH … and a few things are still missing.
Perhaps there is a way to sidestep these problems - let’s try Cygwin. And why (hopefully) Cygwin may help? Cygwin provides a lot of GNU/Linux software to use with Windows. The programs are ported to the Windows platform, Cygwin is not a virtual machine or an emulator. It’s just another peace of Windows-software. And in most cases we can avoid a big part of the configuring-hassle.
Of course this page is not a tutorial how to start with Cygwin - please refer to the huge amount of material which can be found online.

2.2.1. Start with Cygwin

Download Cygwin here and install setup-x86_64.exe (or setup-x86.exe - I prefer the 64-bit version since I run a 64-bit-Windows) the same way as any usual program. Install it to a particular folder, say C:\cygwin64 - just confirm the default. If you peek into C:\cygwin64\bin you see many well known GNU/Linux software as exe-files: bash.exe, echo.exe, less.exe …

Keep in mind not to delete setup-x86_64.exe (in your download directory or somewhere else): you’ll need to start setup again if you want to add cygwin-programs.

Every time you want to use one of the "cygwin"-programs you have to start it from the Cygwin64-Terminal. It’s a good idea to create a link on the desktop. When you doubleclick the link, the cygwin-comman-prompt appears:

<username>@admin-PC ~
$

and you work in your home directory ~

The first thing is to install Python3. Start the saved setup-x86_64.exe" again and choose in the 'Select Packages -→ Full -→ python3 and go on as usual.

If Python3 is already running on the "normal" Windows do not install again. This will cause difficulties. The things should work somehow or other. I started with an empty Windows7.

Installing the "Cygwin-Python" makes it available only in the home-directory and/or the Cygwin64-Terminal. The command is as requested python3, neither py nor py -3.

The next step is to downoad and install asciidoc3-3.x.y.zip. Extract it in your home-directory, e.g. you’ll see the exectuable here:
C:\cygwin64\home\username\ad3\asciidoc3.py and an subdirectory like C:\cygwin64\home\username\ad3\doc.

Just check if everything’s ok so far by entering in the Cygwin64-Terminal …

<username>@admin-PC ~/ad3/doc
$ python3 ../asciidoc3.py -a toc -a icons -n test.txt

the output file test.html lives in the ~/ad3/doc directory.

If you installed AsciiDoc3 in your Windows-user-directory, the command is something like
python3 c:/Users/<username>/ad3/asciidoc3.py -a toc -a icons -n ../../../../../../Users/<username>/ad3/doc/test.txt
In a Cygwin64-Terminal you may use the / instead of \

2.2.2. Cygwin wins! Or not?

And now we take a shortcut by installing the packages (i.e programs) via CygWin which help and work under AsciiDoc3:

lilypond
highlight
source-highlight
graphviz
dblatex

(Please install dblatex at last to avoid an issue I saw when starting with this!)
Yes, these packages work seamlessly with AsciiDoc3, no PATH adjustment neccessary. Skip to install FOP (no binaries available) and Pygments - these two fail.

Summary

We have to use dblatex to achieve PDFs, FOP does not work. As a source-highlighter we can choose between highlight and source-highlight.
So the competition Standard-Windows vs. Cygwin ends undecided.

Tabelle 1. Standard-Windows vs. Cygwin
	`Windows`	`Cygwin`
dblatex	`-`	`ok`
FOP	`ok`	`-`
graphviz	`ok`	`ok`
lilypond/abc	`ok`	`ok`
source-highlight	`-`	`ok`
highlight	`ok`	`ok`