diff --git a/README.adoc b/README.adoc index 2282e3fc..4af5bdf1 100644 --- a/README.adoc +++ b/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