// Copyright 2014-2021 The Khronos Group Inc. // // SPDX-License-Identifier: CC-BY-4.0 = Vulkan^®^ Documentation and Extensions: Procedures and Conventions Jon Leech, Tobias Hector :data-uri: :icons: font :toc2: :toclevels: 3 :numbered: :source-highlighter: rouge :rouge-style: github :doctype: book :imagewidth: 800 :fullimagewidth: width="800" :cl: : // Various special / math symbols. This is easier to edit with than Unicode. include::{config}/attribs.txt[] // Where the current Asciidoctor documentation is found. :docguide: https://docs.asciidoctor.org/asciidoc/latest :leveloffset: 1 <<<< include::{config}/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^{reg}^ 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*, *required*, *should*, *recommend*, *may*, and *optional* in this document are to be interpreted as described in RFC 2119 and by the Vulkan 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 asciidoctor 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]] == Asciidoctor Markup Vulkan Documentation is primarily written in Asciidoctor, a text markup language. We use the command-line asciidoctor client that is actively maintained by asciidoctor, which is documented on its website at https://asciidoctor.org. References to the Asciidoctor User Manual are to sections in the document at https://asciidoctor.org/docs/user-manual/. Asciidoctor is implemented in Ruby (https://www.ruby-lang.org/), which is available for Linux, MacOS, and Microsoft Windows. [NOTE] .Note ==== There are other implementations of asciidoctor, such as AsciidoctorJ (https://github.com/asciidoctor/asciidoctorj) and asciidoctor.js (https://github.com/asciidoctor/asciidoctor.js). In particular, GitHub and GitLab both have preview renderers for .adoc or .asciidoc files in repositories, and live preview extensions exist for Chrome and Firefox. However, because of the use of custom Ruby macros in the Vulkan Specification toolchain, and the high complexity of the documents and toolchain used to generate it, these web tools cannot currently render the Specification from source. Instead, we generate HTML and PDF versions of the Specification and publish them on the Khronos website. The Asciidoctor 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. [[acm-references]] Association for Computing Machinery. _Citation Style and Reference Formats_. Retrieved July 27, 2019. https://www.acm.org/publications/authors/reference-formatting . [[iso-8601]] International Organization for Standardization. _Data elements and interchange formats -- Information interchange -- Representation of dates and times_ (2004-12-01). https://www.iso.org/standard/40874.html . Also see https://www.w3.org/QA/Tips/iso-date for colloquial examples. [[vulkan-docs]] Khronos Vulkan Working Group. `KhronosGroup/Vulkan-Docs` project on GitHub (July 5, 2016). https://github.com/KhronosGroup/Vulkan-Docs . [[vulkan-spec]] Khronos Vulkan Working Group. _Vulkan 1.1.116 - A Specification_ (July 20, 2019). https://www.khronos.org/registry/vulkan/ . Version 1.1.116 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[] include::style/misc.txt[] // Appendices are included below include::style/vuid.txt[] = Revision History * 2021-11-04 - Remove backquote markup around recommended use of the `apiext:` macro, since that macro now styles the extension name argument itself. * 2021-10-29 - add "`render pass" to the <> section. * 2021-10-04 - Update the <> section to require use of the `apiext:` macro for links to extension names (internal issue 2831). * 2021-09-12 - Add a new subsection with more details on using tilde-delimited source blocks <>, and rewrite the <> section to follow current phrasing and markup patterns (internal issue 2040). * 2021-09-09 - Add the <> section to clarify how to write wildcard enumerant names with imbedded italicized text. * 2021-09-06 - Add the <> section based on the Khronos Inclusive Language list (internal issue 2293). * 2021-09-06 - add "`cube map`" to the <> section (internal merge request 4794). * 2021-07-20 - Add additional contraction examples to the table in the <> section. * 2021-05-31 - Add "`implementation-dependent`" as an exception in the <> section (internal merge request 4611). * 2021-05-24 - Add escapes to prevent expansion of attribute names in a few places where markup examples are given. * 2021-05-22 - Expand the <> to include avoiding abbreviations, as well as contractions. * 2021-05-07 - Add <>. * 2021-04-28 - Add <>. * 2021-04-28 - Add <> which may be `NULL` or dname:VK_NULL_HANDLE, respectively (internal issue 2662). * 2021-04-14 - Add "`side effect`" and "`reuse`" as <> (public issue 1484). * 2021-03-31 - Update description of the code{cl} macro in the <> section to match current behavior. * 2021-03-21 - Note that the <> for the same purpose in comparable 32- and 64-bit bitmask types (internal issue 2565). * 2020-09-14 - Change <> section to track actual usage and update the description of the undefined{cl} macro to further clarify its purpose and uses (internal issue 2195). * 2020-08-16 - Add "`reference monitor`" to the preferred <> (internal issue 2291). * 2020-08-10 - Add a <> section to guide authors of new commands (internal issue 2290). * 2020-07-28 - Add a <> section describing how to properly attribute this information. * 2020-06-23 - Update the <> section to recommend placing most extension language inline in existing specification source files, rather than in separate files, and to base extension revision numbers at `1` starting with initial public release (public issue 1263). * 2020-04-29 - Expand use of `basetype` macros to include external API types. * 2020-03-16 - Add documentation of writing links to extension appendices in the <> section and document the apiext{cl} and reflink{cl} macros in the <> section. Improve documentation of writing <> including how to mark up content in the Specification source so it only appears in generated reference pages; however, this section is still out of date (internal issue 1999). * 2020-03-11 - Specify in the <> section that a valid usage statement must be defined at the place (command or structure specification) that all information need to evaluate the statement is known. Update the description of <> to match the current scripts. Use the term "`asciidoctor`" instead of "`asciidoc`" everywhere. Note in the <> section that the Specification can only be built using the command-line asciidoctor client, not by asciidoctor web clients. * 2020-02-22 - Document that it is no longer needed to escape C arrows in macros. * 2019-12-15 - Add a markup section on <> (internal issue 1110). * 2019-11-27 - Expand the <> section and make all spec language consistent with it (internal issue 1814). * 2019-09-09 - Define markup for nested structure members in the <> section (internal issue 1765). * 2019-09-08 - Add language to the end of the <> section describing how to mark up asciidoctor conditionals (internal issue 1808). * 2019-08-25 - Add the <> section (internal issue 1793). * 2019-08-25 - Add the <> section (internal issue 979) and the <> section (internal issue 747). Disallow use of standalone `+` except in latexmath and source blocks, in the <> section (internal issue 736). * 2019-08-19 - Add the <> section (internal issue 1553). * 2019-08-13 - Add a NOTE to the <> appendix specifying allowed characters in VUID tags (based on discussion for internal merge request 3239). * 2019-07-27 - Add the <> section and rewrite external references accordingly. * 2019-05-09 - Specify rules for defining <> (internal issue 1649). * 2019-01-06 - Add details on <> (internal issue 1411). * 2018-11-19 - Add details to the <> section including the new "`Description`" section, and other standard parts of extension appendices. * 2018-08-13 - Add %inline directive to the <> section (public pull request 734). * 2018-07-30 - Added a section on <> (as part of the fixes for public issue 379), and describing why the undefined{cl} macro should always be used. * 2018-07-08 - Remove requirement to explicitly include extension appendices in the <> section. * 2018-06-25 - Modify the process for <> to define vendor ID values as part of an enumerated type. * 2018-03-07 - Updated for Vulkan 1.1 release. * 2018-01-10 - Move details of mandated extension compatibility from the <> section into the Fundamentals section of the API Specification, where they are changed slightly to allow explicit incompatibilies (public issue 638). * 2017-10-27 - Add language about proper use of "`valid pointer`" and "`pointer to valid object`" for valid usage statements, in the <> section (related to public pull request 547). * 2017-10-15 - Describe how to write <> (internal issue 908). * 2017-10-15 - Add more details of <> (public issues 536, 580). * 2017-09-10 - Add descriptions of <> to refer to properties of elments of arrays (internal issue 884). * 2017-09-10 - Add <> language specifying where to describe interactions of structures in a pname:pNext chain (internal issue 715). * 2017-09-10 - Add example of marking up an enumerated type all of whose values are defined by extensions (internal issue 864). * 2017-08-25 - Add language to the <> chapter describing how to write new API versions (internal issue 892). * 2017-06-12 - Add sections describing when to use the <> and <> markup macros instead of the *link{cl} macros, and clarify that slink{cl} should be used for handle as well as structure names (internal issue 886). * 2017-05-08 - Add appendix describing <> and how they're generated. * 2017-03-19 - Add naming rule for <>. * 2017-02-11 - Finish transitioning to asciidoctor markup. * 2016-09-28 - Add asciidoc math markup guidelines. * 2016-09-16 - Make style guide markup more consistent with its own recommendations. Simplify some tables of preferred terms. Add sections on block and table markup. * 2016-09-12 - Describe writing and markup style for labelled lists. Require use of the ISO 8601 date format except in rare legacy cases. Expand the description of <> and add a description of markup for <>. * 2016-09-08 - Add a writing section about proper use of <> (internal issue 432). * 2016-08-30 - Remove mustnot{cl} and shouldnot{cl} macro definitions, which are no longer used in the Specification (internal issue 407). * 2016-08-29 - Add spelling and compound word rules (public issue 352). * 2016-08-23 - Modify description of specifying extensions in the <> chapter to refer to the new single-branch model for extensions (internal issue 397). * 2016-07-26 - Add section describing <>. * 2016-07-18 - Add examples of function-parameter and structure-member markup (based on public issue 286). * 2016-07-11 - Change the document title. * 2016-07-07 - Rename document, change license to CC BY, clarify required and recommended actions, and reserve use of "`normative`" for the Specifications. * 2016-06-26 - 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. * 2016-06-20 - Add API naming guide. * 2016-05-22 - Add markup and image creation rules, after fixing missing figure captions for public issue 219. * 2016-05-01 - Include feedback from public issues 120 and 190. Use consistent conventions for defining structures. Use American rather than British spelling conventions. * 2016-03-12 - Recommend against "the value of". * 2016-02-26 - Replace use of the "maynot{cl}" macro with "may{cl} not". * 2016-02-16 - Place asciidoc conversion post-release. * 2016-02-09 - Added quotation mark convention. * 2016-02-01 - Add the Oxford Comma section and issue resolution. * 2016-01-26 - Add bullet-list style description of command parameters. * 2016-01-11 - Add "`Numbers in Text`" section from WSI work. * 2015-12-16 - Make "`begin / end`" preferred terms to "`start / finish`". * 2015-12-15 - Make "`implementation`" preferred term instead of "`system`". * 2015-12-13 - Add tlink{cl}/tname{cl} macros for function pointer types. * 2015-12-10 - Initial release for feedback.