// Copyright (c) 2014-2016 Khronos Group. This work is licensed under a // Creative Commons Attribution 4.0 International License; see // http://creativecommons.org/licenses/by/4.0/ Vulkan Documentation and Extensions: Procedures and Conventions =============================================================== Jon Leech, Tobias Hector include::specversion.txt[] :toc2: :toclevels: 3 :max-width: 100 :numbered: :doctype: book :imagewidth: 800 :fullimagewidth: {svgpdf@pdf:scaledwidth="75%":width="800"} :cl: : :leveloffset: 1 // :icons: // :toc-placement: manual <<<< include::copyright-ccby.txt[] <<<< [[introduction]] = Introduction This document contains required procedures and conventions when writing specifications for new Vulkan APIs, extensions and layers, or related Khronos documentation such as white papers and tutorials; or contributing to existing Vulkan specifications. These are collectively referred to as _Vulkan Documentation_ or just _documentation_ below. The primary focus is the API Specification and API extensions, although all of the markup and most of the writing style is equally applicable to other documentation. The primary purpose is to achieve consistency across the API, as well as across all of our source and output documents. Consistency makes it easier for developers, editors, reviewers, and users of our documentation to understand and modify it. This document is now formally voted on and approved by the Vulkan Working Group. This means that unless explicitly stated otherwise, the procedures and conventions must be followed If you have a strong desire to modify the procedures and conventions, such changes must be made through the normal Vulkan Working Group processes. [[introduction-terminology]] == Terminology The key words *must*, *must not*, *required*, *shall*, *shall not*, *should*, *should not*, *recommend*, *may*, and *optional* in this document are to be interpreted as described in RFC 2119 and by the Vulkan 1.0 Specification in the ``Terminology'' section. [[introduction-structure]] == Document Structure The style guide is broken into four sections: * <> - the required rules for choosing names of Vulkan identifiers of all types. * <> - the required procedures for creating formal Vulkan extensions and layers. * <> - the required and recommended markup style for writing asciidoc and XML source that follows consistent formatting and layout guidelines, tags special terms and phrases for proper processing by the spec generation tools, etc. * <> - the required and recommended writing style for overall and fine-grained structure and conventions, normative language use, API naming conventions, common words and phrases to use and to avoid, linking and cross-referencing, etc. [[introduction-asciidoc]] == Asciidoc Markup Vulkan Documentation is primarily written in Asciidoc, a form of text markup language. Asciidoc is documented on its website at http://www.asciidoc.org/. [[userguide]] References to the Asciidoc User Guide are to sections in the document at http://asciidoc.org/userguide.html . Asciidoc packages are available for Linux, MacOS, and Microsoft Windows, together with the other toolchain components required to generate output documents corresponding to the markup. [NOTE] .Note ==== We are currently using the original _asciidoc_ tool. Other tools to process Asciidoc markup, such as _asciidoctor_, are also available, but are not currently usable for our documents. While asciidoctor supports the basic Asciidoc markup syntax, it does not support asciidoc macros, which are used extensively in the documentation. We expect to transition from asciidoc to asciidoctor eventually. There may be minor effects on markup and if so, we will document them at the time of the transition. ==== The asciidoc toolchain and build process are not addressed by this document, which concentrates solely on source documents. [[introduction-normative]] == Normative References Normative references are references to external documents or resources to which documentation authors must comply. [[KhronosGroup/Vulkan-Docs]]:: Khronos Vulkan Working Group, +KhronosGroup/Vulkan-Docs+ project on GitHub, https://github.com/KhronosGroup/Vulkan-Docs, July 5, 2016. [[Vulkan API Specification]]:: Vulkan Working Group, _Vulkan 1.0.19 - A Specification_, https://www.khronos.org/registry/vulkan/, July 1, 2016. Version 1.0.19 is the latest patch release of the Vulkan API Specification as of the time this reference was created, but that Specification is frequently updated with minor bugfixes and clarifications. When a more recent patch release is made, it becomes the normative reference for the API. // Chapters of the text are included below include::style/naming.txt[] include::style/extensions.txt[] include::style/markup.txt[] include::style/writing.txt[] = Still To Be Done * Something about Image formats * Something about validation scripts * Something about pictures * Glossary lists * New param/enum macros = Revision History * August 30, 2016 - remove mustnot{cl} and shouldnot{cl} macro definitions, which are no longer used in the Specification (internal issue 407). * August 29, 2016 - Add spelling and compound word rules (public issue 352). * August 23, 2016 - Modify description of specifying extensions in the <> chapter to refer to the new single-branch model for extensions (internal issue 397). * July 26, 2016 - Add section describing <>. * July 18, 2016 - Add examples of function-parameter and structure-member markup (based on public issue 286). * July 11, 2016 - Change the document title. * July 7, 2016 - Rename document, change license to CC BY, clarify required and recommended actions, and reserve use of ``normative'' for the Specifications. * June 26, 2016 - Move Layers and Extensions chapter from Appendix C of the Vulkan API Specification and merge content with the naming guide. Put extension and naming chapters into their own source files. * June 20, 2016 - Add API naming guide. * May 22, 2016 - Add markup and image creation rules, after fixing missing figure captions for public issue 219. * May 1, 2016 - Include feedback from public issues 120 and 190. Use consistent conventions for defining structures. Use American rather than British spelling conventions. * March 12, 2016 - Recommend against "the value of". * February 26, 2016 - Replace use of the "maynot{cl}" macro with "may{cl} not". * February 16, 2016 - Place asciidoc conversion post-release. * February 9, 2016 - Added quotation mark convention. * February 1, 2016 - add the Oxford Comma section and issue resolution. * January 26, 2016 - add bullet-list style description of command parameters. * January 11, 2016 - add ``Numbers in Text'' section from WSI work. * December 16, 2015 - Make ``begin / end'' preferred terms to ``start / finish''. * December 15, 2015 - Make ``implementation'' preferred term instead of ``system''. * December 13, 2015 - Add tlink{cl}/tname{cl} macros for function pointer types. * December 10, 2015 - Initial release for feedback.