Change log for July 10, 2016 Vulkan 1.0.20 spec update:

  * Bump API patch number and header version number to 20 for this
    update.

Github Issues:

  * Replaced existing reference pages by text automatically extracted
    from the specification source, or generated from vk.xml in some
    cases. This isn't a complete solution for the reference pages, but
    puts them in a much better state. The ref pages (only) are now
    placed under a CC BY open source license, which is more current than
    the obsolete license previously used.

    Further improvements to the pages should not edit them directly, but
    instead concentrate on the specification source from which the ref
    pages are being extracted (public issues 44, 55, 160; internal issue
    389).

.gitignore

@@ -34,14 +34,9 @@
 __pycache__
 
 # Spec build temporary files and outputs
-out/checks
-out/html
-out/xhtml
-out/vkspec*
-out/apispec*
-out/man
-out/pdf
-out/core
+out/1.0*
+out/genRef
+out/misc
 doc/specs/vulkan/specversion.txt
 
 # Header build temporary files

ChangeLog.txt

@@ -923,3 +923,24 @@ Other Commits:
     wasn't listed in the error codes.
   * Fix "correponds" typo in member definitions for
     slink:VkSubpassDescription.
+
+-----------------------------------------------------
+
+Change log for July 10, 2016 Vulkan 1.0.20 spec update:
+
+  * Bump API patch number and header version number to 20 for this
+    update.
+
+Github Issues:
+
+  * Replaced existing reference pages by text automatically extracted
+    from the specification source, or generated from vk.xml in some
+    cases. This isn't a complete solution for the reference pages, but
+    puts them in a much better state. The ref pages (only) are now
+    placed under a CC BY open source license, which is more current than
+    the obsolete license previously used.
+
+    Further improvements to the pages should not edit them directly, but
+    instead concentrate on the specification source from which the ref
+    pages are being extracted (public issues 44, 55, 160; internal issue
+    389).

doc/specs/vulkan/Makefile

@@ -93,7 +93,7 @@ A2XDBLATEXOPTS := --dblatex-opts='$(DBLATEXOPTS)'
 # Misc. files to clean up (see 'checkinc' target below)
 DIRT = $(SPECVERSION)
 
-.PHONY: directories
+.PHONY: directories $(MANHTMLDIR) $(MANPAGEDIR)
 
 ICONFILES := \
     $(ICONPATH)/caution.png \
@@ -118,14 +118,15 @@ SVGTYPEHTML := svg
 SVGTYPEPDF := pdf
 # Main (root) asciidoc spec source file
 TOPDOC := vkspec.txt
