1// Copyright (c) 2014-2018 Khronos Group. This work is licensed under a 2// Creative Commons Attribution 4.0 International License; see 3// http://creativecommons.org/licenses/by/4.0/ 4 5= Vulkan^(R)^ Documentation and Extensions: Procedures and Conventions 6Jon Leech, Tobias Hector 7:data-uri: 8:icons: font 9:toc2: 10:toclevels: 3 11:max-width: 100 12:numbered: 13:doctype: book 14:imagewidth: 800 15:fullimagewidth: width="800" 16:cl: : 17 18// Various special / math symbols. This is easier to edit with than Unicode. 19include::config/attribs.txt[] 20 21:leveloffset: 1 22 23<<<< 24 25include::copyright-ccby.txt[] 26 27<<<< 28 29[[introduction]] 30= Introduction 31 32This document contains required procedures and conventions when writing 33specifications for new Vulkan APIs, extensions and layers, or related 34Khronos documentation such as white papers and tutorials; or contributing to 35existing Vulkan specifications. 36These are collectively referred to as _Vulkan Documentation_ or just 37_documentation_ below. 38The primary focus is the API Specification and API extensions, although all 39of the markup and most of the writing style is equally applicable to other 40documentation. 41 42The primary purpose is to achieve consistency across the API, as well as 43across all of our source and output documents. 44Consistency makes it easier for developers, editors, reviewers, and users of 45our documentation to understand and modify it. 46 47This document is now formally voted on and approved by the Vulkan Working 48Group. 49This means that unless explicitly stated otherwise, the procedures and 50conventions must be followed. 51If you have a strong desire to modify the procedures and conventions, such 52changes must be made through the normal Vulkan Working Group processes. 53 54 55[[introduction-terminology]] 56== Terminology 57 58The key words *must*, *required*, *should*, *recommend*, *may*, and 59*optional* in this document are to be interpreted as described in RFC 2119 60and by the Vulkan 1.1 Specification in the "`Terminology`" section. 61 62 63[[introduction-structure]] 64== Document Structure 65 66The style guide is broken into four sections: 67 68 * <<naming,API Naming Conventions>> - the required rules for choosing 69 names of Vulkan identifiers of all types. 70 * <<extensions,Extensions and Layers>> - the required procedures for 71 creating formal Vulkan extensions and layers. 72 * <<markup,Markup Style>> - the required and recommended markup style for 73 writing asciidoc and XML source that follows consistent formatting and 74 layout guidelines, tags special terms and phrases for proper processing 75 by the spec generation tools, etc. 76 * <<writing,Writing Style>> - the required and recommended writing style 77 for overall and fine-grained structure and conventions, normative 78 language use, API naming conventions, common words and phrases to use 79 and to avoid, linking and cross-referencing, etc. 80 81 82[[introduction-asciidoc]] 83== Asciidoc Markup 84 85Vulkan Documentation is primarily written in Asciidoc, a form of text markup 86language. 87Specifically we're using the version of Asciidoc that is actively maintained 88by asciidoctor, which is documented on its website at 89http://www.asciidoctor.org/. 90 91References to the Asciidoctor User Manual are to sections in the document at 92http://asciidoctor.org/docs/user-manual/. 93 94Asciidoctor is implemented in Ruby (https://www.ruby-lang.org/), which is 95available for Linux, MacOS, and Microsoft Windows. 96Multiple preview tools also exist for the language, primarily using 97AsciidoctorJ (https://github.com/asciidoctor/asciidoctorj) or asciidoctor.js 98(https://github.com/asciidoctor/asciidoctor.js). 99In particular, GitHub and GitLab both have asciidoc previews for .adoc or 100.asciidoc files in repositories, and live preview extensions exist for 101Chrome and Firefox. 102 103The Asciidoctor toolchain and build process are not addressed by this 104document, which concentrates solely on source documents. 105 106 107[[introduction-normative]] 108== Normative References 109 110Normative references are references to external documents or resources to 111which documentation authors must comply. 112 113[[iso-8601]] 114International Organization for Standardization, _Data elements and 115interchange formats -- Information interchange -- Representation of dates 116and times_, http://www.iso.org/iso/catalogue_detail?csnumber=40874, 1172004-12-01. 118Also see https://www.w3.org/QA/Tips/iso-date for colloquial examples. 119 120[[vulkan-docs]] 121Khronos Vulkan Working Group, +KhronosGroup/Vulkan-Docs+ project on GitHub, 122https://github.com/KhronosGroup/Vulkan-Docs, 2016-07-05. 123 124[[vulkan-spec]] 125Vulkan Working Group, _Vulkan 1.1.70 - A Specification_, 126https://www.khronos.org/registry/vulkan/, 2018-03-07 127 128Version 1.1.70 is the latest patch release of the Vulkan API Specification 129as of the time this reference was created, but that Specification is 130frequently updated with minor bugfixes and clarifications. 131When a more recent patch release is made, it becomes the normative reference 132for the API. 133 134 135// Chapters of the text are included below 136 137include::style/naming.txt[] 138 139include::style/extensions.txt[] 140 141include::style/markup.txt[] 142 143include::style/writing.txt[] 144 145include::style/misc.txt[] 146 147// Appendices are included below 148include::style/vuid.txt[] 149 150 151= Revision History 152 153* 2018-08-13 - Add %inline directive to the <<markup-sample-section-images, 154 Figures>> section (public pull request 734). 155* 2018-07-08 - Remove requirement to explicitly include extension appendices 156 in the <<extensions-documenting-extensions, Changes for New Extensions>> 157 section. 158* 2018-06-25 - Modify the process for <<extensions-vendor-id, Registering a 159 Vendor ID with Khronos>> to define vendor ID values as part of an 160 enumerated type. 161* 2018-03-07 - Updated for Vulkan 1.1 release. 162* 2018-01-10 - Move details of mandated extension compatibility from the 163 <<extensions-rules, General Rules/Guidelines>> section into the 164 Fundamentals section of the API Specification, where they are changed 165 slightly to allow explicit incompatibilies (public issue 638). 166* 2017-10-27 - Add language about proper use of "`valid pointer`" and 167 "`pointer to valid object`" for valid usage statements, in the 168 <<sample-command, Sample Command Description>> section (related to public 169 pull request 547). 170* 2017-10-15 - Describe how to write <<writing-latexmath-in-table-cells, 171 LaTeX Math in Table Cells>> (internal issue 908). 172* 2017-10-15 - Add more details of <<extensions-naming-author-IDs, `KHX` 173 extensions>> (public issues 536, 580). 174* 2017-09-10 - Add descriptions of <<writing-arrays, how to use `each` and 175 `any`>> to refer to properties of elments of arrays (internal issue 884). 176* 2017-09-10 - Add <<extensions-interactions-parent, Valid Usage and 177 Extension pname:pNext Chains>> language specifying where to describe 178 interactions of structures in a pname:pNext chain (internal issue 715). 179* 2017-09-10 - Add example of marking up an enumerated type all of whose 180 values are defined by extensions (internal issue 864). 181* 2017-08-25 - Add language to the <<extensions,API Versions, Extensions, 182 and Layers>> chapter describing how to write new API versions (internal 183 issue 892). 184* 2017-06-12 - Add sections describing when to use the 185 <<markup-macros-api-name, *name{cl}>> and <<markup-macros-api-text, 186 *text{cl}>> markup macros instead of the *link{cl} macros, and clarify 187 that slink{cl} should be used for handle as well as structure names 188 (internal issue 886). 189* 2017-05-08 - Add appendix describing <<appendix-vuid, Valid Usage ID 190 Tags>> and how they're generated. 191* 2017-03-19 - Add naming rule for <<naming-extension-structures, Extension 192 Structure Names>>. 193* 2017-02-11 - Finish transitioning to asciidoctor markup. 194* 2016-09-28 - Add asciidoc math markup guidelines. 195* 2016-09-16 - Make style guide markup more consistent with its own 196 recommendations. 197 Simplify some tables of preferred terms. 198 Add sections on block and table markup. 199* 2016-09-12 - Describe writing and markup style for labelled lists. 200 Require use of the ISO 8601 date format except in rare legacy cases. 201 Expand the description of <<markup-layout,Line Lengths>> and add a 202 description of markup for <<markup-footnotes,Footnotes>>. 203* 2016-09-08 - Add a writing section about proper use of 204 <<writing-misc-a-an,"`a`" and "`an`">> (internal issue 432). 205* 2016-08-30 - Remove mustnot{cl} and shouldnot{cl} macro definitions, which 206 are no longer used in the Specification (internal issue 407). 207* 2016-08-29 - Add spelling and compound word rules (public issue 352). 208* 2016-08-23 - Modify description of specifying extensions in the 209 <<extensions,Layers and Extensions>> chapter to refer to the new 210 single-branch model for extensions (internal issue 397). 211* 2016-07-26 - Add section describing <<writing-refpages,markup for 212 automatic reference page extraction>>. 213* 2016-07-18 - Add examples of function-parameter and structure-member 214 markup (based on public issue 286). 215* 2016-07-11 - Change the document title. 216* 2016-07-07 - Rename document, change license to CC BY, clarify required 217 and recommended actions, and reserve use of "`normative`" for the 218 Specifications. 219* 2016-06-26 - Move Layers and Extensions chapter from Appendix C of the 220 Vulkan API Specification and merge content with the naming guide. 221 Put extension and naming chapters into their own source files. 222* 2016-06-20 - Add API naming guide. 223* 2016-05-22 - Add markup and image creation rules, after fixing missing 224 figure captions for public issue 219. 225* 2016-05-01 - Include feedback from public issues 120 and 190. 226 Use consistent conventions for defining structures. 227 Use American rather than British spelling conventions. 228* 2016-03-12 - Recommend against "the value of". 229* 2016-02-26 - Replace use of the "maynot{cl}" macro with "may{cl} not". 230* 2016-02-16 - Place asciidoc conversion post-release. 231* 2016-02-09 - Added quotation mark convention. 232* 2016-02-01 - Add the Oxford Comma section and issue resolution. 233* 2016-01-26 - Add bullet-list style description of command parameters. 234* 2016-01-11 - Add "`Numbers in Text`" section from WSI work. 235* 2015-12-16 - Make "`begin / end`" preferred terms to "`start / finish`". 236* 2015-12-15 - Make "`implementation`" preferred term instead of "`system`". 237* 2015-12-13 - Add tlink{cl}/tname{cl} macros for function pointer types. 238* 2015-12-10 - Initial release for feedback. 239