AsciiDoc3 and Python3 on Mac

"Apple will no longer bundle Python 2.7 with macOS 12.3 … " says https://www.macrumors.com/2022/01/28/apple-removing-python-2-in-macos-12-3/

That implies there is no Python at all on a brand new Mac any more, since Apple’s OS ships no Python 3 too. The missing Python2 is ok, but we need Python3 to run AsciiDoc3. Let’s see how we can fix this.

I show to you a walkthrough on my iMac-Pro (BigSur), my user name is abc.
We have to go these steps:

Install Python3
(if not present, of course),
Create a python3-virtual environment where AsciiDoc3 will live in
(the recommended way to install AsciiDoc3),
Install Asciidoc3 via pip in this virtual environment
(producing html is ok),
Install FOP to produce PDFs

These steps are very similar described here 2.1. Recommended: AsciiDoc3 and venv

abc@abcs-iMac-Pro ~ % python

WARNING: Python 2.7 is not recommended.
This version is included in macOS for compatibility with legacy software.
Future versions of macOS will not include Python 2.7.
Instead, it is recommended that you transition to using 'python3' from within Terminal.

Python 2.7.16 (default, Sep    6 2021, 07:39:44)
[GCC Apple LLVM 12.0.5 (clang-1205.0.19.59.6) [+internal-os, ptrauth-isa=deploy on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> exit()

On newer versions you see something like

...the python command requires the command line developer tools ...

abc@abcs-iMac-Pro ~ % python3
xcode-select: note: no developer tools were found at '/Applications/Xcode.app', requesting install. Choose an option in the dialog to download the command line developer tools.

So please install Python3 the Xcode.app route or go to the Python3 download: (python-3.10.4-macos11.pkg)
https://www.python.org/downloads/release/python-3104/

If everything goes right, you see:

abc@abcs-iMac-Pro ~ % python3
Python 3.8.2 (default, Jun    8 2021, 11:59:35)
[Clang 12.0.5 (clang-1205.0.22.11)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> exit()

From now on we go the same way as decribed here:

abc@abcs-iMac-Pro ~ % python3 -m venv ad3
abc@abcs-iMac-Pro ~ % ls
Desktop     Documents   Downloads   Library     Movies      Music       Pictures    Public      ad3
abc@abcs-iMac-Pro ~ % cd ad3
abc@abcs-iMac-Pro ad3 % ls
bin     include     lib     pyvenv.cfg
abc@abcs-iMac-Pro ad3 % source bin/activate
(ad3) abc@abcs-iMac-Pro ad3 % pip3 install wheel
Collecting wheel
    Downloading https://files.pythonhosted.org/packages/27/d6/003e593296a85fd6ed616ed962795b2f87709c3eee2bca4f6d0fe55c6d00/wheel-0.37.1-py2.py3-none-any.whl
Installing collected packages: wheel
Successfully installed wheel-0.37.1
WARNING: You are using pip version 19.2.3, however version 22.0.4 is available.
You should consider upgrading via the 'pip install --upgrade pip' command.
(ad3) abc@abcs-iMac-Pro ad3 % pip3 install --upgrade pip
Collecting pip
    Downloading https://files.pythonhosted.org/packages/4d/16/0a14ca596f30316efd412a60bdfac02a7259bf8673d4d917dc60b9a21812/pip-22.0.4-py3-none-any.whl (2.1MB)
          |████████████████████████████████| 2.1MB 2.2MB/s
Installing collected packages: pip
    Found existing installation: pip 19.2.3
        Uninstalling pip-19.2.3:
            Successfully uninstalled pip-19.2.3
Successfully installed pip-22.0.4
(ad3) abc@abcs-iMac-Pro ad3 % pip install asciidoc3
Collecting asciidoc3
    Downloading asciidoc3-3.2.3-py3-none-any.whl (913 kB)
          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 913.5/913.5 KB 2.9 MB/s eta 0:00:00
Installing collected packages: asciidoc3
Successfully installed asciidoc3-3.2.3
(ad3) abc@abcs-iMac-Pro ad3 % asciidoc3
asciidoc3: no help topics found
(ad3) abc@abcs-iMac-Pro ad3 % asciidoc3_postinstall                            <see annotation 1. below>
(ad3) abc@abcs-iMac-Pro ad3 % cd ..
(ad3) abc@abcs-iMac-Pro ~ % ls
Desktop     Documents   Downloads   Library     Movies      Music       Pictures    Public      ad3     asciidoc3
(ad3) abc@abcs-iMac-Pro ~ % ls -al
total 48
drwxr-xr-x+ 19 abc      staff        608 Apr 28 12:59 .
drwxr-xr-x      5 root    admin        160 Apr 26 09:14 ..
...
drwxr-xr-x+    4 abc      staff        128 Apr 26 09:14 Public
drwxr-xr-x      6 abc      staff        192 Apr 28 12:52 ad3
lrwxr-xr-x      1 abc      staff          52 Apr 28 12:59 asciidoc3 -> /Users/abc/ad3/lib/python3.8/site-packages/asciidoc3
(ad3) abc@abcs-iMac-Pro ~ % cd asciidoc3
(ad3) abc@abcs-iMac-Pro asciidoc3 % ls -al
total 1352
drwxr-xr-x    53 abc    staff        1696 Apr 28 12:56 .
drwxr-xr-x    13 abc    staff          416 Apr 28 12:56 ..
-rw-r--r--      1 abc    staff        1571 Apr 28 12:56 BUGS.txt
-rw-r--r--      1 abc    staff        3766 Apr 28 12:56 CHANGELOG
-rw-r--r--      1 abc    staff        3766 Apr 28 12:56 CHANGELOG.txt
...
drwxr-xr-x      4 abc    staff          128 Apr 28 12:56 themes
drwxr-xr-x      4 abc    staff          128 Apr 28 12:56 vim
-rw-r--r--      1 abc    staff      22638 Apr 28 12:56 xhtml11.conf
(ad3) abc@abcs-iMac-Pro asciidoc3 % cd doc
(ad3) abc@abcs-iMac-Pro doc % ls -al
total 992
drwxr-xr-x    37 abc    staff        1184 Apr 28 12:59 .
drwxr-xr-x    53 abc    staff        1696 Apr 28 12:56 ..
-rw-r--r--      1 abc    staff        4917 Apr 28 12:56 a2x3.1.gz
-rw-r--r--      1 abc    staff      11932 Apr 28 12:56 a2x3.1.txt
...
-rw-r--r--      1 abc    staff        8590 Apr 28 12:56 source-highlight-filter.txt
-rw-r--r--      1 abc    staff        1041 Apr 28 12:56 test.txt
-rw-r--r--      1 abc    staff    231103 Apr 28 12:56 userguide.txt
(ad3) abc@abcs-iMac-Pro doc % asciidoc3 -a toc -a icons -n -v test.txt
asciidoc3: reading: /Users/abc/.asciidoc3/asciidoc3.conf
asciidoc3: Entering "update_input-encoding()" with file: /Users/abc/.asciidoc3/asciidoc3.conf
asciidoc3: input-encoding updated as in /Users/abc/.asciidoc3/asciidoc3.conf: utf-8
asciidoc3: Entering "update/fix input-errors": /Users/abc/.asciidoc3/asciidoc3.conf
...
asciidoc3: test.txt: line 1: Entering "update/fix output-errors" with input-file: /Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc/asciidoc3.conf
asciidoc3: writing: /Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc/test.html
asciidoc3: test.txt: line 1: evaluating: {template:toc}
(ad3) abc@abcs-iMac-Pro doc % ls
a2x3.1.gz               asciidoc3.1.gz              book-multi_docbook51.txt        faq.txt                 latexmathml.txt             slidy-example.txt
a2x3.1.txt              asciidoc3.1.txt             book.txt                images                  music-filter.txt            slidy.txt
article-docinfo.xml         asciidoc3.conf              book_containing_an_abstract.txt     latex-backend.txt           publishing-ebooks-with-asciidoc3.txt    source-highlight-filter.txt
article.txt             asciidoc3api.txt            cheatsheet.txt              latex-bugs.txt              quickstart.txt              test.html
article_docbook51-docinfo.xml       asciimathml.txt             customers.csv               latex-filter.txt            readme.txt              test.txt
article_docbook51.txt           book-multi.txt              epub-notes.txt              latexmath.txt               readme_docbook51.txt            userguide.txt
(ad3) abc@abcs-iMac-Pro doc % asciidoc3 -a toc -a icons -n -v userguide.txt
asciidoc3: reading: /Users/abc/.asciidoc3/asciidoc3.conf
...
asciidoc3: userguide.txt: line 6248: evaluating: {counter:appendix-number:A}    <see annotation 2. below>
(ad3) abc@abcs-iMac-Pro doc %

Do not forget to run asciidoc3_postinstall
You’ll find the computes HTMLs in directory asciidoc3/doc

Do not forget to activate the Python3-venv source bin/activate when you start with AsciiDoc3 and deactivate when ending.

To produce a good-looking pdf we need dblatex and/or FOP
FOP ist recommended since dblatex is very tricky.

We use Homebrew:

abc@abcs-iMac-Pro ~ % /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
==> Checking for `sudo` access (which may request your password)...
Password:
==> This script will install:
/usr/local/bin/brew
/usr/local/share/doc/homebrew
...
/usr/local/Frameworks

Press RETURN/ENTER to continue or any other key to abort:
==> /usr/bin/sudo /bin/mkdir -p /usr/local/bin /usr/local/etc /usr/local/include /usr/local/lib /usr/local/sbin /usr/local/share /usr/local/var /usr/local/opt /usr/local/share/zsh /usr/local/share/zsh/site-functions /usr/local/var/homebrew /usr/local/var/homebrew/linked /usr/local/Cellar /usr/local/Caskroom /usr/local/Frameworks
...
* [new branch]                    dependabot/bundler/Library/Homebrew/sorbet-0.5.9903 -> origin/dependabot/bundler/Library/Homebrew/sorbet-0.5.9903
 * [new branch]                    master          -> origin/master
 * [new tag]                          0.1                -> 0.1
 * [new tag]                          0.2                -> 0.2
 * [new tag]                          0.3                -> 0.3
 ...
 * [new tag]                          3.4.8            -> 3.4.8
 * [new tag]                          3.4.9            -> 3.4.9
Updating files: 100% (2776/2776), done.
...
==> Pouring portable-ruby-2.6.8.yosemite.bottle.tar.gz
==> Installation successful!

==> Homebrew has enabled anonymous aggregate formulae and cask analytics.
Read the analytics documentation (and how to opt-out) here:
    https://docs.brew.sh/Analytics
No analytics data has been sent yet (nor will any be during this install run).
...

abc@abcs-iMac-Pro ~ % brew analytics off
abc@abcs-iMac-Pro ~ % brew update
Already up-to-date.
abc@abcs-iMac-Pro ~ % brew install fop
Running `brew update --preinstall`...
==> Downloading https://ghcr.io/v2/homebrew/core/openjdk/manifests/18.0.1
...
==> Installing fop
==> Pouring fop--2.7.all.bottle.tar.gz
🍺  /usr/local/Cellar/fop/2.7: 4,029 files, 100.5MB
==> Running `brew cleanup fop`...
Disable this behaviour by setting HOMEBREW_NO_INSTALL_CLEANUP.
Hide these hints with HOMEBREW_NO_ENV_HINTS (see `man brew`).
abc@abcs-iMac-Pro ~ % fop
FOP Version 2.7
USAGE
fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-rtf|-tiff|-png|-pcl|-ps|-txt|-at [mime]|-print] <outfile>
 [OPTIONS]
  -version          print FOP version and exit
...
  -foout outfile    input will only be XSL transformed. The intermediate
...

And from now on we can produce PDFs:

abc@abcs-iMac-Pro ~ % cd ad3
abc@abcs-iMac-Pro ad3 % source bin/activate
(ad3) abc@abcs-iMac-Pro ad3 % cd ..
(ad3) abc@abcs-iMac-Pro ~ % cd asciidoc3
(ad3) abc@abcs-iMac-Pro asciidoc3 % cd doc
(ad3) abc@abcs-iMac-Pro doc % asciidoc3 -n -a icons -a toc userguide.txt
(ad3) abc@abcs-iMac-Pro doc % a2x3 -v -f pdf --fop userguide.txt
a2x3: args: ['-v', '-f', 'pdf', '--fop', 'userguide.txt']
a2x3: resource files: []
...
asciidoc3: userguide.txt: line 3232: reading: /Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc/customers.csv
a2x3: executing: "xmllint" --nonet --noout --valid "/Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc/userguide.xml"
I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
/Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc/userguide.xml:2: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
D DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
                                                                               ^
/Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc/userguide.xml:6: validity error : Validation failed: no DTD found !
<article lang="en">
                  ^
a2x3: ERROR: "xmllint" --nonet --noout --valid "/Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc/userguide.xml" returned non-zero exit status 4

Use option --no-xmllint

(ad3) abc@abcs-iMac-Pro doc % a2x3 -v -f pdf --fop --no-xmllint userguide.txt
a2x3: args: ['-v', '-f', 'pdf', '--fop', '--no-xmllint', 'userguide.txt']
a2x3: resource files: []
a2x3: resource directories: ['/Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/images', '/Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/stylesheets']
a2x3: executing: "/Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/asciidoc3.py" --backend docbook -a "a2x3-format=pdf"  --verbose  --out-file "/Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc/userguide.xml" "/Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc/userguide.txt"

asciidoc3: reading: /Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/asciidoc3.conf
...
asciidoc3: userguide.txt: line 3232: reading: /Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc/customers.csv

a2x3: chdir /Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc
a2x3: executing: "xsltproc"  --stringparam callout.graphics 0 --stringparam navig.graphics 0 --stringparam admon.textlabel 1 --stringparam admon.graphics 0  --output "/Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc/userguide.fo" "/Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/docbook-xsl/fo.xsl" "/Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc/userguide.xml"

Making portrait pages on A4 paper (210mmx297mm)

a2x3: chdir /Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc
a2x3: executing: "fop"   -fo "/Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc/userguide.fo" -pdf "/Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc/userguide.pdf"

May 01, 2022 9:42:00 AM org.apache.fop.fo.properties.PropertyMaker make
...
May 01, 2022 9:42:05 AM org.apache.fop.events.LoggingEventListener processEvent
INFO: Rendered page #111.
May 01, 2022 9:42:05 AM org.apache.fop.events.LoggingEventListener processEvent
INFO: Rendered page #112.

a2x3: deleting /Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc/userguide.fo
a2x3: deleting /Users/abc/ad3/lib/python3.8/site-packages/asciidoc3/doc/userguide.xml
(ad3) abc@abcs-iMac-Pro doc %
(ad3) abc@abcs-iMac-Pro doc % deactivate
abc@abcs-iMac-Pro doc %

Find the PDF in directory asciidoc3/doc!

Keywords: MacOS BigSur Catalina AsciiDoc3 Asciidoc Python3 FOP

links