Use Khronos asciidoctor-spec Docker image in CI

.github/workflows/presubmit.yml

@@ -3,47 +3,58 @@ name: Presubmit
 permissions:
   contents: read
 
-on: [push, pull_request]
+# Controls when the action will run.
+on:
+  push:
+  workflow_dispatch:
+  pull_request:
 
+# These jobs are potentially parallelizeable
 jobs:
   build:
-    name: Build all specs
+    name: Build spec artifacts
     runs-on: ubuntu-latest
+    # Refer to the build container by its SHA instead of the name, to
+    # prevent caching problems when updating the image.
+    # container: khronosgroup/docker-images:asciidoctor-spec.20240702
+    container: khronosgroup/docker-images@sha256:91a1b62399f9804e17110e89d85d62e90bc8d2ad7b94a329bee87784158368a9
 
     steps:
       - uses: actions/checkout@v4
         with:
-          fetch-depth: 0
           submodules: recursive
+          # If fetch-depth: 0 is not specified, then
+          #     git describe --tags --dirty
+          # below fails.
+          # This could also affect SPECREVISION in the Makefile.
+          fetch-depth: 0
 
-      - name: Install required packages
+      # Ownerships in the working directory are odd.
+      # . is owned by UID 1001, while repo files are owned by root.
+      # This leads to many odd messages like
+      #     fatal: detected dubious ownership in repository at '/__w/OpenCL-Docs/OpenCL-Docs'
+      # The 'git config' is a brute-force workaround.
+      - name: Git safe directory workaround
         run: |
-          sudo apt-get install -y libpango1.0-dev libwebp-dev ghostscript fonts-lyx jing libavalon-framework-java libbatik-java python3-pyparsing
-          sudo gem install asciidoctor -v 2.0.16
-          sudo gem install coderay -v 1.1.1
-          sudo gem install rouge -v 3.19.0
-          sudo gem install ttfunk -v 1.7.0
-          sudo gem install hexapdf -v 0.27.0
-          sudo gem install asciidoctor-pdf -v 2.3.4
-          sudo gem install asciidoctor-mathematical -v 0.3.5
-          sudo pip install pyparsing
+            git config --global --add safe.directory '*'
+            ls -lda . .. .git Makefile
 
       - name: List git tag
         run: |
           git describe --tags --dirty
 
+      - name: Validate XML
+        run: |
+          make -C xml validate
+
       - name: Generate core specs (HTML and PDF)
         run: |
-          python3 makeSpec -clean -spec core OUTDIR=out.core -j 5 api c env ext cxx4opencl
-          
+          python3 makeSpec -clean -spec core OUTDIR=out.core -j 5 -O api c env ext cxx4opencl
+
       - name: Generate core + extension specs (HTML)
         run: |
-          python3 makeSpec -clean -spec khr OUTDIR=out.khr -j 12 html
+          python3 makeSpec -clean -spec khr OUTDIR=out.khr -j -O html
 
       - name: Generate reference pages
         run: |
-          python3 makeSpec -spec khr OUTDIR=out.refpages -j 12 manhtmlpages
-
-      - name: Validate XML
-        run: |
-          make -C xml validate
+          python3 makeSpec -spec khr OUTDIR=out.refpages -j 12 -O manhtmlpages

Makefile

@@ -14,6 +14,7 @@ EXTOPTIONS := $(foreach ext,$(EXTS),-extension $(ext))
 
 QUIET	    ?=
 VERYQUIET   ?= @
+PYTHON	    ?= python3
 ASCIIDOCTOR ?= asciidoctor
 RM	    = rm -f
 RMRF	    = rm -rf
@@ -545,6 +546,7 @@ $(METADEPEND): $(APIXML) $(GENSCRIPT)
 attribs: $(ATTRIBFILE)
 
 $(ATTRIBFILE):
+	$(QUIET)$(MKDIR) $(dir $@)
 	for attrib in $(EXTS) ; do \
 	    echo ":$${attrib}:" ; \
 	done > $@