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