Update README

- make sentence a list for lesser cognitive strain
- add references to Vulkan-Headers repo
- add reference to Vulkan-Ecosystem repo
- separate obsolete and irrelevant info from the basic info
- update directory tree
- add\convert to links (for easier navigation)
- lots of frivolous changes

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
+This repository contains sources for the formal documentation of the Vulkan
-includes the Specification of the Vulkan API, including extensions; the
+API. This includes:
-reference ("`man`") pages; the XML API Registry; header files; and related
+
-tools and scripts.
+[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
+https://github.com/KhronosGroup/Vulkan-Docs/.
-issues, and other suggested changes should be created using Github.
+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
+Everything is now maintained in the `master` branch of the repository.
-in the `master` branch of the repository. It is possible to generate both
+From this branch it is possible to generate both Vulkan 1.1 and Vulkan 1.0
-Vulkan 1.1 and Vulkan 1.0 Specifications from this branch.
+Specifications, as well as specifications for any set of Extensions.
 
-
+[NOTE]
-=== `1.0` Branch Is Obsolete
+====
-
+Old revisions of the repository maintained the Vulkan 1.0 Specification in
-The `1.0` branch in which the 1.0 Specification was previously maintained is
+the `1.0` branch, and extensions in the `1.0-VK_EXTENSION_NAME`.
-now obsolete. The `1.0` branch will not be updated going forward, and all
+These branches are now **obsolete**, and contain only very old versions of
-outstanding pull requests or merge requests against the `1.0` branch must be
+the Specification (and extensions).
-rebased on, and retargeted to `master`.
+====
 
 
 == Directory Structure
 
-The directory structure was changed following the 1.1.70 spec update to move
+The directory structure is as follows:
-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
+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/                 asciidoc configuration
+config/               Asciidoctor 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
+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
-src/ext_loader/         Extension loader library
+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
+The document sources are marked up in Asciidoctor format, and we use
-asciidoctor and related toolchain components to generate output documents.
+`asciidoctor` and related toolchain components to generate output documents.
-See `BUILD.adoc` for more information on installing the toolchain and
+See link:BUILD.adoc[BUILD.adoc] for more information on installing the
-building the Specification.
+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
+in the XML API Registry (`xml/vk.xml`).
-exception of header files, are not checked into the repository. If you
+The generated files (with the exception of header files) are not checked
-change `vk.xml`, you can regenerate the header by going to `xml/` and
+into the repository.
-running:
+If you change `vk.xml`, you can regenerate the header by going into `xml/`
+and running:
 
     $ make clean install