-
Notifications
You must be signed in to change notification settings - Fork 1
/
check.txt
executable file
·885 lines (729 loc) · 30 KB
/
check.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
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
[[markup]]
= Markup Style
This chapter demonstrates Asciidoc and Specification structure, including
text layout and markup style.
Chapters and sections follow a rigid template consisting of an optional
anchor (if other parts of the document cross-reference the section) followed
by a one line title (see
http://asciidoctor.org/docs/user-manual/#sections[section 19 of the
Asciidoctor User Manual]) and a blank line.
The anchor is typically the base name of the file containing the chapter,
with a lowercased version of the section name following, with spaces
replaced by dashes.
Always use the one-line title form, with one to four = signs preceding the
chapter/section title.
The two-line title form cannot be easily searched for and often looks like
other types of asciidoc delimiters.
Using a mix of one-line and two-line titles causes compatibility issues, and
using the two-line title form
http://asciidoctor.org/docs/user-manual/#changed-syntax[implicitly sets
syntax compatibility mode].
Always precede the anchor by two blank lines (except at the beginning of a
file), and follow the title by a blank line, to set off sections visibly.
[source,asciidoc]
.Example Markup
----
[[markup]]
= Markup Style
[[markup-sample-section]]
== Sample Section
----
[[markup-sample-section]]
== Sample Section
This is a sample section structurally similar to the <<vulkan-spec,Vulkan
API Specification>>, nested one level inside a chapter.
Sections can be nested up to level 5, although not all levels are included
in the Table of Contents.
[[markup-layout]]
== Asciidoc Markup And Text Layout
Asciidoc source should be text filled to 76 columns with hard line breaks.
Each sentence in a paragraph ends with a newline to minimize git diff
conflicts.
Except when necessary for lists or other markup, text should begin at the
first column of each line (leading spaces are often semantically meaningful
in asciidoc markup).
UTF-8 characters outside the ASCII subset should be used sparingly, only
when needed for non-English names.
Instead use asciidoc markup for special characters, if required.
For example, two hyphens produces an em-dash:
[NOTE]
.Example Markup
====
`An -- em-dash` -> An -- em-dash
====
As an exception, multiplication should be marked with the unicode
multiplication symbol "`×`" (and *not* an asterisk) when used in plain text.
You may also use the `{times}` asciidoc attribute for this symbol.
In math sections, the same symbol should be referred to as `\times`.
In code sections, a conventional asterisk (`*`) should be used instead.
See http://asciidoctor.org/docs/user-manual/#special-characters[section 40
of the Asciidoctor User Manual] for supported special characters, as well as
use of entity references.
Quotation marks should use the 66/99 convention.
That is, double asymmetric quotation marks, indicated by a quotation mark
then a backtick as opening marks, and a backtick then quotation mark as
closing marks (pass:["`like this`"]), which renders "`like this`".
_Never_ use hard tabs or trailing blanks.
* In some cases, limitations of asciidoc markup may result in lines that are
longer than 76 characters and cannot easily be shortened without
compromising the output documents.
[[markup-blocks]]
=== Blocks
There are a variety of asciidoc _block_ constructs.
With the exception of <<markup-sample-section-tables,tables>> and of _open
blocks_ used to group markup together, blocks should be delimited by exactly
four repeated characters indicating the block type, for consistency.
The block types and delimiters are shown in the following table.
.Asciidoc Block Delimiters
[width="70%",options="header",cols="25%,10%,65%"]
|====
| Table Type | Delimiter | Comments
| Open | `--` | For <<markup-sample-section-bullet-lists,continuation blocks>>
| Example | `====` | For <<markup-informative-notes,Notes>>
| Passthrough | pass:[++++] | For some kinds of <<writing-math,math markup>>
| Comment | //// |
| Listing | ---- | For source code listings
| Sidebar | pass:[****] | For <<markup-implementors-notes,implementor's notes>>
| Table | `\|====` | For <<markup-sample-section-tables,tables>>
| Quote | pass:[____] | Currently unused in the Vulkan Specification
| Literal | .... | Currently unused in the Vulkan Specification
|====
[[markup-footnotes]]
=== Footnotes
Use manually marked-up footnotes (the asciidoc footnote construct is OK for
PDF outputs, but does not work well with long HTML documents since it places
all footnotes at the end of the document).
Refer to footnotes with asciidoc superscript notation^1^, and mark up the
footnotes below, but near the references as labelled lists.
Manually assigned footnote numbers will inevitably be reused, which is OK as
long as the colliding numbers are not in the same section.
1::
Like this example footnote.
[NOTE]
====
.Example Markup
[source,asciidoc]
----
See reference^2^
2::
Reference 2.
----
->
See reference^2^
2::
Reference 2.
====
[[markup-sample-section-lists]]
=== Lists
[[markup-sample-section-bullet-lists]]
==== Bullet Lists and Continuation Blocks
* Bullet lists are the preferred form of list, aside from glossary
definitions.
* Lists should have text indented by 4 spaces and the list item delimiter
(e.g. one or more asterisks, for bullet lists) indented by two spaces.
+
Note that continuation blocks for list items longer than one paragraph
cannot be indented, only the first paragraph.
+
In general, successive list items should not be separated by white space.
However, list continuation blocks should be followed by a `+` on a line by
itself, or by a blank line, due to limitations of the asciidoc parser.
+
* Indent bullet lists two spaces (to the bullet), 4 spaces (to the text,
if it extends over multiple lines).
This lets us visually distinguish lists from other kinds of markup.
** Nested lists should align the leftmost list item delimiter (bullet,
etc.) with the parent delimiter.
[source,asciidoc]
.Example Markup
----
* This is the first item in a bullet list.
* The second item is described with two paragraphs.
The second paragraph is in a continuation block:
+
This is a continuation block containing the second paragraph,
+
** This is a nested list item for the second item.
Since it follows a continuation block, it must be separated by a blank
line or `+` from that block.
----
[example]
====
* This is the first item in a bullet list.
* The second item is described with two paragraphs.
The second paragraph is in a continuation block:
+
This is a continuation block containing the second paragraph,
+
** This is a nested list item for the second item.
Since it follows a continuation block, it must be separated by a blank
line or `+` from that block.
====
* It's possible to continue a paragraph of the first bullet after a list
of sub-bullets if so desired by using continuations in a similar
fashion:
[source,asciidoc]
.Example Markup
----
* This an item in a bullet list.
+
** This is a nested list item for the second item.
Since it follows a continuation block, it must be separated by a blank
line or `+` from that block.
+
This is a continuation of the first bullet
----
[example]
====
* This an item in a bullet list.
+
** This is a nested list item for the second item.
Since it follows a continuation block, it must be separated by a blank
line or `+` from that block.
+
This is a continuation of the first bullet
====
[[markup-labelled-lists]]
==== Labelled Lists
Labelled lists may be used in some cases such as
<<markup-footnotes,footnotes>>; glossary entries; and long lists of
information about similar names, such as the "`Features, Limits, and
Formats`" chapter of the Vulkan Specification.
Whenever labelled lists are used the label and its terminating double colon
must be alone on a line, followed by the contents of that list entry.
For consistency do not use labels ending in three or four colons, or two
semicolons, even though these forms are allowed in asciidoc markup.
[source,asciidoc]
.Example Markup
----
Glossary Entry::
This is a glossary entry.
Last Modified Date::
2016-02-16
----
[[markup-numbered-lists]]
==== Numbered Lists
Numbered lists may be used if strictly necessary to place an ordering on
list items.
Always use _implicit numbering_, with the bullet point being a single
period.
. Explicit numbering with a number preceding the period is prone to
accumulating errors as edits are made.
. In addition, the markup is harder to recognize for scripts and tools
(other than asciidoc itself) operating on the document source.
[source,asciidoc]
.Example Markup
----
. First list item.
. Second list item.
. Etc.
----
[[markup-sample-section-anchors]]
=== Anchors and Cross-references
In general, chapters and sections should always have anchors, following the
naming convention <<markup,discussed above>>.
Anchors to other sections of the document may be inserted as needed.
In addition, the autogenerated include files defining commands, structures,
enumerations and flags all define anchors whose name is the name of the
command or type being defined, so it is easy to link to a (for example) a
command name such as <<vkCreateCommandPool,vkCreateCommandPool>>.
However, using the <<markup-macros,markup macros>> described below is
preferred when linking to anchors corresponding to API names, such as
flink:vkCreateCommandPool.
If you want a cross-reference to an anchor to appear as something other than
the raw anchor name, always make sure to include that text as part of the
cross-reference.
There are several different toolchains followed for various forms of
asciidoc output, and not all of them treat anchors without alt-text the same
way.
[source,asciidoc]
.Example Markup
----
In general, chapters and sections should always have anchors, following the
naming convention <<markup,discussed above>>.
...
so it is easy to link to a (for example) a command name such as
<<vkCreateCommandPool,vkCreateCommandPool>>. However, using the
<<markup-macros,markup macros>> described below is preferred when linking to
anchors corresponding to API names, such as flink:vkCreateCommandPool.
----
[[markup-sample-section-tables]]
=== Tables
Asciidoc tables should use the block prefix `|====`.
Where feasible, align the `|` separating cells across rows.
This will sometimes result in very wide tables in the source document, but
makes it easier to see which cells belong to which column.
Alternatively, long cells can be broken onto a separate line with the `|`
separator appearing first, except for the first row of the table, which must
all appear on a single line.
Tables should usually be preceded with a short title.
[source,asciidoc]
.Example Markup
----
.Normative Terminology Macros
[width="100%",options="header"]
|====
| Macro Name | Output
| can{cl} | can:
| cannot{cl} | cannot:
|====
----
[[markup-sample-section-images]]
=== Figures
All figures (images) must be marked up as follows, to ensure there is an
anchor and that the figure is given a caption which shows the figure number
and is added to the list of figures:
[source,asciidoc]
.Example Markup
----
[[fig-anchorname]]
image::images/imagename.svg[align="center",title="Figure caption",opts="{imageopts}"]
----
There must be SVG versions of each figure checked into the `images/`
directory, to support generating both HTML and PDF outputs.
The PDF generation pipeline is now able to use SVG images, so PDF versions
of each image are no longer required.
The `opts=` attribute defaults to `inline`, which decreases output image
size in the generated HTML.
However, the `inline` option interferes with generating HTML diffs between
two specifications with the script we currently use.
By using an asciidoctor attribute, this behavior can be controlled.
Asciidoctor restricts captions in figures to be a single line in the source
document.
If a longer caption is required, follow the figure directive with a sidebar
block including the full caption preceded by a link to the figure:
[source,asciidoc]
.Example Markup
----
.Caption
****
In the <<fig-anchorname,Figure caption>> diagram, the diagram represents
... long caption text here.
****
----
[[markup-macros]]
== Markup Macros and Normative Terminology
This section discusses Asciidoc macros used in the document.
In addition to the macros defined by asciidoc itself, additional macros are
defined by the <<vulkan-spec,Vulkan API Specification>> and Reference Page
configuration files.
[[markup-macros-api]]
=== API Markup Macros
These macros must be used to tag command, structure, enumeration, enumerant,
and other Vulkan-specific names so they can be rendered in a distinctive
fashion, link to definitions of those names, and be easily searched for in
the source documents.
The validation scripts (`make allchecks` output) also rely on these macros
being used consistently and correctly.
The API markup macros, with examples of their use, are in the following
table:
.API Markup Macros
[width="100%",options="header",cols="20%,80%"]
|====
| Macro Name | Usage and Meaning
| flink{cl} | Generates a cross-reference or link to the definition of
the command name in the macro argument. Example:
flink{cl}vkCreateCommandPool -> flink:vkCreateCommandPool.
| fname{cl} | Formats the macro argument like flink{cl}. Does not
generate a cross-reference. Example:
fname{cl}vkCreateCommandPool -> fname:vkCreateCommandPool.
Only use this macro <<markup-macros-api-name, when
necessary>>.
| ftext{cl} | Formats the macro argument like fname{cl}. May contain
asterisks for wildcards. Not validated. Example:
ftext{cl}vkCmd* -> ftext:vkCmd*.
Only use this macro <<markup-macros-api-text, when
necessary>>.
| slink{cl} | Generates a cross-reference or link to the definition
of the structure or handle in the macro argument. Example:
slink{cl}VkMemoryHeap -> slink:VkMemoryHeap.
| sname{cl} | Formats the macro argument like slink{cl}. Does not
generate a cross-reference. May also be an abstract
structure or handle name. Example:
sname{cl}VkCommandPoolCreateInfo ->
sname:VkCommandPoolCreateInfo.
Only use this macro <<markup-macros-api-name, when
necessary>>.
| stext{cl} | Formats the macro argument like sname{cl}. May contain
asterisks for wildcards. Not validated. Example:
stext{cl}Vk*CreateInfo -> stext:Vk*CreateInfo.
Only use this macro <<markup-macros-api-text, when
necessary>>.
| elink{cl} | Formats the macro argument as a Vulkan enumerated
type name and links to the definition of that enumeration
type. Example: elink{cl}VkResult -> elink:VkResult.
| ename{cl} | Formats the macro argument as a Vulkan enumerant name.
Example: ename{cl}VK_EVENT_SET -> ename:VK_EVENT_SET.
| etext{cl} | Formats the macro argument like ename{cl}. Not validated.
Examples: etext{cl}_RANGE_SIZE -> etext:_RANGE_SIZE,
etext{cl}VK_IMAGE_CREATE_SPARSE_* ->
etext:VK_IMAGE_CREATE_SPARSE_*
Only use this macro <<markup-macros-api-text, when
necessary>>.
| pname{cl} | Formats the macro argument as a Vulkan parameter or
structure member name. Example: pname{cl}device ->
pname:device.
| ptext{cl} | Formats the macro argument like pname{cl}. May contain
asterisks for wildcards. Not validated. Example:
ptext{cl}sparseResidency* -> ptext:sparseResidency*.
Only use this macro <<markup-macros-api-text, when
necessary>>.
| tlink{cl} | Generates a cross-reference or link to the definition
of the Vulkan type in the macro argument. Example:
tlink{cl}PFN_vkAllocationFunction ->
tlink:PFN_vkAllocationFunction. This is only used for
function pointer types at present.
| tname{cl} | Formats the macro argument like tlink{cl}. Does not
generate a cross-reference. Example:
tname{cl}PFN_vkAllocationFunction ->
tname:PFN_vkAllocationFunction.
Only use this macro <<markup-macros-api-name, when
necessary>>.
| dlink{cl} | Generates a cross-reference or link to the definition of
the Vulkan C macro in the macro argument. Example:
dlink{cl}VK_NULL_HANDLE -> dlink:VK_NULL_HANDLE. There are
only a few macros in the Vulkan API, described in the
"`API Boilerplate`" appendix of the <<vulkan-spec,Vulkan
API Specification>>
| dname{cl} | Formats the macro argument like dlink{cl}. Does not
generate a cross-reference.
Only use this macro <<markup-macros-api-name, when
necessary>>.
| basetype{cl} | Formats the macro argument like a basic scalar type
or API handle name. Not validated. Examples:
basetype{cl}VkBool32 -> basetype:VkBool32,
basetype{cl}VkDeviceSize -> basetype:VkDeviceSize.
| code{cl} | Formats the macro argument as a code sample.
Used for SPIR-V keywords, builtin C types, and names
belonging to other APIs such as Linux or Windows system
calls.
Examples: code{cl}uint32_t -> code:uint32_t,
code{cl}ClipDistance -> code:ClipDistance.
|====
When referring to a compound name (function-parameter, or structure-member),
combine the macros separated by two colons, resulting in
flink:vkCmdBindIndexBuffer::pname:indexType and
slink:VkMemoryHeap::pname:flags.
This is often done when referring to a particular parameter or member in a
part of the document other than the description of the corresponding
function or structure.
[source,asciidoc]
.Example Markup
----
flink:vkCmdBindIndexBuffer::pname:indexType
slink:VkMemoryHeap::pname:flags
----
[[markup-macros-api-name]]
==== When To Use *name: Macros
Only use the fname{cl}, sname{cl}, tname{cl}, and dname{cl} macros if no
definition of the target type with a corresponding anchor exists in the
document.
Anchors are automatically defined when including the generated API interface
definitions under `api/.../*txt`.
If an anchor does exist, use the corresponding *link{cl} macro.
[NOTE]
.Note
====
There are many legacy uses of the *name{cl} macros that will be replaced
over time.
These uses date from before anchors were added to the generated API
definitions.
====
[[markup-macros-api-text]]
==== When To Use *text: Macros
Only use the ftext{cl}, stext{cl}, etext{cl}, and ptext{cl} macros when
describing something something that should be rendered like a command,
structure, enumerant, or parameter name, respectively, but is not actually
one.
Typically these macros are used for wildcards describing multiple API names
with common prefixes or suffixes, or common subsets of API names.
==== Other Markup
Uses of standard Asciidoc markup are less common.
Occasional asterisk markup is used for *emphasis*.
Underscores are used for _glossary terms_.
Backtick markup is used for the C `NULL` macro.
[source,asciidoc]
.Example Markup
----
*emphasis*
`NULL`
----
==== Glossary Terms
Glossary terms are currently marked up using underscore markup where they
are defined in the documents, as well as being added to the formal Glossary
appendix in the <<vulkan-spec,Vulkan API Specification>>.
However, we will probably change to using custom macros soon, to enable
linkage between the glossary and definitions in the spec body.
[source,asciidoc]
.Example Markup
----
_Glossary terms_
----
=== Normative Terminology
Normative terminology is precisely defined in section 1.3 of the
<<vulkan-spec,Vulkan API Specification>>, and is used to visually tag terms
which express mandatory and optional behavior of Vulkan implementations, and
of applications using Vulkan.
Whenever one of these terms appears in the <<vulkan-spec,Vulkan API
Specification>> outside of an <<markup-informative,informative section>>, it
must be tagged using the macros, to indicate that its use has been carefully
considered and is consistent with the definitions in section 1.3.
This is extremely important for determining IP that is in and out of Scope
during Ratification reviews.
The normative terminology macros are defined in the following table:
.Normative Terminology Macros
[width="30%",options="header"]
|====
| Macro Name | Output
| can{cl} | can:
| cannot{cl} | cannot:
| may{cl} | may:
| may{cl} not | may: not
| must{cl} | must:
| must{cl} not | must: not
| optional{cl} | optional:
| optionally{cl} | optionally:
| required{cl} | required:
| should{cl} | should:
| should{cl} not | should: not
|====
Note that the macros are lower-case only, so language should be written such
that these terms do not appear at the beginning of a sentence (if really
necessary, additional capitalized macros could be added).
==== Optional Behavior
If a described behavior of the implementation is not necessary for
conformance, use the terms _may{cl}_ or _optional{cl}_ to describe it.
If a described usage pattern by the application is allowed but not
necessary, use the term _can{cl}_ to describe it.
If language flows more logically using the term "may not", use the term
_may{cl} not_ to describe it.
==== Optional Functionality
If functionality (rather than behavior) is optional, it should be described
as
[source,asciidoc]
.Example Markup
----
not required:
----
Implementations are not mandated to support functionality which is not
required, but if they do, they must behave as described by the
<<vulkan-spec,Vulkan API Specification>>.
The term _functionality_ includes API features, extensions, and layers.
[[markup-informative]]
== Informative, Editing and Implementor's Notes
There are several possible types of notes.
Depending on the type of output, they are rendered in different styles, but
always include a note title, and are usually set off in a box or with an
icon.
While asciidoc supports a wide set of _admonition paragraphs_ such as TIP,
IMPORTANT, WARNING, and CAUTION, we always use the NOTE form, augmented by a
note title.
Each type of note is discussed below.
[[markup-informative-notes]]
=== Informative Notes
Informative notes always appear as part of the document, but are considered
non-normative.
They usually describe usage advice for applications, and are always given
the title _Note_, as in the following example:
[NOTE]
.Note
====
This is an informative note.
====
[source,asciidoc]
.Example Markup
----
[NOTE]
.Note
====
This is an informative note.
====
----
If an entire chapter or section is considered informative, it should begin
with the sentence:
[source,asciidoc]
.Example Markup
----
This chapter/section is Informative.
----
[[markup-editing-notes]]
=== Editing Notes
Editing notes usually only appear in internal (non-published) versions of
documents, via asciidoc conditionals.
If they are not resolved, or are internal issues that should not be visible
in public, they should be removed from the source before pushing content to
the canonical GitHub repository.
They usually tag places where an outstanding Gitlab/GitHub issue is being
worked, and are always given the title _editing-note_, as in the following
example:
ifdef::editing-notes[]
[NOTE]
.editing-note
====
This is an editing note, marked up as follows:
====
endif::editing-notes[]
[source,asciidoc]
.Example Markup
----
\ifdef::editing-notes[]
[NOTE]
.editing-note
====
Contents of an editing note go here.
It is good practice to include a Gitlab/GitHub issue number, or link to the
issue, in the editing note.
====
\endif::editing-notes[]
----
[[markup-implementors-notes]]
=== Implementor's Notes
Implementor's notes may or may not appear in published versions of
documents, via asciidoc conditionals.
They describe suggested approaches or guidelines for people writing Vulkan
implementations, and are rare because the hardware being targeted varies so
widely.
They are always given the title _Implementor's Note_, as in the following
example:
ifdef::implementation-guide[]
.Implementor's Note
====
This is an implementor's note, marked up as follows:
====
endif::implementation-guide[]
[source,asciidoc]
.Example Markup
----
\ifdef::implementation-guide[]
.Implementor's Note
====
Contents of an implementor's note go here.
====
\endif::implementation-guide[]
----
[[markup-word-choices]]
== Word Choices
There are a variety of common terms that have several equivalent word
choices.
Always use the words or phrases in the first column instead of the alternate
terms.
This list may not be comprehensive; when in doubt, be guided by the existing
<<vulkan-spec,Vulkan API Specification>>.
.Word Choices
[width="100%",options="header"]
|====
| Use This | Instead Of | Comments
| allocate | create
| When describing objects or memory resulting from
ftext:vkAllocate* commands.
| application | client |
| bitmask | bit field
| Technically correct. Vulkan bitmasks are just integers and
are not logically addressable at the bit level.
| bound | currently bound
| Appears primarily in valid usage statements, which are
always referring to the current state of the objects
they are validating.
Rare exceptions may be justified in other cases.
| command | function
| Except when talking about function pointers returned by
ftext:vkGet*ProcAddr commands.
| create | allocate
| When describing objects resulting from ftext:vkCreate*
commands.
| depth/stencil | packed (interleaved, combined, _other prefix_)
depth/stencil, depth-stencil, DepthStencil, etc.
| Combined format implicit in the name.
| device | GPU / processor / accelerator
| The Vulkan specification is functional and could be
implemented in many different ways.
| heterogeneous | heterogenous | More common
| homogeneous | homogenous | More common
| host | CPU |
| host endianness | platform endianness |
| image subresource | subresource
| Except when referring to *host-accessible subresources*
| implementation| system / hardware / software
| For consistency, and avoids implied requirements.
| indices | indexes | More common
| member | field |
| ename:enumerant specifies
| ename:enumerant indicates (denotes)
| When giving a brief description of enums in an enumerated
type.
It is often appropriate to use "`enumerant *is*`" when
describing the behavior or meaning of enumerants in other
places.
| pname:parameter are/is
| pname:parameter specifies (denotes, indicates)
| In cases when _are_ or _if_ are not grammatically
appropriate, _specifies_ may be used instead.
| pname:parameter is
| the value of pname:parameter is
| In rare cases, _the value of_ is appropriate. See the
existing specification language for examples.
| begins / begun | starts / started | For ftext:vkBegin* - also see "`finish`"
| finishes / finished | ends / ended | For ftext:vkEnd* - also see "`begins`"
| used | referenced | When describing attachments specified in a
subpass description.
| statically used | referenced | When describing resources or push constants
accessed by shader code
| a more specific term | referenced | For all other situations.
| component | channel | Specifically this refers to color channels/components
|====
[NOTE]
.Note
====
The "`begin/start`" and "`end/finish`" distinction is still being sorted
out.
See Gitlab issue #61.
====
[[markup-avoid-contractions]]
=== Avoid Contractions
Contractions make the specification sound less formal and using them would
be inconsistent with the many non-contraction forms already in use in the
spec.
.Word Choices
[width="30%",options="header"]
|====
| Use This | Instead Of
| are not | aren't
| cannot{cl} | can't
| does not | doesn't
| do not | don't
| has not | hasn't
| is not | isn't
| it is | it's
| that is | that's
| there is | there's
| we are | we're
| will not | won't
|====
[[markup-terms-caution]]
=== Terms to Use With Caution
The term _subset_ is sometimes used to refer to a _strict subset_, and
sometimes used to refer to a subset which may be equal to the entire set.
This is particularly likely to come up when describing bitmasks.
Make sure to use either _subset_ or _strict subset_ as appropriate.
[[markup-terms-avoid]]
=== Terms to Avoid
Do not describe anything in the documentation using vague or wishy-washy
terms.
Our goal is to precisely describe behavior of implementations.
The normative terms may{cl}, optional{cl}, and should{cl} are available when
implementations may make choices of behavior, but when such choices are
allowed, each choice still must have well-defined behavior.
.Terms to Avoid
[width="100%",options="header"]
|====
| Bad Term | Comments
| expect | And variants such as _expected_
| likely | And variants such as _will likely_
| allowed, could, generally, might, probably, perhaps
| And all other such terms of choice. Use _may{cl}_ or _can{cl}_
depending on the context.
| may{cl} or may{cl} not | Just use _may{cl}_.
|====