Restructure the repository to put the specification Makefile and

associated material at the top level, vk.xml and associated material in
xml/, and generated include and source files in include/vulkan/ and
src/ext_loader/, respectively (public issue 436).

.gitattributes

@@ -1,10 +1,10 @@
 # These bash scripts must use Unix-style line ending on all platforms.
-doc/specs/vulkan/installRelease text eol=lf
-doc/specs/vulkan/makeAllExts text eol=lf
-doc/specs/vulkan/makeExt text eol=lf
-doc/specs/vulkan/makeKHR text eol=lf
-doc/specs/vulkan/sandboxCopy text eol=lf
-doc/specs/vulkan/config/optimize-pdf text eol=lf
-doc/specs/vulkan/scripts/checkXrefs text eol=lf
+installRelease text eol=lf
+makeAllExts text eol=lf
+makeExt text eol=lf
+makeKHR text eol=lf
+sandboxCopy text eol=lf
+config/optimize-pdf text eol=lf
+scripts/checkXrefs text eol=lf
 
 *.sh text eol=lf

.gitignore

@@ -37,17 +37,17 @@ __pycache__
 # Spec build generated, temporary, and output files
 
 # Files generated from vk.xml
-doc/specs/vulkan/api
-doc/specs/vulkan/hostsynctable
-doc/specs/vulkan/validity
-doc/specs/vulkan/appendices/meta
+api
+hostsynctable
+validity
+appendices/meta
 
 # Files generated by extraction from spec source
-doc/specs/vulkan/man/PFN*.txt
-doc/specs/vulkan/man/[Vv][Kk]*.txt
+man/PFN*.txt
+man/[Vv][Kk]*.txt
 
 # Files otherwise generated by the Makefile
-doc/specs/vulkan/specversion.txt
+specversion.txt
 
 # Output files and directories
 out/1.0*
@@ -60,4 +60,4 @@ src/spec/diag.txt
 .DS_Store
 
 # Auto-generated files
-# doc/specs/vulkan/*/timeMarker
+# */timeMarker

doc/specs/vulkan/README.adoc → BUILD.adoc

@@ -13,8 +13,14 @@ specification and reference pages building properly.
 [[building]]
 == Building The Spec
 
-Once you have all the right tools installed (see <<depends,Software
-Dependencies>> below), go to `...path-to-git-repo/doc/specs/vulkan` .
+First, clone the Khronos Github repository containing the Vulkan
+specification to your local Linux, Windows, or Mac PC. The repository is
+located at https://github.com/KhronosGroup/Vulkan-Docs/ .
+
+Next, install all the necessary build tools (see <<depends,Software
+Dependencies>> below).
+
+Finally, go to the root directory of your local repository clone, and
 
     $ make html
 
@@ -40,9 +46,8 @@ builds the spec targets `html`, `pdf`, `styleguide`, `manhtml`, `manpdf`,
 ====
 
 These targets generate a variety of output documents in the directory
-specified by the Makefile variable `$(OUTDIR)` (by default,
-`../../../out/1.0`).
-The checked-in file `../../../out/1.0/index.html` links to all these
+specified by the Makefile variable `$(OUTDIR)` (by default, `out`).
+The checked-in file `out/index.html` links to all these
 targets, or they can individually be found as follows:
 
   * API spec:
@@ -84,7 +89,7 @@ may significantly speed up the reference page builds.
 
 If you see an error like this from the `pdf` target:
 
-    /home/jon/.rbenv/versions/2.3.3/lib/ruby/gems/2.3.0/gems/ruby-enum-0.7.1/lib/ruby-enum/enum.rb:34:in `const_set': asciidoctor: FAILED: /home/tree/git/vulkan/doc/specs/vulkan/vkspec.txt: Failed to load AsciiDoc document - wrong constant name default (NameError)
+    /home/jon/.rbenv/versions/2.3.3/lib/ruby/gems/2.3.0/gems/ruby-enum-0.7.1/lib/ruby-enum/enum.rb:34:in `const_set': asciidoctor: FAILED: /home/tree/git/vulkan/vkspec.txt: Failed to load AsciiDoc document - wrong constant name default (NameError)
 
 then try <<ruby-enum-downgrade,downgrading ruby-enum>>
 as described below
@@ -325,7 +330,7 @@ LaTeX math markup delimiters are now inserted by the asciidoctor toolchain.
 
 LaTeX math is passed through unmodified to all HTML output forms, which is
 subsequently rendered with the KaTeX engine when the HTML is loaded.
-A local copy of the KaTeX release is kept in `doc/specs/vulkan/katex` and
+A local copy of the KaTeX release is kept in `katex/` and
 copied to the HTML output directory during spec generation.
 Math is processed into SVGs via asciidoctor-mathematical for PDF output.
 
@@ -359,7 +364,7 @@ In general the anchor should immediately precede the chapter or section
 title and should use the form '+++[[chapter-section-label]]+++'.
 For example,
 
-For example, in chapter +synchronization.txt+:
+For example, in chapter `synchronization.txt`:
 
 ----
 [[synchronization-primitives]]
@@ -394,7 +399,9 @@ Fences are used with the +++<<vkQueueSubmit>>+++ command...
 This section describes the software components used by the Vulkan spec
 toolchain.
 
-Before building the Vulkan spec, you must install the following tools:
+Before building the Vulkan spec, you must install the following tools.
+Minimum versions known to be working are shown. Later versions will probably
+work at least as well.
 
   * GNU make (make version: 4.0.8-1; older versions probably OK)
   * Python 3 (python, version: 3.4.2)
