From 81ce46fe9bcef5e5182f3d4dee2136c7ee50dcfc Mon Sep 17 00:00:00 2001 From: Jon Leech Date: Tue, 6 Mar 2018 16:42:33 -0800 Subject: [PATCH] Update for 1.1 and marking 1.0 branch as obsolete. --- README.adoc | 63 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 38 insertions(+), 25 deletions(-) diff --git a/README.adoc b/README.adoc index 98bcec0a..6e4e2799 100644 --- a/README.adoc +++ b/README.adoc @@ -1,20 +1,31 @@ -Vulkan^(R)^ API Documentation Project -===================================== += Vulkan^(R)^ API Documentation Project This repository contains formal documentation of the Vulkan API. This -includes the main API Specification, the reference (man) pages, the XML API -Registry, and related tools and scripts. +includes the Specification of the Vulkan API, including extensions; the +reference ("`man`") pages; the XML API Registry; header files; and related +tools and scripts. -Single-Branch Model -------------------- +The authoritative public repository is located at +https://github.com/KhronosGroup/Vulkan-Docs/ . Issues, proposed fixes for +issues, and other suggested changes should be created using Github. -As of the 1.0.25 release, we have switched to a new "`single-branch`" model -in which all extensions are included in the source of the 1.0 branch of the -Specification, and can be configured in or out of the build using Makefile -options. -Repository Structure --------------------- +== Branch Structure + +With the release of Vulkan 1.1, the current Specification is now maintained +in the `master` branch of the repository. It is possible to generate both +Vulkan 1.1 and Vulkan 1.0 Specifications from this branch. + + +=== `1.0` Branch Is Obsolete + +The `1.0` branch in which the 1.0 Specification was previously maintained is +now obsolete. The `1.0` branch will not be updated going forward, and all +outstanding pull requests or merge requests against the `1.0` branch must be +rebased on, and retargeted to `master`. + + +== Directory Structure ``` README.adoc This file @@ -31,23 +42,25 @@ src/spec/ XML API Registry (vk.xml) and related scripts src/vulkan/ Vulkan headers, generated from the Registry ``` -Building the Specification and Reference Pages ----------------------------------------------- -As of the 1.0.40 release, we have moved from the old `asciidoc` toolchain to -a new one based on `asciidoctor`. See `doc/specs/vulkan/README.adoc` for -more information on installing the toolchain and building the Specification. +== Building the Specification and Reference Pages -Generating Headers and Related Files ------------------------------------- +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. -The header file (`src/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 exception of -`vulkan.h`, are not checked into the repository. If you change `vk.xml`, you -can regenerate the header by going to `src/spec` and running: - $ make clobber install +== Generating Headers and Related Files + +The header files (`src/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 +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 +running: + + $ make clean install The other generated files are built as required via dependencies in `doc/specs/vulkan/Makefile` .