1// Copyright 2014-2021 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5= Vulkan^®^ Documentation and Extensions: Procedures and Conventions 6Jon Leech, Tobias Hector 7:data-uri: 8:icons: font 9:toc2: 10:toclevels: 3 11:numbered: 12:source-highlighter: rouge 13:rouge-style: github 14:doctype: book 15:imagewidth: 800 16:fullimagewidth: width="800" 17:cl: : 18 19// Various special / math symbols. This is easier to edit with than Unicode. 20include::{config}/attribs.txt[] 21 22// Where the current Asciidoctor documentation is found. 23:docguide: https://docs.asciidoctor.org/asciidoc/latest 24 25:leveloffset: 1 26 27<<<< 28 29include::{config}/copyright-ccby.txt[] 30 31<<<< 32 33[[introduction]] 34= Introduction 35 36This document contains required procedures and conventions when writing 37specifications for new Vulkan APIs, extensions and layers, or related 38Khronos^{reg}^ documentation such as white papers and tutorials; or 39contributing to existing Vulkan specifications. 40These are collectively referred to as _Vulkan Documentation_ or just 41_documentation_ below. 42The primary focus is the API Specification and API extensions, although all 43of the markup and most of the writing style is equally applicable to other 44documentation. 45 46The primary purpose is to achieve consistency across the API, as well as 47across all of our source and output documents. 48Consistency makes it easier for developers, editors, reviewers, and users of 49our documentation to understand and modify it. 50 51This document is now formally voted on and approved by the Vulkan Working 52Group. 53This means that unless explicitly stated otherwise, the procedures and 54conventions must be followed. 55If you have a strong desire to modify the procedures and conventions, such 56changes must be made through the normal Vulkan Working Group processes. 57 58 59[[introduction-terminology]] 60== Terminology 61 62The key words *must*, *required*, *should*, *recommend*, *may*, and 63*optional* in this document are to be interpreted as described in RFC 2119 64and by the Vulkan Specification in the "`Terminology`" section. 65 66 67[[introduction-structure]] 68== Document Structure 69 70The style guide is broken into four sections: 71 72 * <<naming,API Naming Conventions>> - the required rules for choosing 73 names of Vulkan identifiers of all types. 74 * <<extensions,Extensions and Layers>> - the required procedures for 75 creating formal Vulkan extensions and layers. 76 * <<markup,Markup Style>> - the required and recommended markup style for 77 writing asciidoctor and XML source that follows consistent formatting 78 and layout guidelines, tags special terms and phrases for proper 79 processing by the spec generation tools, etc. 80 * <<writing,Writing Style>> - the required and recommended writing style 81 for overall and fine-grained structure and conventions, normative 82 language use, API naming conventions, common words and phrases to use 83 and to avoid, linking and cross-referencing, etc. 84 85 86[[introduction-asciidoc]] 87== Asciidoctor Markup 88 89Vulkan Documentation is primarily written in Asciidoctor, a text markup 90language. 91We use the command-line asciidoctor client that is actively maintained by 92asciidoctor, which is documented on its website at https://asciidoctor.org. 93 94References to the Asciidoctor User Manual are to sections in the document at 95https://asciidoctor.org/docs/user-manual/. 96 97Asciidoctor is implemented in Ruby (https://www.ruby-lang.org/), which is 98available for Linux, MacOS, and Microsoft Windows. 99 100[NOTE] 101.Note 102==== 103There are other implementations of asciidoctor, such as AsciidoctorJ 104(https://github.com/asciidoctor/asciidoctorj) and asciidoctor.js 105(https://github.com/asciidoctor/asciidoctor.js). 106In particular, GitHub and GitLab both have preview renderers for .adoc or 107.asciidoc files in repositories, and live preview extensions exist for 108Chrome and Firefox. 109 110However, because of the use of custom Ruby macros in the Vulkan 111Specification toolchain, and the high complexity of the documents and 112toolchain used to generate it, these web tools cannot currently render the 113Specification from source. 114Instead, we generate HTML and PDF versions of the Specification and publish 115them on the Khronos website. 116 117The Asciidoctor toolchain and build process are not addressed by this 118document, which concentrates solely on source documents. 119==== 120 121 122[[introduction-normative]] 123== Normative References 124 125Normative references are references to external documents or resources to 126which documentation authors must comply. 127 128[[acm-references]] 129Association for Computing Machinery. 130_Citation Style and Reference Formats_. 131Retrieved July 27, 2019. 132https://www.acm.org/publications/authors/reference-formatting . 133 134[[iso-8601]] 135International Organization for Standardization. 136_Data elements and interchange formats -- Information interchange -- 137Representation of dates and times_ (2004-12-01). 138https://www.iso.org/standard/40874.html . 139Also see https://www.w3.org/QA/Tips/iso-date for colloquial examples. 140 141[[vulkan-docs]] 142Khronos Vulkan Working Group. 143`KhronosGroup/Vulkan-Docs` project on GitHub (July 5, 2016). 144https://github.com/KhronosGroup/Vulkan-Docs . 145 146[[vulkan-spec]] 147Khronos Vulkan Working Group. 148_Vulkan 1.1.116 - A Specification_ (July 20, 2019). 149https://www.khronos.org/registry/vulkan/ . 150 151Version 1.1.116 is the latest patch release of the Vulkan API Specification 152as of the time this reference was created, but that Specification is 153frequently updated with minor bugfixes and clarifications. 154When a more recent patch release is made, it becomes the normative reference 155for the API. 156 157 158// Chapters of the text are included below 159 160include::style/naming.txt[] 161 162include::style/extensions.txt[] 163 164include::style/markup.txt[] 165 166include::style/writing.txt[] 167 168include::style/misc.txt[] 169 170// Appendices are included below 171include::style/vuid.txt[] 172 173 174= Revision History 175 176* 2021-11-21 - Add preferred uses of "`indirect (drawing/dispatching) 177 command`" to the <<writing-compound-words, Compound Words and Preferred 178 Orthography>> section. 179* 2021-11-15 - Add <<markup-include-file-paths, Include File Paths>> section 180 requiring using full paths to included markup files. 181* 2021-11-04 - Remove backquote markup around recommended use of the 182 `apiext:` macro, since that macro now styles the extension name argument 183 itself. 184* 2021-10-29 - add "`render pass" to the <<writing-compound-words, Compound 185 Words and Preferred Orthography>> section. 186* 2021-10-04 - Update the <<extensions-documenting-extensions, Changes for 187 New Extensions>> section to require use of the `apiext:` macro for links 188 to extension names (internal issue 2831). 189* 2021-09-12 - Add a new subsection with more details on using 190 tilde-delimited source blocks <<markup-blocks-source, inside reference 191 page open blocks>>, and rewrite the <<sample-command, Sample Command 192 Description>> section to follow current phrasing and markup patterns 193 (internal issue 2040). 194* 2021-09-09 - Add the <<markup-italicized-enumerant-names, Italicized 195 Enumerant Names>> section to clarify how to write wildcard enumerant names 196 with imbedded italicized text. 197* 2021-09-06 - Add the <<writing-inclusivity, Use Inclusive Language>> 198 section based on the Khronos Inclusive Language list (internal issue 199 2293). 200* 2021-09-06 - add "`cube map`" to the <<writing-compound-words, Compound 201 Words and Preferred Orthography>> section (internal merge request 4794). 202* 2021-07-20 - Add additional contraction examples to the table in the 203 <<markup-avoid-contractions, Avoid Abbreviations and Contractions>> 204 section. 205* 2021-05-31 - Add "`implementation-dependent`" as an exception in the 206 <<writing-compound-words, Compound Words and Preferred Orthography>> 207 section (internal merge request 4611). 208* 2021-05-24 - Add escapes to prevent expansion of attribute names in a few 209 places where markup examples are given. 210* 2021-05-22 - Expand the <<markup-avoid-contractions, markup rules>> to 211 include avoiding abbreviations, as well as contractions. 212* 2021-05-07 - Add <<markup-word-choices, preferred way to write 213 "`drawing/dispatching command">>. 214* 2021-04-28 - Add <<markup-word-choices, disambiguations for 215 "`executable`">>. 216* 2021-04-28 - Add <<writing-pointers-instances, usage for pointers and 217 handles>> which may be `NULL` or dname:VK_NULL_HANDLE, respectively 218 (internal issue 2662). 219* 2021-04-14 - Add "`side effect`" and "`reuse`" as 220 <<writing-compound-words, preferred orthography>> (public issue 1484). 221* 2021-03-31 - Update description of the code{cl} macro in the 222 <<markup-macros-api, API Markup Macros>> section to match current 223 behavior. 224* 2021-03-21 - Note that the <<extensions-reserving-bitmask-values same bit 225 should be reserved>> for the same purpose in comparable 32- and 64-bit 226 bitmask types (internal issue 2565). 227* 2020-09-14 - Change <<markup-informative-notes, Informative Sections and 228 Notes>> section to track actual usage and update the description of the 229 undefined{cl} macro to further clarify its purpose and uses (internal 230 issue 2195). 231* 2020-08-16 - Add "`reference monitor`" to the preferred 232 <<markup-word-choices, Word Choices>> (internal issue 2291). 233* 2020-08-10 - Add a <<writing-describing-errors, Commands which Return 234 Error Codes>> section to guide authors of new commands (internal issue 235 2290). 236* 2020-07-28 - Add a <<markup-copyrights, Copyrights and Licenses>> section 237 describing how to properly attribute this information. 238* 2020-06-23 - Update the <<extensions-documenting-extensions, Changes for 239 New Extensions>> section to recommend placing most extension language 240 inline in existing specification source files, rather than in separate 241 files, and to base extension revision numbers at `1` starting with initial 242 public release (public issue 1263). 243* 2020-04-29 - Expand use of `basetype` macros to include external API 244 types. 245* 2020-03-16 - Add documentation of writing links to extension appendices in 246 the <<extensions-documenting-extensions, Changes for New Extensions>> 247 section and document the apiext{cl} and reflink{cl} macros in the 248 <<markup-macros-api, API Markup Macros>> section. 249 Improve documentation of writing <<writing-refpages, Markup For Automatic 250 Reference Page Extraction>> including how to mark up content in the 251 Specification source so it only appears in generated reference pages; 252 however, this section is still out of date (internal issue 1999). 253* 2020-03-11 - Specify in the <<sample-command, Sample Command Description>> 254 section that a valid usage statement must be defined at the place (command 255 or structure specification) that all information need to evaluate the 256 statement is known. 257 Update the description of <<appendix-vuid-creating, Creating VUID tags>> 258 to match the current scripts. 259 Use the term "`asciidoctor`" instead of "`asciidoc`" everywhere. 260 Note in the <<introduction-asciidoc, Asciidoctor Markup>> section that the 261 Specification can only be built using the command-line asciidoctor client, 262 not by asciidoctor web clients. 263* 2020-02-22 - Document that it is no longer needed to escape C arrows in 264 macros. 265* 2019-12-15 - Add a markup section on <<markup-macros-prime-symbols, Prime 266 Symbols>> (internal issue 1110). 267* 2019-11-27 - Expand the <<writing-pNext-chain, Describing Extension 268 Structure Chains>> section and make all spec language consistent with it 269 (internal issue 1814). 270* 2019-09-09 - Define markup for nested structure members in the 271 <<markup-macros-api, API Markup Macros>> section (internal issue 1765). 272* 2019-09-08 - Add language to the end of the 273 <<extensions-documenting-extensions, Changes for New Extensions>> section 274 describing how to mark up asciidoctor conditionals (internal issue 1808). 275* 2019-08-25 - Add the <<markup-indentation-equations, Indentation of 276 Equations>> section (internal issue 1793). 277* 2019-08-25 - Add the <<writing-describing-layers, Extensions and Grouping 278 Related Language>> section (internal issue 979) and the 279 <<markup-minimize-indentation, Minimize Indentation>> section (internal 280 issue 747). 281 Disallow use of standalone `+` except in latexmath and source blocks, in 282 the <<markup-layout, Asciidoc Markup And Text Layout>> section (internal 283 issue 736). 284* 2019-08-19 - Add the <<writing-pointers-instances, Describing Pointers and 285 Instances>> section (internal issue 1553). 286* 2019-08-13 - Add a NOTE to the <<appendix-vuid-format, Format of VUID 287 Tags>> appendix specifying allowed characters in VUID tags (based on 288 discussion for internal merge request 3239). 289* 2019-07-27 - Add the <<writing-references, References>> section and 290 rewrite external references accordingly. 291* 2019-05-09 - Specify rules for defining <<extensions-new-flags-types, new 292 flags and bitmask types>> (internal issue 1649). 293* 2019-01-06 - Add details on <<extensions-reserving-bitmask-values, 294 Reserving Bitmask Values>> (internal issue 1411). 295* 2018-11-19 - Add details to the <<extensions-documenting-extensions, 296 Changes for New Extensions>> section including the new "`Description`" 297 section, and other standard parts of extension appendices. 298* 2018-08-13 - Add %inline directive to the <<markup-sample-section-images, 299 Figures>> section (public pull request 734). 300* 2018-07-30 - Added a section on <<writing-undefined, Describing Undefined 301 Behavior>> (as part of the fixes for public issue 379), and describing why 302 the undefined{cl} macro should always be used. 303* 2018-07-08 - Remove requirement to explicitly include extension appendices 304 in the <<extensions-documenting-extensions, Changes for New Extensions>> 305 section. 306* 2018-06-25 - Modify the process for <<extensions-vendor-id, Registering a 307 Vendor ID with Khronos>> to define vendor ID values as part of an 308 enumerated type. 309* 2018-03-07 - Updated for Vulkan 1.1 release. 310* 2018-01-10 - Move details of mandated extension compatibility from the 311 <<extensions-rules, General Rules/Guidelines>> section into the 312 Fundamentals section of the API Specification, where they are changed 313 slightly to allow explicit incompatibilies (public issue 638). 314* 2017-10-27 - Add language about proper use of "`valid pointer`" and 315 "`pointer to valid object`" for valid usage statements, in the 316 <<sample-command, Sample Command Description>> section (related to public 317 pull request 547). 318* 2017-10-15 - Describe how to write <<writing-latexmath-in-table-cells, 319 LaTeX Math in Table Cells>> (internal issue 908). 320* 2017-10-15 - Add more details of <<extensions-naming-author-IDs, `KHX` 321 extensions>> (public issues 536, 580). 322* 2017-09-10 - Add descriptions of <<writing-arrays, how to use `each` and 323 `any`>> to refer to properties of elments of arrays (internal issue 884). 324* 2017-09-10 - Add <<extensions-interactions-parent, Valid Usage and 325 Extension pname:pNext Chains>> language specifying where to describe 326 interactions of structures in a pname:pNext chain (internal issue 715). 327* 2017-09-10 - Add example of marking up an enumerated type all of whose 328 values are defined by extensions (internal issue 864). 329* 2017-08-25 - Add language to the <<extensions,API Versions, Extensions, 330 and Layers>> chapter describing how to write new API versions (internal 331 issue 892). 332* 2017-06-12 - Add sections describing when to use the 333 <<markup-macros-api-name, *name{cl}>> and <<markup-macros-api-text, 334 *text{cl}>> markup macros instead of the *link{cl} macros, and clarify 335 that slink{cl} should be used for handle as well as structure names 336 (internal issue 886). 337* 2017-05-08 - Add appendix describing <<appendix-vuid, Valid Usage ID 338 Tags>> and how they are generated. 339* 2017-03-19 - Add naming rule for <<naming-extension-structures, Extension 340 Structure Names>>. 341* 2017-02-11 - Finish transitioning to asciidoctor markup. 342* 2016-09-28 - Add asciidoc math markup guidelines. 343* 2016-09-16 - Make style guide markup more consistent with its own 344 recommendations. 345 Simplify some tables of preferred terms. 346 Add sections on block and table markup. 347* 2016-09-12 - Describe writing and markup style for labelled lists. 348 Require use of the ISO 8601 date format except in rare legacy cases. 349 Expand the description of <<markup-layout,Line Lengths>> and add a 350 description of markup for <<markup-footnotes,Footnotes>>. 351* 2016-09-08 - Add a writing section about proper use of 352 <<writing-misc-a-an,"`a`" and "`an`">> (internal issue 432). 353* 2016-08-30 - Remove mustnot{cl} and shouldnot{cl} macro definitions, which 354 are no longer used in the Specification (internal issue 407). 355* 2016-08-29 - Add spelling and compound word rules (public issue 352). 356* 2016-08-23 - Modify description of specifying extensions in the 357 <<extensions,Layers and Extensions>> chapter to refer to the new 358 single-branch model for extensions (internal issue 397). 359* 2016-07-26 - Add section describing <<writing-refpages,markup for 360 automatic reference page extraction>>. 361* 2016-07-18 - Add examples of function-parameter and structure-member 362 markup (based on public issue 286). 363* 2016-07-11 - Change the document title. 364* 2016-07-07 - Rename document, change license to CC BY, clarify required 365 and recommended actions, and reserve use of "`normative`" for the 366 Specifications. 367* 2016-06-26 - Move Layers and Extensions chapter from Appendix C of the 368 Vulkan API Specification and merge content with the naming guide. 369 Put extension and naming chapters into their own source files. 370* 2016-06-20 - Add API naming guide. 371* 2016-05-22 - Add markup and image creation rules, after fixing missing 372 figure captions for public issue 219. 373* 2016-05-01 - Include feedback from public issues 120 and 190. 374 Use consistent conventions for defining structures. 375 Use American rather than British spelling conventions. 376* 2016-03-12 - Recommend against "the value of". 377* 2016-02-26 - Replace use of the "maynot{cl}" macro with "may{cl} not". 378* 2016-02-16 - Place asciidoc conversion post-release. 379* 2016-02-09 - Added quotation mark convention. 380* 2016-02-01 - Add the Oxford Comma section and issue resolution. 381* 2016-01-26 - Add bullet-list style description of command parameters. 382* 2016-01-11 - Add "`Numbers in Text`" section from WSI work. 383* 2015-12-16 - Make "`begin / end`" preferred terms to "`start / finish`". 384* 2015-12-15 - Make "`implementation`" preferred term instead of "`system`". 385* 2015-12-13 - Add tlink{cl}/tname{cl} macros for function pointer types. 386* 2015-12-10 - Initial release for feedback. 387