Update asciidoctor-spec image to ruby:3.3.3 (#40)

This greatly reduces the number of CVEs reported by Dockerhub and also
updates the toolchain to current versions of asciidoctor (which
apparently gives some better error messages now than it used to).

Because of the underlying Debian updates, Python packages can no longer
be installed at system level without a very ugly and brute-force
override. Instead this image sets up a Python virtual environment
containing all the packages, with just enough of an OS-level Python to
install venv itself. If you are following the image instructions to do
your own non-Docker install of the toolchain, you will need to setup a
venv and then use the 'activate' script or otherwise setup your
VIRTUAL_ENV and PATH to use that version. Scripts relying on Python
packages installed by this image must invoke the python3 in the venv,
not /usr/bin/python3.

asciidoctor-spec.Dockerfile

@@ -1,28 +1,34 @@
-# Copyright 2019-2024, The Khronos Group Inc.
+# Copyright 2019-2024 The Khronos Group Inc.
 # SPDX-License-Identifier: Apache-2.0
 
-# This defines a Docker image for building a set of Khronos specifications
-# written using asciidoctor markup.
-# It contains the asciidoctor toolchain, and related plugins and tools.
-# Some projects may have additional toolchain requirements, and will use
-# Docker images layered on this one.
+# Defines a Docker image for building Khronos specifications written using
+# asciidoctor markup.
+# Contains the asciidoctor toolchain and related plugins and tools.
+# Specifications with additional toolchain requirements can build images
+# layered on this one.
 
-from ruby:3.1.2
+from ruby:3.3.3
 label maintainer="Jon Leech <[email protected]>"
 
-# This adds the Node.js repository to the apt registry
-# nodejs is actually installed in the next step
+# Add the Node.js repository to the apt registry
 run curl -fsSL https://deb.nodesource.com/setup_current.x | bash -
 
-# Debian packages
-# pandoc is for potential use with Markdown
-# reuse is for repository license verification
+# Debian packages.
+# First install is for Node / Python / Ruby.
+# Second is for native tools, and libraries needed for some Ruby gems.
 run apt-get update -qq && \
+    apt-get install -y -qq --no-install-recommends \
+        locales \
+        nodejs \
+        python3 \
+        python3-venv \
+        python3-pip && \
     apt-get install -y -qq --no-install-recommends \
         bash \
         bison  \
         build-essential \
         cmake \
+        dos2unix \
         flex \
         fonts-lyx \
         clang \
@@ -42,19 +48,44 @@ run apt-get update -qq && \
         libreadline-dev \
         libxml2-dev \
         ninja-build \
-        nodejs \
         pandoc \
         pdftk \
         poppler-utils \
-        python3 \
-        python3-pip \
-        python3-pytest \
-        python3-termcolor \
-        tcsh \
-        dos2unix \
     && apt-get clean
 
-# Ruby gems providing asciidoctor and related plugins
+# Ensure the proper locale is installed and used - not present in ruby image
+# See https://serverfault.com/questions/54591/how-to-install-change-locale-on-debian#54597
+run sed -i 's/^# *\(en_US.UTF-8\)/\1/' /etc/locale.gen && \
+    locale-gen && \
+    apt-get clean
+env LANG en_US.UTF-8
+
+# Python packages are installed in a virtual environment (venv).
+# Debian does not allow pip3 to install to the system Python directories.
+# It is possible to override this, but instead we use Docker commands to
+# manage a venv - see e.g.
+#   https://pythonspeed.com/articles/activate-virtualenv-dockerfile/
+# A user trying to create their own spec toolchain should instead
+#   source /path/to/venv/activate
+# which is equivalent to the commands below.
+
+env VIRTUAL_ENV=/opt/venv
+run python3 -m venv $VIRTUAL_ENV
+env PATH="$VIRTUAL_ENV/bin:$PATH"
+
+run pip3 install \
+    wheel setuptools \
+    codespell lxml meson networkx pygments pyparsing pytest termcolor \
+    reuse
+
+# JavaScript packages
+# escape-string-regexp is locked @2.0.0 because the current version is an
+# ES6 module requiring unobvious changes from 'require' to 'import'
+# There is an issue with more recent lunr versions, as well
+run npm install -g [email protected] he [email protected]
+env NODE_PATH /usr/lib/node_modules
+
+# Ruby packages providing asciidoctor and related plugins
 run gem install -N \
         asciidoctor \
         asciidoctor-diagram \
@@ -68,25 +99,3 @@ run gem install -N \
         pygments.rb \
         rouge \
         text-hyphen
-
-# Python packages
-# Something odd in the Docker build causes errors if setuptools isn't
-# installed first, although it should be a dependency of the other packages.
-run pip3 install wheel setuptools
-run pip3 install codespell networkx pygments reuse
-run pip3 install lxml meson
-
-# JavaScript packages
-# escape-string-regexp is locked @2.0.0 because the current version is an
-# ES6 module requiring unobvious changes from 'require' to 'import'
-# There is an issue with more recent lunr versions, as well
-run npm install -g [email protected] he [email protected]
-env NODE_PATH /usr/lib/node_modules
-
-# Ensure the proper locale is installed and used - not present in ruby image
-# See https://serverfault.com/questions/54591/how-to-install-change-locale-on-debian#54597
-run apt-get install -y -qq locales && \
-    sed -i 's/^# *\(en_US.UTF-8\)/\1/' /etc/locale.gen && \
-    locale-gen && \
-    apt-get clean
-env LANG en_US.UTF-8