Merge pull request #834 from krOoze/update_readme

Update README

README.adoc

@@ -1,69 +1,94 @@
+ifdef::env-github[]
+:note-caption: :information_source:
+endif::[]
+
 = Vulkan^(R)^ API Documentation Project
 
-This repository contains formal documentation of the Vulkan API. This
-includes the Specification of the Vulkan API, including extensions; the
-reference ("`man`") pages; the XML API Registry; header files; and related
-tools and scripts.
+This repository contains sources for the formal documentation of the Vulkan
+API. This includes:
+
+[options="compact"]
+ * the Vulkan API Specification
+ * specification of Vulkan Extensions
+ * the reference ("`man`") pages
+ * the XML API Registry (also mirrored at
+   https://github.com/KhronosGroup/Vulkan-Headers)
+ * Vulkan header files (also mirrored at
+   https://github.com/KhronosGroup/Vulkan-Headers)
+ * related tools and scripts.
 
 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.
+https://github.com/KhronosGroup/Vulkan-Docs/.
+It hosts public Issue tracker, and accepts patches (Pull Requests) from the
+general public.
+
+If in doubt where to submit your Issue consult the
+https://github.com/KhronosGroup/Vulkan-Ecosystem repo.
 
 
 == 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.
+Everything is now maintained in the `master` branch of the repository.
+From this branch it is possible to generate both Vulkan 1.1 and Vulkan 1.0
+Specifications, as well as specifications for any set of Extensions.
 
-
-=== `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`.
+[NOTE]
+====
+Old revisions of the repository maintained the Vulkan 1.0 Specification in
+the `1.0` branch, and extensions in the `1.0-VK_EXTENSION_NAME`.
+These branches are now **obsolete**, and contain only very old versions of
+the Specification (and extensions).
+====
 
 
 == 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.
-
+The directory structure is as follows:
 
 ```
-README.adoc             This file
-BUILD.adoc              Build targets and methods for the specification
-ChangeLog.txt           Change log summary for each public spec update
-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
+README.adoc           This file
+BUILD.adoc            Documents how to build the specifications, and man pages
+COPYING.md            Copyright and licensing information
+CODE_OF_CONDUCT.md    Code of Conduct
+ChangeLog.txt         Change log summary for each public spec update
+Makefile, make*       Makefile and helper build scripts (see BUILD.adoc)
+appendices/           Specification appendices
+chapters/             Specification chapters
+config/               Asciidoctor configuration
+images/               Images (figures, diagrams, icons)
+include/vulkan/       Vulkan headers, generated from the Registry
+man/                  Reference (man) pages for the API; mostly extracted from the spec source
+out/                  Default directory for the generated documents
+scripts/              Related scripts (but many scripts are still in the root or xml/ directory)
+src/ext_loader/       Extension loader library (deprecated)
+style/                Sources for "styleguide" (Vulkan Documentation and Extensions: Procedures and Conventions)
+xml/                  XML API Registry (vk.xml) and related scripts
+registry.txt          Sources for documentation of the vk.xml format
 ```
 
+This structure was adopted following 1.1.70 spec update.
+There may be additional cleanup and simplification in the future.
+
 
 == Building the Specification and Reference Pages
 
-The document sources are marked up in `asciidoctor` format, and we use
-asciidoctor and related toolchain components to generate output documents.
-See `BUILD.adoc` for more information on installing the toolchain and
-building the Specification.
+The document sources are marked up in Asciidoctor format, and we use
+`asciidoctor` and related toolchain components to generate output documents.
+See link:BUILD.adoc[BUILD.adoc] for more information on installing the
+toolchain and building the Specification.
 
 
 == Generating Headers and Related Files
 
+See link:xml/README.adoc[xml/README.adoc].
+
 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 (`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 `xml/` and
-running:
+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 into `xml/`
+and running:
 
     $ make clean install