forked from KhronosGroup/Vulkan-Docs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
styleguide.txt
331 lines (287 loc) · 14.9 KB
/
styleguide.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
// Copyright 2014-2020 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
:max-width: 100
:numbered:
:doctype: book
:imagewidth: 800
:fullimagewidth: width="800"
:cl: :
// Various special / math symbols. This is easier to edit with than Unicode.
include::{config}/attribs.txt[]
: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:
* <<naming,API Naming Conventions>> - the required rules for choosing
names of Vulkan identifiers of all types.
* <<extensions,Extensions and Layers>> - the required procedures for
creating formal Vulkan extensions and layers.
* <<markup,Markup Style>> - 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.
* <<writing,Writing Style>> - 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
* 2020-09-14 - Change <<markup-informative-notes, Informative Sections and
Notes>> 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
<<markup-word-choices, Word Choices>> (internal issue 2291).
* 2020-08-10 - Add a <<writing-describing-errors, Commands which Return
Error Codes>> section to guide authors of new commands (internal issue
2290).
* 2020-07-28 - Add a <<markup-copyrights, Copyrights and Licenses>> section
describing how to properly attribute this information.
* 2020-06-23 - Update the <<extensions-documenting-extensions, Changes for
New Extensions>> 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 <<extensions-documenting-extensions, Changes for New Extensions>>
section and document the apiext{cl} and reflink{cl} macros in the
<<markup-macros-api, API Markup Macros>> section.
Improve documentation of writing <<writing-refpages, Markup For Automatic
Reference Page Extraction>> 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 <<sample-command, Sample Command Description>>
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 <<appendix-vuid-creating, Creating VUID tags>>
to match the current scripts.
Use the term "`asciidoctor`" instead of "`asciidoc`" everywhere.
Note in the <<introduction-asciidoc, Asciidoctor Markup>> 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 <<markup-macros-prime-symbols, Prime
Symbols>> (internal issue 1110).
* 2019-11-27 - Expand the <<writing-pNext-chain, Describing Extension
Structure Chains>> section and make all spec language consistent with it
(internal issue 1814).
* 2019-09-09 - Define markup for nested structure members in the
<<markup-macros-api, API Markup Macros>> section (internal issue 1765).
* 2019-09-08 - Add language to the end of the
<<extensions-documenting-extensions, Changes for New Extensions>> section
describing how to mark up asciidoctor conditionals (internal issue 1808).
* 2019-08-25 - Add the <<markup-indentation-equations, Indentation of
Equations>> section (internal issue 1793).
* 2019-08-25 - Add the <<writing-describing-layers, Extensions and Grouping
Related Language>> section (internal issue 979) and the
<<markup-minimize-indentation, Minimize Indentation>> section (internal
issue 747).
Disallow use of standalone `+` except in latexmath and source blocks, in
the <<markup-layout, Asciidoc Markup And Text Layout>> section (internal
issue 736).
* 2019-08-19 - Add the <<writing-pointers-instances, Describing Pointers and
Instances>> section (internal issue 1553).
* 2019-08-13 - Add a NOTE to the <<appendix-vuid-format, Format of VUID
Tags>> appendix specifying allowed characters in VUID tags (based on
discussion for internal merge request 3239).
* 2019-07-27 - Add the <<writing-references, References>> section and
rewrite external references accordingly.
* 2019-05-09 - Specify rules for defining <<extensions-new-flags-types, new
flags and bitmask types>> (internal issue 1649).
* 2019-01-06 - Add details on <<extensions-reserving-bitmask-values,
Reserving Bitmask Values>> (internal issue 1411).
* 2018-11-19 - Add details to the <<extensions-documenting-extensions,
Changes for New Extensions>> section including the new "`Description`"
section, and other standard parts of extension appendices.
* 2018-08-13 - Add %inline directive to the <<markup-sample-section-images,
Figures>> section (public pull request 734).
* 2018-07-30 - Added a section on <<writing-undefined, Describing Undefined
Behavior>> (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 <<extensions-documenting-extensions, Changes for New Extensions>>
section.
* 2018-06-25 - Modify the process for <<extensions-vendor-id, Registering a
Vendor ID with Khronos>> 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
<<extensions-rules, General Rules/Guidelines>> 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
<<sample-command, Sample Command Description>> section (related to public
pull request 547).
* 2017-10-15 - Describe how to write <<writing-latexmath-in-table-cells,
LaTeX Math in Table Cells>> (internal issue 908).
* 2017-10-15 - Add more details of <<extensions-naming-author-IDs, `KHX`
extensions>> (public issues 536, 580).
* 2017-09-10 - Add descriptions of <<writing-arrays, how to use `each` and
`any`>> to refer to properties of elments of arrays (internal issue 884).
* 2017-09-10 - Add <<extensions-interactions-parent, Valid Usage and
Extension pname:pNext Chains>> 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 <<extensions,API Versions, Extensions,
and Layers>> chapter describing how to write new API versions (internal
issue 892).
* 2017-06-12 - Add sections describing when to use the
<<markup-macros-api-name, *name{cl}>> and <<markup-macros-api-text,
*text{cl}>> 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 <<appendix-vuid, Valid Usage ID
Tags>> and how they're generated.
* 2017-03-19 - Add naming rule for <<naming-extension-structures, Extension
Structure Names>>.
* 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 <<markup-layout,Line Lengths>> and add a
description of markup for <<markup-footnotes,Footnotes>>.
* 2016-09-08 - Add a writing section about proper use of
<<writing-misc-a-an,"`a`" and "`an`">> (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
<<extensions,Layers and Extensions>> chapter to refer to the new
single-branch model for extensions (internal issue 397).
* 2016-07-26 - Add section describing <<writing-refpages,markup for
automatic reference page extraction>>.
* 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.