-# Included chapters of the API spec
-CHAPTERS := $(wildcard chapters/[A-Za-z]*.txt appendices/[A-Za-z]*.txt)
+# Files making up sections of the API spec. The wildcard expression
+# should work in extension branches to pull in those files as well.
+CHAPTERS := $(wildcard chapters/[A-Za-z]*.txt appendices/[A-Za-z]*.txt chapters/*/[A-Za-z]*.txt appendices/*/[A-Za-z]*.txt)
 INCLUDES := $(wildcard protos/*.txt structs/*.txt flags/*.txt enums/*.txt funcpointers/*.txt validity/structs/*.txt validity/protos/*.txt)
 # All non-format-specific dependencies
 COMMONDOCS := $(CHAPTERS) $(INCLUDES)
 # A generated included file with the spec version, date, and git commit
 SPECVERSION = specversion.txt
-SPECREVISION = 1.0.19
+SPECREVISION = 1.0.20
 SPECREMARK =
 
 # Spec targets
@@ -203,7 +204,13 @@ $(OUTDIR)/styleguide.html: $(VKCONF) $(SPECVERSION) $(STYLESRC)
 	    -o $(OUTDIR)/styleguide.html -a svgpdf=$(SVGTYPEHTML) \
 	    $(STYLESRC)
 
-clean: clean_html clean_pdf clean_chunked clean_checks clean_dirt
+clean: clean_html clean_pdf clean_chunked clean_checks clean_dirt clean_man
+
+clean_man:
+	$(RM) $(MANHTML)
+	$(RMRF) $(MANHTMLDIR)
+	$(RM) $(MANPAGES)
+	$(RMRF) $(MANPAGEDIR)
 
 clean_html:
 	$(QUIET)$(RMRF) $(HTMLDIR) $(XHTMLDIR)
@@ -221,23 +228,73 @@ clean_checks:
 clean_dirt:
 	$(QUIET)$(RM) $(DIRT)
 
-# Man page targets for individual pages
-MANDIR:=man
--include man/manpages.mak
+# Ref page targets for individual pages
+MANDIR	    := man
+MANSECTION  := 3
+
+# These lists should be autogenerated
+
+# Ref page sources, split up by core vs. author IDs
+# CORESOURCES expansion will accidentally pull in macros defined by
+# extensions. Hopefully that won't happen.
+WSISOURCES  := $(wildcard $(MANDIR)/*KHR.txt)
+EXTSOURCES  := $(wildcard $(MANDIR)/*EXT.txt)
+CORESOURCES := $(filter-out $(WSISOURCES) $(EXTSOURCES) $(MANDIR)/vkman.css,$(wildcard $(MANDIR)/[Vv][Kk]* $(MANDIR)/PFN*txt))
+MANSOURCES  := $(CORESOURCES) $(WSISOURCES) $(EXTSOURCES)
+
+MANCOPYRIGHT:= $(MANDIR)/khronoscopyright.txt $(MANDIR)/footer.txt
+MANPAGEDIR  := $(OUTDIR)/man/$(MANSECTION)
+MANPAGES    := $(MANSOURCES:$(MANDIR)/%.txt=$(MANPAGEDIR)/%.$(MANSECTION))
+MANHTMLDIR  := $(OUTDIR)/man/html
+MANHTML     := $(MANSOURCES:$(MANDIR)/%.txt=$(MANHTMLDIR)/%.html)
+
+manpagesall: manpages manhtmlpages
+
+manpages: $(MANPAGEDIR) $(MANPAGES)
+
+manhtmlpages: $(MANHTMLDIR) $(MANHTML)
+
+manhtmlpages: VKCONF=config/manpages.conf
+
+# Automatic generation of ref pages. Needs to have a proper dependency
+# causing the man page sources to be generated by running genRef (once),
+# but adding $(MANSOURCES) to the targets causes genRef to run
+# once/target.
+man/apispec.txt: $(CHAPTERS) genRef.py reflib.py vkapi.py
+	$(PYTHON) genRef.py $(CHAPTERS)
+
+# These dependencies don't take into account include directives
+
+$(MANPAGEDIR)/%.$(MANSECTION): $(MANDIR)/%.$(MANSECTION)
+	$(QUIET)mv $< $@
+
+$(MANDIR)/%.$(MANSECTION): $(MANDIR)/%.txt $(MANCOPYRIGHT) config/manpages.conf
+	$(QUIET)$(ECHO) Building $@
+	$(QUIET)$(A2X) -d manpage -f manpage --asciidoc-opts "-f config/manpages.conf" $(A2XOPTS) $<
+
+$(MANHTMLDIR)/%.html: $(MANDIR)/%.txt $(MANCOPYRIGHT) config/manpages.conf
+	$(QUIET)$(ECHO) Building $@
+	$(QUIET)$(A2X) -d manpage -f xhtml --asciidoc-opts "-f config/manpages.conf" --stylesheet=vkman.css $(A2XOPTS) --destination-dir=$(@D) $<
+
+$(MANHTMLDIR):
+	$(QUIET)$(MKDIR) $@
+
+$(MANPAGEDIR):
+	$(QUIET)$(MKDIR) $@
 
 # Man page targets for HTML and PDF single-file documents
 
 manpdf: $(OUTDIR)/apispec.pdf
 
 manhtml: $(OUTDIR)/apispec.html
 
-$(OUTDIR)/apispec.pdf: $(CONFFILE) man/apispec.txt $(MANSOURCES) $(PDFXSL)
+$(OUTDIR)/apispec.pdf: $(CONFFILE) man/apispec.txt $(MANSOURCES) $(MANCOPYRIGHT) $(PDFXSL)
 	$(QUIET)if test ! -d $(OUTDIR) ; then $(MKDIR) $(OUTDIR) ; fi
 	$(QUIET)$(A2X) -f pdf $(A2XDBLATEXOPTS) $(A2XOPTS) --icons man/apispec.txt --destination-dir=$(OUTDIR)
 
-$(OUTDIR)/apispec.html: $(CONFFILE) man/apispec.txt $(MANSOURCES) $(SVGFILES)
+$(OUTDIR)/apispec.html: $(CONFFILE) man/apispec.txt $(MANSOURCES) $(MANCOPYRIGHT) $(SVGFILES)
 	$(QUIET)if test ! -d $(OUTDIR) ; then $(MKDIR) $(OUTDIR) ; fi
-	$(QUIET)$(ASCIIDOC) $(ADOCOPTS) -d book -b html --out-file=$(OUTDIR)/apispec.html man/apispec.txt
+	$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) -d book -b html --out-file=$(OUTDIR)/apispec.html man/apispec.txt
 
 $(HTMLDIR)/images/%: images/%
 	$(QUIET)$(MKDIR) $(@D)