@@ -427,7 +434,7 @@ parts you don't use) completely before trying to install.
   * https://github.com/asciidoctor/asciidoctor-mathematical#dependencies[Dependencies
     for asciidoctor-mathematical] (There are a lot of these!)
   * KaTeX distribution (version 0.7.0 from https://github.com/Khan/KaTeX .
-    This is cached under `doc/specs/vulkan/katex/`, and need not be
+    This is cached under `katex/`, and need not be
     installed from github.
 
 .Note
@@ -823,30 +830,25 @@ gem install --pre asciidoctor-pdf
 
 *ruby-enum*
 
-As of 2017-03-06, there appears to be a problem with the ruby-enum version
-0.7.1 gem which breaks the PDF build. Make sure you are using ruby-enum
-0.7.0, as follows:
-
-    gem uninstall ruby-enum
-    gem install -v 0.7.0 ruby-enum
-
-Hopefully this will soon be fixed. See
-https://github.com/gjtorikian/mathematical/issues/69 for a report of this
-problem.
+Make sure you are using ruby-enum 0.7.1 or later, and mathematical 1.6.8 or
+later. If you are forced to use earlier versions, see
+https://github.com/gjtorikian/mathematical/issues/69 for a report of a
+related versioning problem.
 
 
 *prawn*
 
-As of 2017-03-20, there are incompatibilities between asciidoctor-pdf and
-certain versions of prawn and prawn-templates affecting the PDF build. Make
-sure to update to prawn 2.2.1 and prawn-templates 0.0.5. See
-
+Make sure you are using prawn 2.2.1 or later, and prawn-templates 0.0.5 or
+later. Incompatibilities between asciidoctor-pdf and earlier versions of
+these gems affects the PDF build. See
 https://github.com/KhronosGroup/Vulkan-Docs/issues/476
 
 
 [[history]]
 == Revision History
 
+  * 2018-03-13 - Rename to BUILD.adoc and update for new directory
+    structure.
   * 2018-03-05 - Update README for Vulkan 1.1 release.
   * 2017-03-20 - Add description of prawn versioning problem and how to fix
     it.

doc/specs/vulkan/Makefile → Makefile

@@ -84,7 +84,7 @@ GS_EXISTS := $(shell command -v gs 2> /dev/null)
 # HTMLDIR - 'html' target
 # PDFDIR - 'pdf' target
 # CHECKDIR - 'allchecks' target
-OUTDIR	  := $(CURDIR)/../../../out/1.0
+OUTDIR	  := $(CURDIR)/out
 HTMLDIR   := $(OUTDIR)/html
 VUDIR	  := $(OUTDIR)/validation
 PDFDIR	  := $(OUTDIR)/pdf
@@ -407,7 +407,7 @@ checklinks: vkapi.py
 # $(EXTOPTIONS) specifies the extensions which are included in these
 # targets, and is set above based on $(EXTENSIONS).
 
-REGISTRY = ../../../src/spec
+REGISTRY = xml
 VKXML	 = $(REGISTRY)/vk.xml
 GENVK	 = $(REGISTRY)/genvk.py
 GENVKOPTS= $(VERSIONOPTIONS) $(EXTOPTIONS) -registry $(VKXML)

README.adoc

@@ -27,18 +27,23 @@ rebased on, and retargeted to `master`.
 
 == Directory Structure
 
+The directory structure was changed following the 1.1.70 spec update to move
+the specification directory to the root of the repository, and move other
+content relative to that. There may be additional cleanup and simplification
+in the future.
+
+
 ```
 README.adoc             This file
+BUILD.adoc              Build targets and methods for the specification
 ChangeLog.txt           Change log summary for each public spec update
-doc/specs/              Main documentation tree
-    vulkan/             Vulkan specification
-        appendices/     Appendices - one file each
-        chapters/       Chapters - one file each
-        config/         asciidoc configuration
-        images/         Images (figures, diagrams, icons)
-        man/            Reference (manual) pages for API, mostly extracted from the spec source
-src/spec/               XML API Registry (vk.xml) and related scripts
-src/vulkan/             Vulkan headers, generated from the Registry
+appendices/             Specification appendices
+chapters/               Specification chapters
+config/                 asciidoc configuration
+images/                 Images (figures, diagrams, icons)
+include/vulkan/         Vulkan headers, generated from the Registry
+man/                    Reference (manual) pages for API, mostly extracted from the spec source
+xml/                    XML API Registry (vk.xml) and related scripts
 src/ext_loader/         Extension loader library
 ```
 
@@ -47,20 +52,20 @@ src/ext_loader/         Extension loader library
 
 The document sources are marked up in `asciidoctor` format, and we use
 asciidoctor and related toolchain components to generate output documents.
-See `doc/specs/vulkan/README.adoc` for more information on installing the
-toolchain and building the Specification.
+See `BUILD.adoc` for more information on installing the toolchain and
+building the Specification.
 
 
 == Generating Headers and Related Files
 
-The header files (`src/vulkan/vulkan*.h`) and many parts of the
+The header files (`include/vulkan/vulkan*.h`) and many parts of the
 specification and reference page documents are generated from descriptions
-in the XML API Registry (`src/spec/vk.xml`). The generated files, with the
+in the XML API Registry (`xml/vk.xml`). The generated files, with the
 exception of header files, are not checked into the repository. If you
-change `vk.xml`, you can regenerate the header by going to `src/spec` and
+change `vk.xml`, you can regenerate the header by going to `xml/` and
 running:
 
     $ make clean install
 
 The other generated files are built as required via dependencies in
-`doc/specs/vulkan/Makefile` .
+the top-level `Makefile`.