OpenCL 3.0 Refpages (#671)

* First cut at 3.0 refpages

Import relevant changes from update-refpages-2.2-from-0a92eee branch

Update copyrights on relevant files to use SPDX license identifiers
(should do this for all files and make repository REUSE-compliant, but
that's a different issue).

Update refpage generation scripts to use 3.0 specs / version numbers
instead of 2.2.

* Fix problem with clCreateImageWithProperties rewrite rule

* Synchronize scripts, improve generation actions (#680)

* Move extracted refpage sources to generated/refpages

Considerable changes to the Makefile to accomplish this, but basically a
no-op in terms of the output HTML. Also a few minor fixes to address
build warnings.

* Further Makefile cleanup to copy static files to the right place

Also cleans up copyright boilerplate to avoid duplicate section titles.

* Build refpages as part of CI

Author: oddhack

.travis.yml

@@ -18,7 +18,7 @@ before_install:
 
 script:
   - git describe --tags --dirty
-  - make api c env ext cxx4opencl
+  - make -O -j 5 api c env ext cxx4opencl manhtmlpages
 
 deploy:
   provider: releases

Makefile

@@ -69,19 +69,23 @@ SPECREMARK = from git branch: $(shell echo `git symbolic-ref --short HEAD`) \
 	     commit: $(shell echo `git log -1 --format="%H"`)
 endif
 
-ATTRIBOPTS_NO_VERSION   = -a revdate="$(SPECDATE)" \
-	                  -a revremark="$(SPECREMARK)" \
-	                  -a stem=latexmath \
-	                  -a generated=$(GENERATED) \
-	                  -a sectnumlevels=5
+ATTRIBOPTS_NO_VERSION	= -a revdate="$(SPECDATE)" \
+			  -a revremark="$(SPECREMARK)" \
+			  -a stem=latexmath \
+			  -a generated=$(GENERATED) \
+			  -a sectnumlevels=5
 
 ATTRIBOPTS   = -a revnumber="$(SPECREVISION)" \
-               $(ATTRIBOPTS_NO_VERSION)
+	       $(ATTRIBOPTS_NO_VERSION)
 
-ADOCEXTS              = -r $(CURDIR)/config/sectnumoffset-treeprocessor.rb -r $(CURDIR)/config/spec-macros.rb
+ADOCEXTS	      = -r $(CURDIR)/config/sectnumoffset-treeprocessor.rb -r $(CURDIR)/config/spec-macros.rb
 ADOCOPTS_NO_VERSION   = -d book $(ATTRIBOPTS_NO_VERSION) $(NOTEOPTS) $(VERBOSE) $(ADOCEXTS)
-ADOCOPTS              = -d book $(ATTRIBOPTS) $(NOTEOPTS) $(VERBOSE) $(ADOCEXTS)
-ADOCMANOPTS           = -d manpage $(ATTRIBOPTS) $(NOTEOPTS) $(VERBOSE) $(ADOCEXTS)
+ADOCCOMMONOPTS	      = -a apispec="$(CURDIR)/api" \
+			-a config="$(CURDIR)/config" \
+			-a cspec="$(CURDIR)/c" \
+			$(ATTRIBOPTS) $(NOTEOPTS) $(VERBOSE) $(ADOCEXTS)
+ADOCOPTS	      = -d book $(ADOCCOMMONOPTS)
+ADOCMANOPTS	      = -d manpage $(ADOCCOMMONOPTS)
 
 # ADOCHTMLOPTS relies on the relative runtime path from the output HTML
 # file to the katex scripts being set with KATEXDIR. This is overridden
@@ -103,6 +107,7 @@ ADOCPDFOPTS  = $(ADOCPDFEXTS) -a mathematical-format=svg \
 # the API interface includes.
 # GENDEPENDS could have multiple dependencies.
 GENERATED  = $(CURDIR)/generated
+REFPATH    = $(GENERATED)/refpage
 APIINCDIR  = $(GENERATED)/api
 VERSIONDIR = $(APIINCDIR)/version-notes
 GENDEPENDS = $(APIINCDIR)/timeMarker
@@ -395,9 +400,9 @@ clean_pdf:
 	$(QUIET)$(RMRF) $(PDFDIR) $(PDFMATHDIR)
 
 clean_generated:
-	$(QUIET)$(RMRF) $(APIINCDIR)/* $(SCRIPTS)/clapi.py
-	$(QUIET)$(RM) man/apispec.txt $(MANGENSOURCES) $(MANTMP)
+	$(QUIET)$(RMRF) $(APIINCDIR)/* $(GENERATED)/api.py $($(REFPATH)/
 	$(QUIET)$(RMRF) $(PDFMATHDIR)
+	$(QUIET)$(RMRF) $(GENERATED)/__pycache__
 
 # Ref page targets for individual pages
 MANDIR	    := man
@@ -406,22 +411,12 @@ MANSECTION  := 3
 # These lists should be autogenerated
 
 # Ref page sources for all CL interfaces
-# Most are autogenerated; $(MANCOPYRIGHT) are static
-
-# Static asciidoctor files in the man/ directory that aren't refpages
-MANCOPYRIGHT = $(MANDIR)/copyright-ccby.txt $(MANDIR)/footer.txt
+# Most are autogenerated; man/static/*.txt are hand-coded at present
 
 # MANSOURCES is the list of individual refpage sources, excluding the
-# copyright, single-page index, and any include files.
-MANSOURCES   = $(filter-out $(MANCOPYRIGHT) $(MANDIR)/apispec.txt  $(wildcard $(MANDIR)/*Inc.txt), $(wildcard $(MANDIR)/[A-Za-z]*.txt))
-
-# MANGENSOURCES is the list of generated refpage sources, excluding the
-# static index page but including the files copied from static/
-MANGENSOURCES= $(filter-out $(MANDIR)/intro.txt, $(MANSOURCES))
-
-# MANTMP are temp files created by the rules
-MANTMP	     = $(LOGFILE) $(MANDIR)/tocbody $(MANDIR)/toc.html \
-	       $(MANDIR)/rewritebody $(MANDIR)/.htaccess
+# single-page index, boilerplate document footer, and include files.
+# For now, always build all refpages.
+MANSOURCES   = $(filter-out $(REFPATH)/apispec.txt $(REFPATH)/footer.txt $(wildcard $(REFPATH)/*Inc.txt), $(wildcard $(REFPATH)/*.txt))
 
 # Generation of ref page asciidoctor sources by extraction from the
 # specification(s).
@@ -432,49 +427,53 @@ MANTMP	     = $(LOGFILE) $(MANDIR)/tocbody $(MANDIR)/toc.html \
 #
 # Should pass in $(EXTOPTIONS) to determine which pages to generate.
 # For now, all core and extension ref pages are extracted by genRef.py.
-LOGFILE = man/logfile
 ## Temporary - eventually should be all spec asciidoctor source files
-SPECFILES = $(wildcard api/*.asciidoc) $(wildcard man/static/*.txt) OpenCL_API.txt OpenCL_C.txt
-##SPECFILES = api/opencl_platform_layer.txt
+SPECFILES = $(wildcard api/*.asciidoc) OpenCL_API.txt OpenCL_C.txt
 SCRIPTS = scripts
 GENREF = $(SCRIPTS)/genRef.py
+LOGFILE = $(REFPATH)/refpage.log
 
-man/apispec.txt: $(SPECFILES) $(GENREF) $(SCRIPTS)/reflib.py $(SCRIPTS)/clapi.py
-	$(PYTHON) $(GENREF) -rewrite man/rewritebody -toc man/tocbody \
+refpages: $(REFPATH)/apispec.txt
+$(REFPATH)/apispec.txt: $(SPECFILES) $(GENREF) $(SCRIPTS)/reflib.py $(GENERATED)/api.py
+	$(QUIET)$(MKDIR) $(REFPATH)
+	$(PYTHON) $(GENREF) -genpath $(GENERATED) -basedir $(REFPATH) \
+	    -rewrite $(REFPATH)/rewritebody -toc $(REFPATH)/tocbody \
 	    -log $(LOGFILE) $(SPECFILES)
-	cat man/tochead man/tocbody man/toctail > man/toc.html
-	cat man/rewritehead > man/.htaccess
-	sort < man/rewritebody >> man/.htaccess
-	$(CP) -p $(MANDIR)/static/*.txt $(MANDIR)/
+	cat $(MANDIR)/tochead $(REFPATH)/tocbody $(MANDIR)/toctail > $(REFPATH)/toc.html
+	(cat $(MANDIR)/rewritehead ; \
+	 echo ; echo "# Aliases hard-coded in refpage markup" ; \
+	 sort < $(REFPATH)/rewritebody) > $(REFPATH)/.htaccess
+	$(CP) $(MANDIR)/static/*.txt $(REFPATH)
 
 # These targets are HTML5 ref pages
 #
 # The recursive $(MAKE) is an apparently unavoidable hack, since the
 # actual list of man page sources isn't known until after
-# man/apispec.txt is generated. $(GENDEPENDS) is generated before
+# $(REFPATH)/apispec.txt is generated. $(GENDEPENDS) is generated before
 # running the recursive make, so it doesn't trigger twice
-manhtmlpages: man/apispec.txt $(GENDEPENDS)
+manhtmlpages: $(REFPATH)/apispec.txt $(GENDEPENDS)
 	$(MAKE) -e buildmanpages
-	$(CP) $(MANDIR)/*.jpg $(MANDIR)/*.gif $(MANDIR)/*.css $(MANDIR)/*.html $(MANHTMLDIR)
-	$(CP) $(MANDIR)/.htaccess $(MANHTMLDIR)/.htaccess
+	$(CP) $(MANDIR)/*.html $(MANDIR)/*.css $(MANDIR)/*.gif $(MANDIR)/*.jpg $(MANHTMLDIR)
+	$(CP) $(REFPATH)/.htaccess $(REFPATH)/*.html $(MANHTMLDIR)
 
 MANHTMLDIR  = $(OUTDIR)/man/html
-MANHTML     = $(MANSOURCES:$(MANDIR)/%.txt=$(MANHTMLDIR)/%.html)
+MANHTML     = $(MANSOURCES:$(REFPATH)/%.txt=$(MANHTMLDIR)/%.html)
+
 buildmanpages: $(MANHTML)
 
 $(MANHTMLDIR)/%.html: KATEXDIR = ../../katex
-$(MANHTMLDIR)/%.html: $(MANDIR)/%.txt $(MANCOPYRIGHT) $(GENDEPENDS) $(KATEXINST)
+$(MANHTMLDIR)/%.html: $(REFPATH)/%.txt $(MANCOPYRIGHT) $(GENDEPENDS) $(KATEXINST)
 	$(QUIET)$(MKDIR) $(MANHTMLDIR)
 	$(QUIET)$(ASCIIDOCTOR) -b html5 -a cross-file-links \
 	    $(ADOCMANOPTS) $(ADOCHTMLOPTS) -o $@ $<
 
-$(MANHTMLDIR)/intro.html: $(MANDIR)/intro.txt $(MANCOPYRIGHT)
+$(MANHTMLDIR)/intro.html: $(REFPATH)/intro.txt $(MANCOPYRIGHT)
 	$(QUIET)$(MKDIR) $(MANHTMLDIR)
 	$(QUIET)$(ASCIIDOCTOR) -b html5 -a cross-file-links \
 	    $(ADOCOPTS) $(ADOCHTMLOPTS) -o $@ $<
 
 # Targets generated from the XML and registry processing scripts
-#   clapi.py - Python encoding of the registry
+#   api.py - Python encoding of the registry
 #   $(APIINCDIR)/timeMarker - proxy for 'apiinc' - generate API interfaces
 #
 # $(GENSCRIPTEXTRA) are extra options that can be passed to the
@@ -489,15 +488,14 @@ VERSIONSCRIPT  = $(SCRIPTS)/gen_version_notes.py
 GENSCRIPTOPTS  = $(VERSIONOPTIONS) $(EXTOPTIONS) $(GENSCRIPTEXTRA) -registry $(APIXML)
 GENSCRIPTEXTRA =
 
-$(SCRIPTS)/clapi.py: $(APIXML) $(GENSCRIPT)
-	$(QUIET)$(PYTHON) $(GENSCRIPT) $(GENSCRIPTOPTS) -o $(SCRIPTS) clapi.py
+$(GENERATED)/api.py: $(APIXML) $(GENSCRIPT)
+	$(QUIET)$(PYTHON) $(GENSCRIPT) $(GENSCRIPTOPTS) -o $(GENERATED) api.py
 
 apiinc: $(APIINCDIR)/timeMarker
 
 $(APIINCDIR)/timeMarker: $(APIXML) $(DICTSCRIPT) $(GENSCRIPT) $(VERSIONSCRIPT)
-	$(QUIET)$(MKDIR) -p $(APIINCDIR)
+	$(QUIET)$(MKDIR) $(APIINCDIR)
 	$(QUIET)$(PYTHON) $(DICTSCRIPT) -registry $(APIXML) -o $(APIINCDIR)
-	$(QUIET)$(MKDIR) -p $(VERSIONDIR)
+	$(QUIET)$(MKDIR) $(VERSIONDIR)
 	$(QUIET)$(PYTHON) $(VERSIONSCRIPT) -registry $(APIXML) -o $(VERSIONDIR)
 	$(QUIET)$(PYTHON) $(GENSCRIPT) $(GENSCRIPTOPTS) -o $(APIINCDIR) apiinc
-

OpenCL_C.txt

@@ -221,7 +221,7 @@ for earlier OpenCL C versions are allowed to define feature test macros
 but they are not required to do so. This means that applications which
 target earlier OpenCL C versions should not rely on the presence of
 feature test macros because there is no guarantee that feature test macros
-will be defined and that if defined they will indicate the presence of the 
+will be defined and that if defined they will indicate the presence of the
 corresponding optional functionality.
 
 [[extensions]]
@@ -2446,7 +2446,7 @@ For all other cases that are not listed above the address space is inferred to
     are inferred to be in the private address space.
 
 Examples:
- 
+
 [source,c]
 ----------
 // Note: these examples assume OpenCL C 2.0 or the
@@ -2490,7 +2490,7 @@ Qualifiers must be explicitly specified for:
 
   * Program scope variables or variables inside functions with
     a `static` or `extern` type specifier for OpenCL C prior to version 2.0 or
-    OpenCL C 3.0 without {opencl_c_program_scope_global_variables} feature, 
+    OpenCL C 3.0 without {opencl_c_program_scope_global_variables} feature,
 
   * Pointers used as arguments to kernel functions (the address space pointed
     to must be specified explicitly).
@@ -2588,7 +2588,7 @@ definition in section 5 of the <<embedded-c-spec, Embedded C Specification>>. In
 OpenCL C, no objects can be allocated in this address space. It can only be used
 with pointer types, where a pointer pointing to a location in the generic
 address space can be used for objects allocated in any of the concrete named
-address spaces `private`, `local`, or `global`. 
+address spaces `private`, `local`, or `global`.
 ====
 
 Following section 5.3 of the <<embedded-c-spec, Embedded C Specification>>, it
@@ -2816,10 +2816,10 @@ Various clarifications and examples illustrating how changes to ISO/IEC
 9899:1999 detailed in <<embedded-c-spec, Embedded C, section 5.3>> apply
 to OpenCL C with the generic address space.
 
-*Clause 6.2.5 - Types*: 
+*Clause 6.2.5 - Types*:
 
 If address space qualifier on type T is omitted refer to
-<<addr-spaces-inference>>. 
+<<addr-spaces-inference>>.
 
 *Clause 6.3.2.3 - Pointers*
 
@@ -6239,7 +6239,7 @@ in a subgroup.
   spaces.
   For the *sub_group_barrier* variant that does not take a
   memory scope, the _scope_ is `memory_scope_sub_group`.
-  
+
   `CLK_LOCAL_MEM_FENCE` - The *sub_group_barrier* function will either flush
   any variables stored in local memory or queue a memory fence to ensure
   correct ordering of memory operations to local memory.
@@ -6325,7 +6325,7 @@ The OpenCL C programming language implements the following explicit memory fence
 [[address-space-qualifier-functions]]
 === Address Space Qualifier Functions
 
-[open,refpage='addressSpaceQualifierFuncs',desc='Address Space Qualifier Functions',type='freeform',spec='clang',anchor='address-space-qualifier-functions',xrefs='qualifiers',alias='get_fence to_global to_local to_private']
+[open,refpage='addressSpaceQualifierFuncs',desc='Address Space Qualifier Functions',type='freeform',spec='clang',anchor='address-space-qualifier-functions',alias='get_fence to_global to_local to_private']
 --
 
 NOTE: The functionality described in this section <<unified-spec, requires>>

config/copyright-ccby.txt

@@ -0,0 +1,3 @@
+Copyright 2014-2021 The Khronos Group Inc.
+
+SPDX-License-Identifier: CC-BY-4.0