Use Khronos asciidoctor-spec Docker image in CI

Per discussion with $bashbaug

N.b. at present the CI script has less parallelism than it could, at
least as I understand Actions. Some of the 'steps' could be split off
into 'jobs'. Might try that next once the basic build is working. Net
performance is still somewhat faster than current CI since it's
generally faster to load the container than to add needed packages at
each invocation, and the spec build is pretty fast, so there's not much
to be gained.

There was odd error behavior from shifting to the container which I have
never seen in Vulkan CI, having to do with mixed ownership of files in
the checked-out repository. I inserted a brute-force workaround right
after the checkout action.

.github/workflows/presubmit.yml

@@ -3,47 +3,56 @@ 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
+    # needs: checkout
+    container: khronosgroup/docker-images@sha256:bd30a83285a2ea062598f053b5bd8ebc843e16c639c0e4cd88ab4bbb4e63ead3
 
     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 > $@