Restore static refpages to the build (#1127)

These were commented out during debugging and not restored.
Also factors out a small difference between Vulkan and OpenCL scripts.

Closes #1121

Makefile

@@ -459,7 +459,7 @@ $(REFPATH)/apispec.txt: $(SPECFILES) $(GENREF) $(SCRIPTS)/reflib.py $(PYAPIMAP)
 	(cat $(MANDIR)/rewritehead ; \
 	 echo ; echo "# Aliases hard-coded in refpage markup" ; \
 	 sort < $(REFPATH)/rewritebody) > $(REFPATH)/.htaccess
-	echo $(CP) $(MANDIR)/static/*.txt $(REFPATH)
+	$(CP) $(MANDIR)/static/*.txt $(REFPATH)
 
 # These targets are HTML5 ref pages
 #
@@ -493,11 +493,12 @@ $(MANHTMLDIR)/%.html: $(REFPATH)/%.txt $(MANCOPYRIGHT) $(GENDEPENDS) $(KATEXINST
 	$(VERYQUIET)$(ASCIIDOCTOR) -b html5 $(ADOCOPTS) $(ADOCHTMLOPTS) \
 	    $(ADOCREFOPTS) -o $@ $<
 
+# This is not formatted as a refpage, so needs a different build rule
 $(MANHTMLDIR)/intro.html: $(REFPATH)/intro.txt $(MANCOPYRIGHT)
 	$(VERYQUIET)echo "Building $@ from $< using default options"
 	$(VERYQUIET)$(MKDIR) $(MANHTMLDIR)
 	$(VERYQUIET)$(ASCIIDOCTOR) -b html5 $(ADOCOPTS) $(ADOCHTMLOPTS) \
-	    $(ADOCREFOPTS) -o $@ $<
+	    -o $@ $<
 
 # Targets generated from the XML and registry processing scripts
 #   apimap.py - Python encoding of the registry

scripts/docgenerator.py

@@ -255,7 +255,11 @@ def writeInclude(self, directory, basename, contents):
                 index_term = basename
             write('indexterm:[{}]'.format(index_term), file=fp)
 
-        write(f'[source%unbreakable,{self.conventions.docgen_language}]', file=fp)
+        source_options = self.conventions.docgen_source_options
+        source_language = self.conventions.docgen_language
+        source_directive = f'[source{source_options},{source_language}]'
+
+        write(source_directive, file=fp)
         write('----', file=fp)
         write(contents, file=fp)
         write('----', file=fp)
@@ -270,7 +274,7 @@ def writeInclude(self, directory, basename, contents):
             # Asciidoc anchor
             write(self.genOpts.conventions.warning_comment, file=fp)
             write('// Include this no-xref version without cross reference id for multiple includes of same file', file=fp)
-            write(f'[source,%unbreakable,{self.conventions.docgen_language}]', file=fp)
+            write(source_directive, file=fp)
             write('----', file=fp)
             write(contents, file=fp)
             write('----', file=fp)

scripts/spec_tools/conventions.py

@@ -548,3 +548,11 @@ def docgen_language(self):
            blocks."""
 
         return 'c++'
+
+    @property
+    def docgen_source_options(self):
+        """Return block options to be used in docgenerator [source] blocks,
+           which are appended to the 'source' block type.
+           Can be empty."""
+
+        return '%unbreakable'