1e5c31af7Sopenharmony_ci// Copyright 2015-2021 The Khronos Group Inc.
2e5c31af7Sopenharmony_ci//
3e5c31af7Sopenharmony_ci// SPDX-License-Identifier: CC-BY-4.0
4e5c31af7Sopenharmony_ci
5e5c31af7Sopenharmony_ci[[markup]]
6e5c31af7Sopenharmony_ci= Markup Style
7e5c31af7Sopenharmony_ci
8e5c31af7Sopenharmony_ciThis chapter demonstrates Asciidoc and Specification structure, including
9e5c31af7Sopenharmony_citext layout and markup style.
10e5c31af7Sopenharmony_ci
11e5c31af7Sopenharmony_ci
12e5c31af7Sopenharmony_ci[[markup-copyrights]]
13e5c31af7Sopenharmony_ci== Copyrights and Licenses
14e5c31af7Sopenharmony_ci
15e5c31af7Sopenharmony_ciThe asciidoctor source for the Vulkan Specification and related documents is
16e5c31af7Sopenharmony_ciunder an open source license.
17e5c31af7Sopenharmony_ci
18e5c31af7Sopenharmony_ciWhen creating a *new* file, add the following copyright and license
19e5c31af7Sopenharmony_cistatement at the top:
20e5c31af7Sopenharmony_ci
21e5c31af7Sopenharmony_ci[source,asciidoc]
22e5c31af7Sopenharmony_ci.Example Markup
23e5c31af7Sopenharmony_ci----
24e5c31af7Sopenharmony_ci// Copyright YEAR AUTHOR
25e5c31af7Sopenharmony_ci// SPDX-License-Identifier: CC-BY-4.0
26e5c31af7Sopenharmony_ci
27e5c31af7Sopenharmony_ci----
28e5c31af7Sopenharmony_ci
29e5c31af7Sopenharmony_ci`YEAR` should be replaced by the year in which the file was created.
30e5c31af7Sopenharmony_ci
31e5c31af7Sopenharmony_ci`AUTHOR` is normally "`The Khronos Group Inc.`".
32e5c31af7Sopenharmony_ciIf a new file is created by a member company or outside contributor, use
33e5c31af7Sopenharmony_cithat entity's legal name as the author.
34e5c31af7Sopenharmony_ci
35e5c31af7Sopenharmony_ci`SPDX-License-Identifier` gives the license used for the file, following the
36e5c31af7Sopenharmony_cihttps://spdx.github.io/spdx-spec/using-SPDX-short-identifiers-in-source-files/[SPDX]
37e5c31af7Sopenharmony_cistandard for short identifiers in source files.
38e5c31af7Sopenharmony_ci`CC-BY-4.0` is the short identifier for the
39e5c31af7Sopenharmony_cihttps://spdx.org/licenses/CC-BY-4.0.html[Creative Commons Attribution 4.0
40e5c31af7Sopenharmony_ciInternational] license.
41e5c31af7Sopenharmony_ci
42e5c31af7Sopenharmony_ciNo matter who holds the *copyright* on a source file for the Specification,
43e5c31af7Sopenharmony_ciit must be placed under the `CC-BY-4.0` *license*.
44e5c31af7Sopenharmony_ciWhen contributing to the Specification, contributors are required to execute
45e5c31af7Sopenharmony_cia Contributor License Agreement to this effect.
46e5c31af7Sopenharmony_ci
47e5c31af7Sopenharmony_ciWhen updating an *existing* file, modify the following copyright and license
48e5c31af7Sopenharmony_cistatement to include the year(s) of modification.
49e5c31af7Sopenharmony_ciFor example:
50e5c31af7Sopenharmony_ci
51e5c31af7Sopenharmony_ci[source,asciidoc]
52e5c31af7Sopenharmony_ci.Example Markup
53e5c31af7Sopenharmony_ci----
54e5c31af7Sopenharmony_ci// Copyright 2018-2021 The Khronos Group Inc.
55e5c31af7Sopenharmony_ci// SPDX-License-Identifier: CC-BY-4.0
56e5c31af7Sopenharmony_ci
57e5c31af7Sopenharmony_ci----
58e5c31af7Sopenharmony_ci
59e5c31af7Sopenharmony_ciindicates a file which has been been modified in 2018, 2019, and 2020
60e5c31af7Sopenharmony_ciinclusive.
61e5c31af7Sopenharmony_ci
62e5c31af7Sopenharmony_ci
63e5c31af7Sopenharmony_ci[[markup-structure]]
64e5c31af7Sopenharmony_ci== Document Structure
65e5c31af7Sopenharmony_ci
66e5c31af7Sopenharmony_ciChapters and sections follow a rigid template consisting of an optional
67e5c31af7Sopenharmony_cianchor (if other parts of the document cross-reference the section) followed
68e5c31af7Sopenharmony_ciby a link:{docguide}/sections/titles-and-levels/[one line title] and a blank
69e5c31af7Sopenharmony_ciline.
70e5c31af7Sopenharmony_ciThe anchor is typically the base name of the file containing the chapter,
71e5c31af7Sopenharmony_ciwith a lowercased version of the section name following, with spaces
72e5c31af7Sopenharmony_cireplaced by dashes.
73e5c31af7Sopenharmony_ci
74e5c31af7Sopenharmony_ciAlways use the one-line title form, with one to four `=` signs preceding the
75e5c31af7Sopenharmony_cichapter/section title.
76e5c31af7Sopenharmony_ciThe two-line title form cannot be easily searched for, and often looks like
77e5c31af7Sopenharmony_ciother types of asciidoctor delimiters.
78e5c31af7Sopenharmony_ciUsing a mix of one-line and two-line titles causes compatibility issues, and
79e5c31af7Sopenharmony_ciusing the two-line title form may implicitly set a backwards-compatibility
80e5c31af7Sopenharmony_cisyntax mode we do not want.
81e5c31af7Sopenharmony_ci
82e5c31af7Sopenharmony_ciAlways precede the anchor by two blank lines (except at the beginning of a
83e5c31af7Sopenharmony_cifile), and follow the title by a blank line, to set off sections visibly.
84e5c31af7Sopenharmony_ci
85e5c31af7Sopenharmony_ci[source,asciidoc]
86e5c31af7Sopenharmony_ci.Example Markup
87e5c31af7Sopenharmony_ci----
88e5c31af7Sopenharmony_ci[[markup]]
89e5c31af7Sopenharmony_ci= Markup Style
90e5c31af7Sopenharmony_ci
91e5c31af7Sopenharmony_ci
92e5c31af7Sopenharmony_ci[[markup-sample-section]]
93e5c31af7Sopenharmony_ci== Sample Section
94e5c31af7Sopenharmony_ci----
95e5c31af7Sopenharmony_ci
96e5c31af7Sopenharmony_ci
97e5c31af7Sopenharmony_ci[[markup-include-file-paths]]
98e5c31af7Sopenharmony_ci=== Include File Paths
99e5c31af7Sopenharmony_ci
100e5c31af7Sopenharmony_ciWhen using the asciidoctor `include::` directive anywhere other than the
101e5c31af7Sopenharmony_citop-level file of the document, always use a full (absolute) path to the
102e5c31af7Sopenharmony_cifile being included.
103e5c31af7Sopenharmony_ciTo make this easier, the specification build process defines several
104e5c31af7Sopenharmony_ciattributes which refer to different paths in the document tree:
105e5c31af7Sopenharmony_ci
106e5c31af7Sopenharmony_ci  * `\{chapters}` - path to the `chapters/` directory containing most of the
107e5c31af7Sopenharmony_ci    specification.
108e5c31af7Sopenharmony_ci  * `\{appendices}` - path to the `appendices/` directory containing
109e5c31af7Sopenharmony_ci    appendices.
110e5c31af7Sopenharmony_ci  * `\{generated}` - path to the temporary directory containing generated
111e5c31af7Sopenharmony_ci    files such as API includes.
112e5c31af7Sopenharmony_ci  * `\{config}` - path to configuration files used in the spec toolchain.
113e5c31af7Sopenharmony_ci
114e5c31af7Sopenharmony_ciNumerous examples of using these attributes are given in the <<writing,
115e5c31af7Sopenharmony_ciWriting Style>> and <<extensions, API Versions, Extensions, and Layers>>
116e5c31af7Sopenharmony_cichapters.
117e5c31af7Sopenharmony_ci
118e5c31af7Sopenharmony_ci
119e5c31af7Sopenharmony_ci[[markup-sample-section]]
120e5c31af7Sopenharmony_ci== Sample Section
121e5c31af7Sopenharmony_ci
122e5c31af7Sopenharmony_ciThis is a sample section structurally similar to the <<vulkan-spec,Vulkan
123e5c31af7Sopenharmony_ciAPI Specification>>, nested one level inside a chapter.
124e5c31af7Sopenharmony_ciSections can be nested up to level 5, although not all levels are included
125e5c31af7Sopenharmony_ciin the Table of Contents.
126e5c31af7Sopenharmony_ci
127e5c31af7Sopenharmony_ci
128e5c31af7Sopenharmony_ci[[markup-layout]]
129e5c31af7Sopenharmony_ci== Asciidoc Markup And Text Layout
130e5c31af7Sopenharmony_ci
131e5c31af7Sopenharmony_ciAsciidoc source should be text filled to 76 columns with hard line breaks.
132e5c31af7Sopenharmony_ciEach sentence in a paragraph ends with a newline to minimize git diff
133e5c31af7Sopenharmony_ciconflicts.
134e5c31af7Sopenharmony_ciExcept when necessary for lists or other markup, text should begin at the
135e5c31af7Sopenharmony_cifirst column of each line (leading spaces are often semantically meaningful
136e5c31af7Sopenharmony_ciin asciidoctor markup).
137e5c31af7Sopenharmony_ci
138e5c31af7Sopenharmony_ciUTF-8 characters outside the ASCII subset should be used sparingly, only
139e5c31af7Sopenharmony_ciwhen needed for non-English names.
140e5c31af7Sopenharmony_ciInstead use asciidoctor markup for special characters, if required.
141e5c31af7Sopenharmony_ciFor example, two hyphens produces an em-dash:
142e5c31af7Sopenharmony_ci
143e5c31af7Sopenharmony_ci[NOTE]
144e5c31af7Sopenharmony_ci.Example Markup
145e5c31af7Sopenharmony_ci====
146e5c31af7Sopenharmony_ci
147e5c31af7Sopenharmony_ci`+An -- em-dash+` -> An -- em-dash
148e5c31af7Sopenharmony_ci====
149e5c31af7Sopenharmony_ci
150e5c31af7Sopenharmony_ciAs an exception, multiplication should be marked with the unicode
151e5c31af7Sopenharmony_cimultiplication symbol "`×`" (and *not* an asterisk) when used in plain text.
152e5c31af7Sopenharmony_ciYou may also use the `\{times}` asciidoctor attribute for this symbol.
153e5c31af7Sopenharmony_ciIn math sections, the same symbol should be referred to as `\times`.
154e5c31af7Sopenharmony_ciIn code sections, a conventional asterisk (`*`) should be used instead.
155e5c31af7Sopenharmony_ci
156e5c31af7Sopenharmony_ciThe trailing `+` character causes a hard break in asciidoctor markup, and
157e5c31af7Sopenharmony_cishould not be used except for this purpose.
158e5c31af7Sopenharmony_ciMarkup addition with the \{plus} asciidoctor attribute, except in
159e5c31af7Sopenharmony_ci<<writing-math-latexmath, LaTeX math>> and <<markup-blocks, source blocks>>.
160e5c31af7Sopenharmony_ci
161e5c31af7Sopenharmony_ciSee the Asciidoctor docs for
162e5c31af7Sopenharmony_cilink:{docguide}/subs/special-characters[supported special characters], as
163e5c31af7Sopenharmony_ciwell as use of entity references.
164e5c31af7Sopenharmony_ci
165e5c31af7Sopenharmony_ciQuotation marks should use the 66/99 convention.
166e5c31af7Sopenharmony_ciThat is, double asymmetric quotation marks, indicated by a quotation mark
167e5c31af7Sopenharmony_cithen a backtick as opening marks, and a backtick then quotation mark as
168e5c31af7Sopenharmony_ciclosing marks (pass:["`like this`"]), which renders "`like this`".
169e5c31af7Sopenharmony_ci
170e5c31af7Sopenharmony_ci_Never_ use hard tabs or trailing blanks.
171e5c31af7Sopenharmony_ci
172e5c31af7Sopenharmony_ci* In some cases, limitations of asciidoctor markup may result in lines that
173e5c31af7Sopenharmony_ci  are longer than 76 characters and cannot easily be shortened without
174e5c31af7Sopenharmony_ci  compromising the output documents.
175e5c31af7Sopenharmony_ci
176e5c31af7Sopenharmony_ci
177e5c31af7Sopenharmony_ci[[markup-minimize-indentation]]
178e5c31af7Sopenharmony_ci=== Minimize Indentation
179e5c31af7Sopenharmony_ci
180e5c31af7Sopenharmony_ciIndentation (leading whitespace) for markup should not be used, except for
181e5c31af7Sopenharmony_ci<<markup-sample-section-bullet-lists, bullet lists>> as described below.
182e5c31af7Sopenharmony_ciLeading whitespace can affect asciidoctor processing.
183e5c31af7Sopenharmony_ci
184e5c31af7Sopenharmony_ciWhen presenting unformatted text, use asciidoctor source blocks as described
185e5c31af7Sopenharmony_ciin the next section.
186e5c31af7Sopenharmony_ciSource blocks do allow leading whitespace, for example when including sample
187e5c31af7Sopenharmony_cicode in C.
188e5c31af7Sopenharmony_ci
189e5c31af7Sopenharmony_ci
190e5c31af7Sopenharmony_ci[[markup-blocks]]
191e5c31af7Sopenharmony_ci=== Blocks
192e5c31af7Sopenharmony_ci
193e5c31af7Sopenharmony_ciThere are a variety of asciidoctor _block_ constructs.
194e5c31af7Sopenharmony_ciWith the exception of <<markup-sample-section-tables,tables>> and of _open
195e5c31af7Sopenharmony_ciblocks_ used to group markup together, blocks should be delimited by exactly
196e5c31af7Sopenharmony_cifour repeated characters indicating the block type, for consistency.
197e5c31af7Sopenharmony_ciThe block types and delimiters are shown in the following table.
198e5c31af7Sopenharmony_ci
199e5c31af7Sopenharmony_ci.Asciidoc Block Delimiters
200e5c31af7Sopenharmony_ci[width="70%",options="header",cols="25%,10%,65%"]
201e5c31af7Sopenharmony_ci|====
202e5c31af7Sopenharmony_ci| Table Type    | Delimiter     | Comments
203e5c31af7Sopenharmony_ci| Open          | `--`          | For <<markup-sample-section-bullet-lists,continuation blocks>>
204e5c31af7Sopenharmony_ci| Example       | `====`        | For <<markup-informative-notes,Notes>>
205e5c31af7Sopenharmony_ci| Passthrough   | `pass:[++++]` | For some kinds of <<writing-math,math markup>>
206e5c31af7Sopenharmony_ci| Comment       | `////`        |
207e5c31af7Sopenharmony_ci| Listing       | `----`        | For source code listings
208e5c31af7Sopenharmony_ci| Listing (alt.)| `pass:[~~~~]` | For source code listings <<markup-blocks-source, imbedded in Open blocks>>
209e5c31af7Sopenharmony_ci| Sidebar       | `pass:[****]` | For <<markup-implementors-notes,implementor's notes>>
210e5c31af7Sopenharmony_ci| Table         | `\|====`      | For <<markup-sample-section-tables,tables>>
211e5c31af7Sopenharmony_ci| Quote         | `pass:[____]` |
212e5c31af7Sopenharmony_ci| Literal       | `pass:[....]` |
213e5c31af7Sopenharmony_ci|====
214e5c31af7Sopenharmony_ci
215e5c31af7Sopenharmony_ci
216e5c31af7Sopenharmony_ci[[markup-blocks-source]]
217e5c31af7Sopenharmony_ci==== Listing Blocks Imbedded in Open Blocks
218e5c31af7Sopenharmony_ci
219e5c31af7Sopenharmony_ciIf you need to include a `source` block that would normally use `----`
220e5c31af7Sopenharmony_cidelimiters inside an open block delimiting a reference page, use
221e5c31af7Sopenharmony_ci`pass:[~~~~]` delimiters around the inner source block instead.
222e5c31af7Sopenharmony_ciThis avoids confusing some of the toolchain which makes assumptions about
223e5c31af7Sopenharmony_ciblock delimiters not being nested, such as the VUID assignment script.
224e5c31af7Sopenharmony_ciTildes are not standard asciidoctor markup, but are supported by a custom
225e5c31af7Sopenharmony_ciRuby extension.
226e5c31af7Sopenharmony_ci
227e5c31af7Sopenharmony_ci
228e5c31af7Sopenharmony_ci[[markup-footnotes]]
229e5c31af7Sopenharmony_ci=== Footnotes
230e5c31af7Sopenharmony_ci
231e5c31af7Sopenharmony_ciUse manually marked-up footnotes (the asciidoctor footnote construct is OK
232e5c31af7Sopenharmony_cifor PDF outputs, but does not work well with long HTML documents since it
233e5c31af7Sopenharmony_ciplaces all footnotes at the end of the document).
234e5c31af7Sopenharmony_ci
235e5c31af7Sopenharmony_ciRefer to footnotes with asciidoctor superscript notation^1^, and mark up the
236e5c31af7Sopenharmony_cifootnotes below, but near the references as labelled lists.
237e5c31af7Sopenharmony_ciManually assigned footnote numbers will inevitably be reused, which is OK as
238e5c31af7Sopenharmony_cilong as the colliding numbers are not in the same section.
239e5c31af7Sopenharmony_ci
240e5c31af7Sopenharmony_ci1::
241e5c31af7Sopenharmony_ci    Like this example footnote.
242e5c31af7Sopenharmony_ci
243e5c31af7Sopenharmony_ci[NOTE]
244e5c31af7Sopenharmony_ci====
245e5c31af7Sopenharmony_ci.Example Markup
246e5c31af7Sopenharmony_ci[source,asciidoc]
247e5c31af7Sopenharmony_ci----
248e5c31af7Sopenharmony_ciSee reference^2^
249e5c31af7Sopenharmony_ci
250e5c31af7Sopenharmony_ci2::
251e5c31af7Sopenharmony_ci    Reference 2.
252e5c31af7Sopenharmony_ci----
253e5c31af7Sopenharmony_ci
254e5c31af7Sopenharmony_ci->
255e5c31af7Sopenharmony_ci
256e5c31af7Sopenharmony_ciSee reference^2^
257e5c31af7Sopenharmony_ci
258e5c31af7Sopenharmony_ci2::
259e5c31af7Sopenharmony_ci    Reference 2.
260e5c31af7Sopenharmony_ci====
261e5c31af7Sopenharmony_ci
262e5c31af7Sopenharmony_ci
263e5c31af7Sopenharmony_ci[[markup-sample-section-lists]]
264e5c31af7Sopenharmony_ci=== Lists
265e5c31af7Sopenharmony_ci
266e5c31af7Sopenharmony_ci
267e5c31af7Sopenharmony_ci[[markup-sample-section-bullet-lists]]
268e5c31af7Sopenharmony_ci==== Bullet Lists and Continuation Blocks
269e5c31af7Sopenharmony_ci
270e5c31af7Sopenharmony_ci  * Bullet lists are the preferred form of list, aside from glossary
271e5c31af7Sopenharmony_ci    definitions.
272e5c31af7Sopenharmony_ci  * Lists should have text indented by 4 spaces and the list item delimiter
273e5c31af7Sopenharmony_ci    (e.g. one or more asterisks, for bullet lists) indented by two spaces.
274e5c31af7Sopenharmony_ci+
275e5c31af7Sopenharmony_ciNote that continuation blocks for list items longer than one paragraph
276e5c31af7Sopenharmony_cicannot be indented, only the first paragraph.
277e5c31af7Sopenharmony_ci+
278e5c31af7Sopenharmony_ciIn general, successive list items should not be separated by white space.
279e5c31af7Sopenharmony_ciHowever, list continuation blocks should be followed by a `+` on a line by
280e5c31af7Sopenharmony_ciitself, or by a blank line, due to limitations of the asciidoctor parser.
281e5c31af7Sopenharmony_ci+
282e5c31af7Sopenharmony_ci  * Indent bullet lists two spaces (to the bullet), 4 spaces (to the text,
283e5c31af7Sopenharmony_ci    if it extends over multiple lines).
284e5c31af7Sopenharmony_ci    This lets us visually distinguish lists from other kinds of markup.
285e5c31af7Sopenharmony_ci  ** Nested lists should align the leftmost list item delimiter (bullet,
286e5c31af7Sopenharmony_ci     etc.) with the parent delimiter.
287e5c31af7Sopenharmony_ci
288e5c31af7Sopenharmony_ci[source,asciidoc]
289e5c31af7Sopenharmony_ci.Example Markup
290e5c31af7Sopenharmony_ci----
291e5c31af7Sopenharmony_ci  * This is the first item in a bullet list.
292e5c31af7Sopenharmony_ci  * The second item is described with two paragraphs.
293e5c31af7Sopenharmony_ci    The second paragraph is in a continuation block:
294e5c31af7Sopenharmony_ci+
295e5c31af7Sopenharmony_ciThis is a continuation block containing the second paragraph,
296e5c31af7Sopenharmony_ci+
297e5c31af7Sopenharmony_ci  ** This is a nested list item for the second item.
298e5c31af7Sopenharmony_ci     Since it follows a continuation block, it must be separated by a blank
299e5c31af7Sopenharmony_ci     line or `+` from that block.
300e5c31af7Sopenharmony_ci----
301e5c31af7Sopenharmony_ci
302e5c31af7Sopenharmony_ci[example]
303e5c31af7Sopenharmony_ci====
304e5c31af7Sopenharmony_ci  * This is the first item in a bullet list.
305e5c31af7Sopenharmony_ci  * The second item is described with two paragraphs.
306e5c31af7Sopenharmony_ci    The second paragraph is in a continuation block:
307e5c31af7Sopenharmony_ci+
308e5c31af7Sopenharmony_ciThis is a continuation block containing the second paragraph,
309e5c31af7Sopenharmony_ci+
310e5c31af7Sopenharmony_ci  ** This is a nested list item for the second item.
311e5c31af7Sopenharmony_ci     Since it follows a continuation block, it must be separated by a blank
312e5c31af7Sopenharmony_ci     line or `+` from that block.
313e5c31af7Sopenharmony_ci====
314e5c31af7Sopenharmony_ci
315e5c31af7Sopenharmony_ci  * It is possible to continue a paragraph of the first bullet after a list
316e5c31af7Sopenharmony_ci    of sub-bullets if so desired by using continuations in a similar
317e5c31af7Sopenharmony_ci    fashion:
318e5c31af7Sopenharmony_ci
319e5c31af7Sopenharmony_ci[source,asciidoc]
320e5c31af7Sopenharmony_ci.Example Markup
321e5c31af7Sopenharmony_ci----
322e5c31af7Sopenharmony_ci  * This an item in a bullet list.
323e5c31af7Sopenharmony_ci+
324e5c31af7Sopenharmony_ci  ** This is a nested list item for the second item.
325e5c31af7Sopenharmony_ci     Since it follows a continuation block, it must be separated by a blank
326e5c31af7Sopenharmony_ci     line or `+` from that block.
327e5c31af7Sopenharmony_ci+
328e5c31af7Sopenharmony_ciThis is a continuation of the first bullet
329e5c31af7Sopenharmony_ci----
330e5c31af7Sopenharmony_ci
331e5c31af7Sopenharmony_ci[example]
332e5c31af7Sopenharmony_ci====
333e5c31af7Sopenharmony_ci  * This an item in a bullet list.
334e5c31af7Sopenharmony_ci+
335e5c31af7Sopenharmony_ci  ** This is a nested list item for the second item.
336e5c31af7Sopenharmony_ci     Since it follows a continuation block, it must be separated by a blank
337e5c31af7Sopenharmony_ci     line or `+` from that block.
338e5c31af7Sopenharmony_ci+
339e5c31af7Sopenharmony_ciThis is a continuation of the first bullet
340e5c31af7Sopenharmony_ci====
341e5c31af7Sopenharmony_ci
342e5c31af7Sopenharmony_ci[[markup-labelled-lists]]
343e5c31af7Sopenharmony_ci==== Labelled Lists
344e5c31af7Sopenharmony_ci
345e5c31af7Sopenharmony_ciLabelled lists may be used in some cases such as
346e5c31af7Sopenharmony_ci<<markup-footnotes,footnotes>>; glossary entries; and long lists of
347e5c31af7Sopenharmony_ciinformation about similar names, such as the "`Features, Limits, and
348e5c31af7Sopenharmony_ciFormats`" chapter of the Vulkan Specification.
349e5c31af7Sopenharmony_ciWhenever labelled lists are used the label and its terminating double colon
350e5c31af7Sopenharmony_cimust be alone on a line, followed by the contents of that list entry.
351e5c31af7Sopenharmony_ci
352e5c31af7Sopenharmony_ciFor consistency do not use labels ending in three or four colons, or two
353e5c31af7Sopenharmony_cisemicolons, even though these forms are allowed in asciidoctor markup.
354e5c31af7Sopenharmony_ci
355e5c31af7Sopenharmony_ci[source,asciidoc]
356e5c31af7Sopenharmony_ci.Example Markup
357e5c31af7Sopenharmony_ci----
358e5c31af7Sopenharmony_ciGlossary Entry::
359e5c31af7Sopenharmony_ci    This is a glossary entry.
360e5c31af7Sopenharmony_ci
361e5c31af7Sopenharmony_ciLast Modified Date::
362e5c31af7Sopenharmony_ci    2016-02-16
363e5c31af7Sopenharmony_ci----
364e5c31af7Sopenharmony_ci
365e5c31af7Sopenharmony_ci
366e5c31af7Sopenharmony_ci[[markup-numbered-lists]]
367e5c31af7Sopenharmony_ci==== Numbered Lists
368e5c31af7Sopenharmony_ci
369e5c31af7Sopenharmony_ciNumbered lists may be used if strictly necessary to place an ordering on
370e5c31af7Sopenharmony_cilist items.
371e5c31af7Sopenharmony_ciAlways use _implicit numbering_, with the bullet point being a single
372e5c31af7Sopenharmony_ciperiod.
373e5c31af7Sopenharmony_ci
374e5c31af7Sopenharmony_ci  . Explicit numbering with a number preceding the period is prone to
375e5c31af7Sopenharmony_ci    accumulating errors as edits are made.
376e5c31af7Sopenharmony_ci  . In addition, the markup is harder to recognize for scripts and tools
377e5c31af7Sopenharmony_ci    (other than asciidoctor itself) operating on the document source.
378e5c31af7Sopenharmony_ci
379e5c31af7Sopenharmony_ci[source,asciidoc]
380e5c31af7Sopenharmony_ci.Example Markup
381e5c31af7Sopenharmony_ci----
382e5c31af7Sopenharmony_ci. First list item.
383e5c31af7Sopenharmony_ci. Second list item.
384e5c31af7Sopenharmony_ci. Etc.
385e5c31af7Sopenharmony_ci----
386e5c31af7Sopenharmony_ci
387e5c31af7Sopenharmony_ci
388e5c31af7Sopenharmony_ci[[markup-sample-section-anchors]]
389e5c31af7Sopenharmony_ci=== Anchors and Cross-references
390e5c31af7Sopenharmony_ci
391e5c31af7Sopenharmony_ciIn general, chapters and sections should always have anchors, following the
392e5c31af7Sopenharmony_cinaming convention <<markup,discussed above>>.
393e5c31af7Sopenharmony_ciAnchors to other sections of the document may be inserted as needed.
394e5c31af7Sopenharmony_ciIn addition, the autogenerated include files defining commands, structures,
395e5c31af7Sopenharmony_cienumerations and flags all define anchors whose name is the name of the
396e5c31af7Sopenharmony_cicommand or type being defined, so it is easy to link to a (for example) a
397e5c31af7Sopenharmony_cicommand name such as <<vkCreateCommandPool,vkCreateCommandPool>>.
398e5c31af7Sopenharmony_ciHowever, using the <<markup-macros,markup macros>> described below is
399e5c31af7Sopenharmony_cipreferred when linking to anchors corresponding to API names, such as
400e5c31af7Sopenharmony_ciflink:vkCreateCommandPool.
401e5c31af7Sopenharmony_ci
402e5c31af7Sopenharmony_ciIf you want a cross-reference to an anchor to appear as something other than
403e5c31af7Sopenharmony_cithe raw anchor name, always make sure to include that text as part of the
404e5c31af7Sopenharmony_cicross-reference.
405e5c31af7Sopenharmony_ciThere are several different toolchains followed for various forms of
406e5c31af7Sopenharmony_ciasciidoctor output, and not all of them treat anchors without alt-text the
407e5c31af7Sopenharmony_cisame way.
408e5c31af7Sopenharmony_ci
409e5c31af7Sopenharmony_ci[source,asciidoc]
410e5c31af7Sopenharmony_ci.Example Markup
411e5c31af7Sopenharmony_ci----
412e5c31af7Sopenharmony_ciIn general, chapters and sections should always have anchors, following the
413e5c31af7Sopenharmony_cinaming convention <<markup,discussed above>>.
414e5c31af7Sopenharmony_ci...
415e5c31af7Sopenharmony_ciso it is easy to link to a (for example) a command name such as
416e5c31af7Sopenharmony_ci<<vkCreateCommandPool,vkCreateCommandPool>>. However, using the
417e5c31af7Sopenharmony_ci<<markup-macros,markup macros>> described below is preferred when linking to
418e5c31af7Sopenharmony_cianchors corresponding to API names, such as flink:vkCreateCommandPool.
419e5c31af7Sopenharmony_ci----
420e5c31af7Sopenharmony_ci
421e5c31af7Sopenharmony_ci
422e5c31af7Sopenharmony_ci[[markup-sample-section-tables]]
423e5c31af7Sopenharmony_ci=== Tables
424e5c31af7Sopenharmony_ci
425e5c31af7Sopenharmony_ciAsciidoc tables should use the block prefix `|====`.
426e5c31af7Sopenharmony_ciWhere feasible, align the `|` separating cells across rows.
427e5c31af7Sopenharmony_ciThis will sometimes result in very wide tables in the source document, but
428e5c31af7Sopenharmony_cimakes it easier to see which cells belong to which column.
429e5c31af7Sopenharmony_ciAlternatively, long cells can be broken onto a separate line with the `|`
430e5c31af7Sopenharmony_ciseparator appearing first, except for the first row of the table, which must
431e5c31af7Sopenharmony_ciall appear on a single line.
432e5c31af7Sopenharmony_ci
433e5c31af7Sopenharmony_ciTables should usually be preceded with a short title.
434e5c31af7Sopenharmony_ci
435e5c31af7Sopenharmony_ci[source,asciidoc]
436e5c31af7Sopenharmony_ci.Example Markup
437e5c31af7Sopenharmony_ci----
438e5c31af7Sopenharmony_ci.Normative Terminology Macros
439e5c31af7Sopenharmony_ci[width="100%",options="header"]
440e5c31af7Sopenharmony_ci|====
441e5c31af7Sopenharmony_ci| Macro Name     | Output
442e5c31af7Sopenharmony_ci| can{cl}        | can:
443e5c31af7Sopenharmony_ci| cannot{cl}     | cannot:
444e5c31af7Sopenharmony_ci|====
445e5c31af7Sopenharmony_ci----
446e5c31af7Sopenharmony_ci
447e5c31af7Sopenharmony_ci
448e5c31af7Sopenharmony_ci[[markup-sample-section-images]]
449e5c31af7Sopenharmony_ci=== Figures
450e5c31af7Sopenharmony_ci
451e5c31af7Sopenharmony_ciAll figures (images) must be marked up as follows, to ensure there is an
452e5c31af7Sopenharmony_cianchor and that the figure is given a caption which shows the figure number
453e5c31af7Sopenharmony_ciand is added to the list of figures.
454e5c31af7Sopenharmony_ci
455e5c31af7Sopenharmony_ci[source,asciidoc]
456e5c31af7Sopenharmony_ci.Example Markup
457e5c31af7Sopenharmony_ci----
458e5c31af7Sopenharmony_ci[[fig-anchorname]]
459e5c31af7Sopenharmony_ciimage::{images}/imagename.svg[align="center",title="Figure caption",opts="{imageopts}"]
460e5c31af7Sopenharmony_ci----
461e5c31af7Sopenharmony_ci
462e5c31af7Sopenharmony_ciThere must be SVG versions of each figure checked into the `images/`
463e5c31af7Sopenharmony_cidirectory, to support generating both HTML and PDF outputs.
464e5c31af7Sopenharmony_ciThis directory is referred to as `\{images}` so that there is a consistent
465e5c31af7Sopenharmony_cipath no matter what directory the file including the images is in.
466e5c31af7Sopenharmony_ciThe PDF generation pipeline is now able to use SVG images, so PDF versions
467e5c31af7Sopenharmony_ciof each image are no longer required.
468e5c31af7Sopenharmony_ciThe `opts=` attribute defaults to `inline`, which decreases output image
469e5c31af7Sopenharmony_cisize in the generated HTML.
470e5c31af7Sopenharmony_ciHowever, the `inline` option interferes with generating HTML diffs between
471e5c31af7Sopenharmony_citwo specifications with the script we currently use.
472e5c31af7Sopenharmony_ciBy using an asciidoctor attribute, this behavior can be controlled.
473e5c31af7Sopenharmony_ci
474e5c31af7Sopenharmony_ciAsciidoctor restricts captions in figures to be a single line in the source
475e5c31af7Sopenharmony_cidocument.
476e5c31af7Sopenharmony_ciIf a longer caption is required, follow the figure directive with a sidebar
477e5c31af7Sopenharmony_ciblock including the full caption preceded by a link to the figure:
478e5c31af7Sopenharmony_ci
479e5c31af7Sopenharmony_ci[source,asciidoc]
480e5c31af7Sopenharmony_ci.Example Markup
481e5c31af7Sopenharmony_ci----
482e5c31af7Sopenharmony_ci.Caption
483e5c31af7Sopenharmony_ci****
484e5c31af7Sopenharmony_ciIn the <<fig-anchorname,Figure caption>> diagram, the diagram represents
485e5c31af7Sopenharmony_ci... long caption text here.
486e5c31af7Sopenharmony_ci****
487e5c31af7Sopenharmony_ci----
488e5c31af7Sopenharmony_ci
489e5c31af7Sopenharmony_ci
490e5c31af7Sopenharmony_ci[[markup-indentation-equations]]
491e5c31af7Sopenharmony_ci=== Indentation of Equations
492e5c31af7Sopenharmony_ci
493e5c31af7Sopenharmony_ciAsciidoctor separates structural markup in asciidoctor source from
494e5c31af7Sopenharmony_ciformatting, in HTML CSS stylesheets and invoked via asciidoctor "`role`"
495e5c31af7Sopenharmony_ciattributes on blocks.
496e5c31af7Sopenharmony_ciHowever, the flexibility of CSS stylesheets is not available in PDF layout
497e5c31af7Sopenharmony_ciusing the existing PDF toolchain and YML stylesheets.
498e5c31af7Sopenharmony_ci
499e5c31af7Sopenharmony_ciExplicit indentation should be used sparingly in the specification, but one
500e5c31af7Sopenharmony_ciplace it is useful is with equations.
501e5c31af7Sopenharmony_ciUsing <<writing-math, asciidoctor math markup>>, the easiest way to produce
502e5c31af7Sopenharmony_ciindentation is with a list where the leading bullet or descriptive text is
503e5c31af7Sopenharmony_cisuppressed
504e5c31af7Sopenharmony_ci
505e5c31af7Sopenharmony_ci[source,asciidoc]
506e5c31af7Sopenharmony_ci.Example Markup
507e5c31af7Sopenharmony_ci----
508e5c31af7Sopenharmony_ci[none]
509e5c31af7Sopenharmony_ci  * A {plus} B
510e5c31af7Sopenharmony_ci
511e5c31af7Sopenharmony_cior
512e5c31af7Sopenharmony_ci
513e5c31af7Sopenharmony_ci  {empty}:: A {plus} B
514e5c31af7Sopenharmony_ci----
515e5c31af7Sopenharmony_ci
516e5c31af7Sopenharmony_ci->
517e5c31af7Sopenharmony_ci
518e5c31af7Sopenharmony_ci[example]
519e5c31af7Sopenharmony_ci====
520e5c31af7Sopenharmony_ci[none]
521e5c31af7Sopenharmony_ci  * A {plus} B
522e5c31af7Sopenharmony_ci
523e5c31af7Sopenharmony_cior
524e5c31af7Sopenharmony_ci
525e5c31af7Sopenharmony_ci  {empty}:: A {plus} B
526e5c31af7Sopenharmony_ci====
527e5c31af7Sopenharmony_ci
528e5c31af7Sopenharmony_ci
529e5c31af7Sopenharmony_ci[[markup-italicized-enumerant-names]]
530e5c31af7Sopenharmony_ci=== Italicized Enumerant Names
531e5c31af7Sopenharmony_ci
532e5c31af7Sopenharmony_ciWhen writing a "`wildcard`" enumerant name containing an italicized term
533e5c31af7Sopenharmony_ciwithin it, it is difficult to directly combine constrained formatting markup
534e5c31af7Sopenharmony_ci(double underscores) and the single underscores that separate words in the
535e5c31af7Sopenharmony_cienumerant.
536e5c31af7Sopenharmony_ciInstead, use attribute substitution as suggested in the "`Escape
537e5c31af7Sopenharmony_ciunconstrained formatting marks`" section of the AsciiDoc Language
538e5c31af7Sopenharmony_ciDocumentation.
539e5c31af7Sopenharmony_ciTo help when this is required, an attribute `\{ibit}` expanding to
540e5c31af7Sopenharmony_ci`pass:[_i_]` is defined in `config/attribs.txt`, and the same technique can
541e5c31af7Sopenharmony_cibe used for similar markup in other cases if `_i_` is not the desired
542e5c31af7Sopenharmony_ciitalicized term:
543e5c31af7Sopenharmony_ci
544e5c31af7Sopenharmony_ci[source,asciidoc]
545e5c31af7Sopenharmony_ci.Example Markup
546e5c31af7Sopenharmony_ci----
547e5c31af7Sopenharmony_ci`VK_IMAGE_ASPECT_PLANE__{ibit}__BIT`
548e5c31af7Sopenharmony_ci----
549e5c31af7Sopenharmony_ci
550e5c31af7Sopenharmony_ci->
551e5c31af7Sopenharmony_ci
552e5c31af7Sopenharmony_ci[example]
553e5c31af7Sopenharmony_ci====
554e5c31af7Sopenharmony_ci`VK_IMAGE_ASPECT_PLANE__{ibit}__BIT`
555e5c31af7Sopenharmony_ci====
556e5c31af7Sopenharmony_ci
557e5c31af7Sopenharmony_ci[NOTE]
558e5c31af7Sopenharmony_ci.Note
559e5c31af7Sopenharmony_ci====
560e5c31af7Sopenharmony_ciThis technique cannot be used with the <<markup-macros, markup macros>> that
561e5c31af7Sopenharmony_ciare normally used to semantically tag API names.
562e5c31af7Sopenharmony_ciBecause there are so few places it is needed, conventional backquote
563e5c31af7Sopenharmony_ciformatting markup is used instead.
564e5c31af7Sopenharmony_ci====
565e5c31af7Sopenharmony_ci
566e5c31af7Sopenharmony_ci
567e5c31af7Sopenharmony_ci[[markup-macros]]
568e5c31af7Sopenharmony_ci== Markup Macros and Normative Terminology
569e5c31af7Sopenharmony_ci
570e5c31af7Sopenharmony_ciThis section discusses Asciidoc macros used in the document.
571e5c31af7Sopenharmony_ciIn addition to the macros defined by asciidoctor itself, additional macros
572e5c31af7Sopenharmony_ciare defined by the <<vulkan-spec,Vulkan API Specification>> and Reference
573e5c31af7Sopenharmony_ciPage configuration files.
574e5c31af7Sopenharmony_ci
575e5c31af7Sopenharmony_ci
576e5c31af7Sopenharmony_ci[[markup-macros-api]]
577e5c31af7Sopenharmony_ci=== API Markup Macros
578e5c31af7Sopenharmony_ci
579e5c31af7Sopenharmony_ciThese macros must be used to tag command, structure, enumeration, enumerant,
580e5c31af7Sopenharmony_ciand other Vulkan-specific names so they can be rendered in a distinctive
581e5c31af7Sopenharmony_cifashion, link to definitions of those names, and be easily searched for in
582e5c31af7Sopenharmony_cithe source documents.
583e5c31af7Sopenharmony_ciThe validation scripts (`make allchecks` output) also rely on these macros
584e5c31af7Sopenharmony_cibeing used consistently and correctly.
585e5c31af7Sopenharmony_ciThe API markup macros, with examples of their use, are in the following
586e5c31af7Sopenharmony_citable (note that these examples will not actually successfully link into
587e5c31af7Sopenharmony_cicorresponding specification or reference pages, since they are in an
588e5c31af7Sopenharmony_ciunrelated document).
589e5c31af7Sopenharmony_ci
590e5c31af7Sopenharmony_ci.API Markup Macros
591e5c31af7Sopenharmony_ci[width="100%",options="header",cols="20%,80%"]
592e5c31af7Sopenharmony_ci|====
593e5c31af7Sopenharmony_ci| Macro Name    | Usage and Meaning
594e5c31af7Sopenharmony_ci| reflink{cl}   | Generates a cross-reference or link to an unknown type of
595e5c31af7Sopenharmony_ci                  API entity. This is only used in generated content in the
596e5c31af7Sopenharmony_ci                  reference pages which refers to other reference pages
597e5c31af7Sopenharmony_ci                  which are not actually part of the API. Example:
598e5c31af7Sopenharmony_ci                  reflink{cl}WSIheaders -> reflink:WSIheaders.
599e5c31af7Sopenharmony_ci| pass:c[`apiext:`] | Generates a cross-reference or link to the description
600e5c31af7Sopenharmony_ci                  of an extension. Example: pass:c[`apiext:VK_KHR_ray_tracing_pipeline`]
601e5c31af7Sopenharmony_ci                  -> `apiext:VK_KHR_ray_tracing_pipeline`.
602e5c31af7Sopenharmony_ci| flink{cl}     | Generates a cross-reference or link to the definition of
603e5c31af7Sopenharmony_ci                  the command name in the macro argument. Example:
604e5c31af7Sopenharmony_ci                  flink{cl}vkCreateCommandPool -> flink:vkCreateCommandPool.
605e5c31af7Sopenharmony_ci| fname{cl}     | Formats the macro argument like flink{cl}. Does not
606e5c31af7Sopenharmony_ci                  generate a cross-reference. Example:
607e5c31af7Sopenharmony_ci                  fname{cl}vkCreateCommandPool -> fname:vkCreateCommandPool.
608e5c31af7Sopenharmony_ci
609e5c31af7Sopenharmony_ci                  Only use this macro <<markup-macros-api-name, when
610e5c31af7Sopenharmony_ci                  necessary>>.
611e5c31af7Sopenharmony_ci| ftext{cl}     | Formats the macro argument like fname{cl}. May contain
612e5c31af7Sopenharmony_ci                  asterisks for wildcards. Not validated. Example:
613e5c31af7Sopenharmony_ci                  ftext{cl}vkCmd* -> ftext:vkCmd*.
614e5c31af7Sopenharmony_ci
615e5c31af7Sopenharmony_ci                  Only use this macro <<markup-macros-api-text, when
616e5c31af7Sopenharmony_ci                  necessary>>.
617e5c31af7Sopenharmony_ci| slink{cl}     | Generates a cross-reference or link to the definition
618e5c31af7Sopenharmony_ci                  of the structure or handle in the macro argument. Example:
619e5c31af7Sopenharmony_ci                  slink{cl}VkMemoryHeap -> slink:VkMemoryHeap.
620e5c31af7Sopenharmony_ci| sname{cl}     | Formats the macro argument like slink{cl}. Does not
621e5c31af7Sopenharmony_ci                  generate a cross-reference. May also be an abstract
622e5c31af7Sopenharmony_ci                  structure or handle name. Example:
623e5c31af7Sopenharmony_ci                  sname{cl}VkCommandPoolCreateInfo ->
624e5c31af7Sopenharmony_ci                  sname:VkCommandPoolCreateInfo.
625e5c31af7Sopenharmony_ci
626e5c31af7Sopenharmony_ci                  Only use this macro <<markup-macros-api-name, when
627e5c31af7Sopenharmony_ci                  necessary>>.
628e5c31af7Sopenharmony_ci| stext{cl}     | Formats the macro argument like sname{cl}. May contain
629e5c31af7Sopenharmony_ci                  asterisks for wildcards. Not validated. Example:
630e5c31af7Sopenharmony_ci                  stext{cl}Vk*CreateInfo -> stext:Vk*CreateInfo.
631e5c31af7Sopenharmony_ci
632e5c31af7Sopenharmony_ci                  Only use this macro <<markup-macros-api-text, when
633e5c31af7Sopenharmony_ci                  necessary>>.
634e5c31af7Sopenharmony_ci| elink{cl}     | Formats the macro argument as a Vulkan enumerated
635e5c31af7Sopenharmony_ci                  type name and links to the definition of that enumeration
636e5c31af7Sopenharmony_ci                  type. Example: elink{cl}VkResult -> elink:VkResult.
637e5c31af7Sopenharmony_ci| ename{cl}     | Formats the macro argument as a Vulkan enumerant name.
638e5c31af7Sopenharmony_ci                  Example: ename{cl}VK_EVENT_SET -> ename:VK_EVENT_SET.
639e5c31af7Sopenharmony_ci                  Note that this is not related to elink{cl}, unlike the
640e5c31af7Sopenharmony_ci                  other macro link{cl}/text{cl} pairings.
641e5c31af7Sopenharmony_ci| etext{cl}     | Formats the macro argument like ename{cl}. Not validated.
642e5c31af7Sopenharmony_ci                  Examples: etext{cl}_RANGE_SIZE -> etext:_RANGE_SIZE,
643e5c31af7Sopenharmony_ci                  etext{cl}VK_IMAGE_CREATE_SPARSE_* ->
644e5c31af7Sopenharmony_ci                  etext:VK_IMAGE_CREATE_SPARSE_*
645e5c31af7Sopenharmony_ci
646e5c31af7Sopenharmony_ci                  Only use this macro <<markup-macros-api-text, when
647e5c31af7Sopenharmony_ci                  necessary>>.
648e5c31af7Sopenharmony_ci| pname{cl}     | Formats the macro argument as a Vulkan parameter or
649e5c31af7Sopenharmony_ci                  structure member name. Example: pname{cl}device ->
650e5c31af7Sopenharmony_ci                  pname:device.
651e5c31af7Sopenharmony_ci| ptext{cl}     | Formats the macro argument like pname{cl}. May contain
652e5c31af7Sopenharmony_ci                  asterisks for wildcards. Not validated. Example:
653e5c31af7Sopenharmony_ci                  ptext{cl}sparseResidency* -> ptext:sparseResidency*.
654e5c31af7Sopenharmony_ci
655e5c31af7Sopenharmony_ci                  Only use this macro <<markup-macros-api-text, when
656e5c31af7Sopenharmony_ci                  necessary>>.
657e5c31af7Sopenharmony_ci| tlink{cl}     | Generates a cross-reference or link to the definition
658e5c31af7Sopenharmony_ci                  of the Vulkan type in the macro argument.
659e5c31af7Sopenharmony_ci                  Example: tlink{cl}PFN_vkAllocationFunction ->
660e5c31af7Sopenharmony_ci                  tlink:PFN_vkAllocationFunction.
661e5c31af7Sopenharmony_ci                  This is only used for function pointer and `Vk*Flags`
662e5c31af7Sopenharmony_ci                  types at present, although it is a potentially a catch-all
663e5c31af7Sopenharmony_ci                  for other types not covered by a more specific macro.
664e5c31af7Sopenharmony_ci| tname{cl}     | Formats the macro argument like tlink{cl}. Does not
665e5c31af7Sopenharmony_ci                  generate a cross-reference. Example:
666e5c31af7Sopenharmony_ci                  tname{cl}PFN_vkAllocationFunction ->
667e5c31af7Sopenharmony_ci                  tname:PFN_vkAllocationFunction.
668e5c31af7Sopenharmony_ci
669e5c31af7Sopenharmony_ci                  Only use this macro <<markup-macros-api-name, when
670e5c31af7Sopenharmony_ci                  necessary>>.
671e5c31af7Sopenharmony_ci| dlink{cl}     | Generates a cross-reference or link to the definition of
672e5c31af7Sopenharmony_ci                  the Vulkan C macro in the macro argument. Example:
673e5c31af7Sopenharmony_ci                  dlink{cl}VK_NULL_HANDLE -> dlink:VK_NULL_HANDLE. There are
674e5c31af7Sopenharmony_ci                  only a few macros in the Vulkan API, described in the
675e5c31af7Sopenharmony_ci                  "`API Boilerplate`" appendix of the <<vulkan-spec,Vulkan
676e5c31af7Sopenharmony_ci                  API Specification>>
677e5c31af7Sopenharmony_ci| dname{cl}     | Formats the macro argument like dlink{cl}. Does not
678e5c31af7Sopenharmony_ci                  generate a cross-reference.
679e5c31af7Sopenharmony_ci
680e5c31af7Sopenharmony_ci                  Only use this macro <<markup-macros-api-name, when
681e5c31af7Sopenharmony_ci                  necessary>>.
682e5c31af7Sopenharmony_ci| basetype{cl}  | Formats the macro argument like a basic scalar type,
683e5c31af7Sopenharmony_ci                  handle name, of type defined by an external API. Not
684e5c31af7Sopenharmony_ci                  validated.
685e5c31af7Sopenharmony_ci                  Examples: basetype{cl}VkBool32 -> basetype:VkBool32,
686e5c31af7Sopenharmony_ci                  basetype{cl}AHardwareBuffer -> basetype:AHardwareBuffer,
687e5c31af7Sopenharmony_ci                  basetype{cl}VkDeviceSize -> basetype:VkDeviceSize.
688e5c31af7Sopenharmony_ci| code{cl}      | Formats the macro argument as a code sample.
689e5c31af7Sopenharmony_ci                  Used for SPIR-V keywords, builtin C types, and names
690e5c31af7Sopenharmony_ci                  belonging to other APIs such as Linux or Windows system
691e5c31af7Sopenharmony_ci                  calls.
692e5c31af7Sopenharmony_ci                  Examples: code{cl}uint32_t -> code:uint32_t,
693e5c31af7Sopenharmony_ci                  code{cl}ClipDistance -> code:ClipDistance.
694e5c31af7Sopenharmony_ci                  code{cl}OpImage*Gather -> code:OpImage*Gather.
695e5c31af7Sopenharmony_ci
696e5c31af7Sopenharmony_ci                  This macro allows imbedded field member (`.`) and wildcard
697e5c31af7Sopenharmony_ci                  (`*`) text separating words, ending with an optional
698e5c31af7Sopenharmony_ci                  wildcard.
699e5c31af7Sopenharmony_ci|====
700e5c31af7Sopenharmony_ci
701e5c31af7Sopenharmony_ciWhen referring to a compound name (function-parameter, or structure-member),
702e5c31af7Sopenharmony_cicombine the macros separated by two colons, resulting in
703e5c31af7Sopenharmony_ciflink:vkCmdBindIndexBuffer::pname:indexType and
704e5c31af7Sopenharmony_cislink:VkMemoryHeap::pname:flags.
705e5c31af7Sopenharmony_ciThis is often done when referring to a particular parameter or member in a
706e5c31af7Sopenharmony_cipart of the document other than the description of the corresponding
707e5c31af7Sopenharmony_cifunction or structure.
708e5c31af7Sopenharmony_ciWhen a nested member within the compound name is referred to, use normal C
709e5c31af7Sopenharmony_cimarkup:
710e5c31af7Sopenharmony_ci
711e5c31af7Sopenharmony_ci[source,asciidoc]
712e5c31af7Sopenharmony_ci.Example Markup
713e5c31af7Sopenharmony_ci----
714e5c31af7Sopenharmony_ciflink:vkCmdBindIndexBuffer::pname:indexType
715e5c31af7Sopenharmony_cisname:VkExternalImageFormatProperties::pname:externalMemoryProperties.externalMemoryFeatures
716e5c31af7Sopenharmony_cipname:pAllocateInfo->memoryTypeIndex
717e5c31af7Sopenharmony_ci----
718e5c31af7Sopenharmony_ci
719e5c31af7Sopenharmony_ci[NOTE]
720e5c31af7Sopenharmony_ci.Note
721e5c31af7Sopenharmony_ci====
722e5c31af7Sopenharmony_ciIn the macros, "```\->```" is correct markup for the C arrow operator.
723e5c31af7Sopenharmony_ciBut in any other context (including a "```````" delimited inline literal) it
724e5c31af7Sopenharmony_ciwould be subject to link:{docguide}/subs/replacements/[Asciidoctor character
725e5c31af7Sopenharmony_cireplacement substitutions], resulting in a unicode arrow: ->.
726e5c31af7Sopenharmony_ci====
727e5c31af7Sopenharmony_ci
728e5c31af7Sopenharmony_ci
729e5c31af7Sopenharmony_ci[[markup-macros-api-name]]
730e5c31af7Sopenharmony_ci==== When To Use *name: Macros
731e5c31af7Sopenharmony_ci
732e5c31af7Sopenharmony_ciOnly use the fname{cl}, sname{cl}, tname{cl}, and dname{cl} macros if no
733e5c31af7Sopenharmony_cidefinition of the target type with a corresponding anchor exists in the
734e5c31af7Sopenharmony_cidocument.
735e5c31af7Sopenharmony_ciAnchors are automatically defined when including the generated API interface
736e5c31af7Sopenharmony_cidefinitions under `\{generated}/api/*/*txt`.
737e5c31af7Sopenharmony_ciIf an anchor does exist, use the corresponding *link{cl} macro.
738e5c31af7Sopenharmony_ci
739e5c31af7Sopenharmony_ci[NOTE]
740e5c31af7Sopenharmony_ci.Note
741e5c31af7Sopenharmony_ci====
742e5c31af7Sopenharmony_ciThere are many legacy uses of the *name{cl} macros that will be replaced
743e5c31af7Sopenharmony_ciover time.
744e5c31af7Sopenharmony_ciThese uses date from before anchors were added to the generated API
745e5c31af7Sopenharmony_cidefinitions.
746e5c31af7Sopenharmony_ci====
747e5c31af7Sopenharmony_ci
748e5c31af7Sopenharmony_ci
749e5c31af7Sopenharmony_ci[[markup-macros-api-text]]
750e5c31af7Sopenharmony_ci==== When To Use *text: Macros
751e5c31af7Sopenharmony_ci
752e5c31af7Sopenharmony_ciOnly use the ftext{cl}, stext{cl}, etext{cl}, and ptext{cl} macros when
753e5c31af7Sopenharmony_cidescribing something that should be rendered like a command, structure,
754e5c31af7Sopenharmony_cienumerant, or parameter name, respectively, but is not actually one.
755e5c31af7Sopenharmony_ciTypically these macros are used for wildcards describing multiple API names
756e5c31af7Sopenharmony_ciwith common prefixes or suffixes, or common subsets of API names.
757e5c31af7Sopenharmony_ci
758e5c31af7Sopenharmony_ci
759e5c31af7Sopenharmony_ci[[markup-macros-prime-symbols]]
760e5c31af7Sopenharmony_ci==== Prime Symbols
761e5c31af7Sopenharmony_ci
762e5c31af7Sopenharmony_ciOccasionally we want to use mathematical prime symbols as markup in regular
763e5c31af7Sopenharmony_citext, outside of <<latexmath, LaTeX math markup>>.
764e5c31af7Sopenharmony_ciWhile it is easy to write the single quote character for this, since that is
765e5c31af7Sopenharmony_ciwhat LaTeX uses, asciidoctor will turn this into a curved quote character
766e5c31af7Sopenharmony_ciwhenever it is followed by an alphabetic character.
767e5c31af7Sopenharmony_ciFor example, when writing the {YCbCr} term widely used to describe a color
768e5c31af7Sopenharmony_ciencoding, the obvious markup does not look quite right:
769e5c31af7Sopenharmony_ci
770e5c31af7Sopenharmony_ci.Prime Attributes (incorrect, with curved prime symbol)
771e5c31af7Sopenharmony_ci[width="30%",options="header"]
772e5c31af7Sopenharmony_ci|====
773e5c31af7Sopenharmony_ci| Markup              | Output
774e5c31af7Sopenharmony_ci| `pass:[Y'C~b~C~r~]` | Y'C~b~C~r~
775e5c31af7Sopenharmony_ci|====
776e5c31af7Sopenharmony_ci
777e5c31af7Sopenharmony_ciUsing a backslash to escape the apostrophe works in body text, but not
778e5c31af7Sopenharmony_ciplaces such as section titles, captions, and link text.
779e5c31af7Sopenharmony_ciWhen prime symbols are needed, use the Unicode ``prime'' symbol.
780e5c31af7Sopenharmony_ciSeveral predefined asciidoctor variables are available to help with this,
781e5c31af7Sopenharmony_ciincluding symbols for {YCbCr} and {RGBprime} because they are frequently
782e5c31af7Sopenharmony_ciused in the specification.
783e5c31af7Sopenharmony_ci
784e5c31af7Sopenharmony_ci.Prime Attributes (correct)
785e5c31af7Sopenharmony_ci[width="30%",options="header"]
786e5c31af7Sopenharmony_ci|====
787e5c31af7Sopenharmony_ci| Markup              | Output
788e5c31af7Sopenharmony_ci| `pass:[{prime}]`    | {prime}
789e5c31af7Sopenharmony_ci| `pass:[{YCbCr}]`    | {YCbCr}
790e5c31af7Sopenharmony_ci| `pass:[{RGBprime}]` | {RGBprime}
791e5c31af7Sopenharmony_ci|====
792e5c31af7Sopenharmony_ci
793e5c31af7Sopenharmony_ci
794e5c31af7Sopenharmony_ci==== Other Markup
795e5c31af7Sopenharmony_ci
796e5c31af7Sopenharmony_ciUses of standard Asciidoc markup are less common.
797e5c31af7Sopenharmony_ciOccasional asterisk markup is used for *emphasis*.
798e5c31af7Sopenharmony_ciUnderscores are used for _glossary terms_.
799e5c31af7Sopenharmony_ciBacktick markup is used for the C `NULL` macro.
800e5c31af7Sopenharmony_ci
801e5c31af7Sopenharmony_ci[source,asciidoc]
802e5c31af7Sopenharmony_ci.Example Markup
803e5c31af7Sopenharmony_ci----
804e5c31af7Sopenharmony_ci*emphasis*
805e5c31af7Sopenharmony_ci`NULL`
806e5c31af7Sopenharmony_ci----
807e5c31af7Sopenharmony_ci
808e5c31af7Sopenharmony_ci
809e5c31af7Sopenharmony_ci==== Glossary Terms
810e5c31af7Sopenharmony_ci
811e5c31af7Sopenharmony_ciGlossary terms are currently marked up using underscore markup where they
812e5c31af7Sopenharmony_ciare defined in the documents, as well as being added to the formal Glossary
813e5c31af7Sopenharmony_ciappendix in the <<vulkan-spec,Vulkan API Specification>>.
814e5c31af7Sopenharmony_ciHowever, we will probably change to using custom macros soon, to enable
815e5c31af7Sopenharmony_cilinkage between the glossary and definitions in the specification body.
816e5c31af7Sopenharmony_ci
817e5c31af7Sopenharmony_ci[source,asciidoc]
818e5c31af7Sopenharmony_ci.Example Markup
819e5c31af7Sopenharmony_ci----
820e5c31af7Sopenharmony_ci_Glossary terms_
821e5c31af7Sopenharmony_ci----
822e5c31af7Sopenharmony_ci
823e5c31af7Sopenharmony_ci
824e5c31af7Sopenharmony_ci=== Normative Terminology
825e5c31af7Sopenharmony_ci
826e5c31af7Sopenharmony_ciNormative terminology is precisely defined in section 1.3 of the
827e5c31af7Sopenharmony_ci<<vulkan-spec,Vulkan API Specification>>, and is used to visually tag terms
828e5c31af7Sopenharmony_ciwhich express mandatory and optional behavior of Vulkan implementations, and
829e5c31af7Sopenharmony_ciof applications using Vulkan.
830e5c31af7Sopenharmony_ci
831e5c31af7Sopenharmony_ciWhenever one of these terms appears in the <<vulkan-spec,Vulkan API
832e5c31af7Sopenharmony_ciSpecification>> outside of an <<markup-informative,informative section>>, it
833e5c31af7Sopenharmony_cimust be tagged using the macros, to indicate that its use has been carefully
834e5c31af7Sopenharmony_ciconsidered and is consistent with the definitions in section 1.3.
835e5c31af7Sopenharmony_ciThis is extremely important for determining IP that is in and out of Scope
836e5c31af7Sopenharmony_ciduring Ratification reviews.
837e5c31af7Sopenharmony_ciThe normative terminology macros are defined in the following table:
838e5c31af7Sopenharmony_ci
839e5c31af7Sopenharmony_ci.Normative Terminology Macros
840e5c31af7Sopenharmony_ci[width="30%",options="header"]
841e5c31af7Sopenharmony_ci|====
842e5c31af7Sopenharmony_ci| Macro Name     | Output
843e5c31af7Sopenharmony_ci| can{cl}        | can:
844e5c31af7Sopenharmony_ci| cannot{cl}     | cannot:
845e5c31af7Sopenharmony_ci| may{cl}        | may:
846e5c31af7Sopenharmony_ci| may{cl} not    | may: not
847e5c31af7Sopenharmony_ci| must{cl}       | must:
848e5c31af7Sopenharmony_ci| must{cl} not   | must: not
849e5c31af7Sopenharmony_ci| optional{cl}   | optional:
850e5c31af7Sopenharmony_ci| optionally{cl} | optionally:
851e5c31af7Sopenharmony_ci| required{cl}   | required:
852e5c31af7Sopenharmony_ci| should{cl}     | should:
853e5c31af7Sopenharmony_ci| should{cl} not | should: not
854e5c31af7Sopenharmony_ci|====
855e5c31af7Sopenharmony_ci
856e5c31af7Sopenharmony_ciNote that the macros are lower-case only, so language should be written such
857e5c31af7Sopenharmony_cithat these terms do not appear at the beginning of a sentence (if really
858e5c31af7Sopenharmony_cinecessary, additional capitalized macros could be added).
859e5c31af7Sopenharmony_ci
860e5c31af7Sopenharmony_ci
861e5c31af7Sopenharmony_ci==== Optional Behavior
862e5c31af7Sopenharmony_ci
863e5c31af7Sopenharmony_ciIf a described behavior of the implementation is not necessary for
864e5c31af7Sopenharmony_ciconformance, use the terms _may{cl}_, _optional{cl}_, or _optionally{cl}_ to
865e5c31af7Sopenharmony_cidescribe it.
866e5c31af7Sopenharmony_ci
867e5c31af7Sopenharmony_ciIf a described usage pattern by the application is allowed but not
868e5c31af7Sopenharmony_cinecessary, use the term _can{cl}_ to describe it.
869e5c31af7Sopenharmony_ci
870e5c31af7Sopenharmony_ciIf language flows more logically using the term "`may not`", use the term
871e5c31af7Sopenharmony_ci_may{cl} not_ to describe it.
872e5c31af7Sopenharmony_ci
873e5c31af7Sopenharmony_ci
874e5c31af7Sopenharmony_ci==== Optional Functionality
875e5c31af7Sopenharmony_ci
876e5c31af7Sopenharmony_ciIf functionality (rather than behavior) is optional, it should be described
877e5c31af7Sopenharmony_cias
878e5c31af7Sopenharmony_ci
879e5c31af7Sopenharmony_ci[source,asciidoc]
880e5c31af7Sopenharmony_ci.Example Markup
881e5c31af7Sopenharmony_ci----
882e5c31af7Sopenharmony_cinot required:
883e5c31af7Sopenharmony_ci----
884e5c31af7Sopenharmony_ci
885e5c31af7Sopenharmony_ciImplementations are not mandated to support functionality which is not
886e5c31af7Sopenharmony_cirequired, but if they do, they must behave as described by the
887e5c31af7Sopenharmony_ci<<vulkan-spec,Vulkan API Specification>>.
888e5c31af7Sopenharmony_ciThe term _functionality_ includes API features, extensions, and layers.
889e5c31af7Sopenharmony_ci
890e5c31af7Sopenharmony_ci
891e5c31af7Sopenharmony_ci[[markup-informative]]
892e5c31af7Sopenharmony_ci== Informative, Editing and Implementor's Notes
893e5c31af7Sopenharmony_ci
894e5c31af7Sopenharmony_ciThere are several possible types of notes.
895e5c31af7Sopenharmony_ciDepending on the type of output, they are rendered in different styles, but
896e5c31af7Sopenharmony_cialways include a note title, and are usually set off in a box or with an
897e5c31af7Sopenharmony_ciicon.
898e5c31af7Sopenharmony_ciWhile asciidoctor supports a wide set of _admonition paragraphs_ such as
899e5c31af7Sopenharmony_ciTIP, IMPORTANT, WARNING, and CAUTION, we always use the NOTE form, augmented
900e5c31af7Sopenharmony_ciby a note title.
901e5c31af7Sopenharmony_ciEach type of note is discussed below.
902e5c31af7Sopenharmony_ci
903e5c31af7Sopenharmony_ci
904e5c31af7Sopenharmony_ci[[markup-informative-notes]]
905e5c31af7Sopenharmony_ci=== Informative Sections and Notes
906e5c31af7Sopenharmony_ci
907e5c31af7Sopenharmony_ciIf an entire chapter or section is considered informative, its title should
908e5c31af7Sopenharmony_cibe suffixed with "`(Informative)`".
909e5c31af7Sopenharmony_ciAdditionally, the chapter or section text may begin with the sentence:
910e5c31af7Sopenharmony_ci
911e5c31af7Sopenharmony_ci[source,asciidoc]
912e5c31af7Sopenharmony_ci.Example Markup
913e5c31af7Sopenharmony_ci----
914e5c31af7Sopenharmony_ci== Explanatory Section (Informative)
915e5c31af7Sopenharmony_ci
916e5c31af7Sopenharmony_ciThis chapter/section is Informative.
917e5c31af7Sopenharmony_ci----
918e5c31af7Sopenharmony_ci
919e5c31af7Sopenharmony_ciInformative notes always appear as part of the document, but are considered
920e5c31af7Sopenharmony_cinon-normative.
921e5c31af7Sopenharmony_ciThey usually describe usage advice for applications, and are always given
922e5c31af7Sopenharmony_cithe title _Note_, as in the following example:
923e5c31af7Sopenharmony_ci
924e5c31af7Sopenharmony_ci[NOTE]
925e5c31af7Sopenharmony_ci.Note
926e5c31af7Sopenharmony_ci====
927e5c31af7Sopenharmony_ciThis is an informative note.
928e5c31af7Sopenharmony_ci====
929e5c31af7Sopenharmony_ci
930e5c31af7Sopenharmony_ci[source,asciidoc]
931e5c31af7Sopenharmony_ci.Example Markup
932e5c31af7Sopenharmony_ci----
933e5c31af7Sopenharmony_ci[NOTE]
934e5c31af7Sopenharmony_ci.Note
935e5c31af7Sopenharmony_ci====
936e5c31af7Sopenharmony_ciThis is an informative note.
937e5c31af7Sopenharmony_ci====
938e5c31af7Sopenharmony_ci----
939e5c31af7Sopenharmony_ci
940e5c31af7Sopenharmony_ciIt is not necessary to include the text "`Informative`" in the body of the
941e5c31af7Sopenharmony_cinote.
942e5c31af7Sopenharmony_ci
943e5c31af7Sopenharmony_ci
944e5c31af7Sopenharmony_ci[[markup-editing-notes]]
945e5c31af7Sopenharmony_ci=== Editing Notes
946e5c31af7Sopenharmony_ci
947e5c31af7Sopenharmony_ciEditing notes usually only appear in internal (non-published) versions of
948e5c31af7Sopenharmony_cidocuments, via asciidoctor conditionals.
949e5c31af7Sopenharmony_ciIf they are not resolved, or are internal issues that should not be visible
950e5c31af7Sopenharmony_ciin public, they should be removed from the source before pushing content to
951e5c31af7Sopenharmony_cithe canonical GitHub repository.
952e5c31af7Sopenharmony_ciThey usually tag places where an outstanding Gitlab/GitHub issue is being
953e5c31af7Sopenharmony_ciworked, and are always given the title _editing-note_, as in the following
954e5c31af7Sopenharmony_ciexample:
955e5c31af7Sopenharmony_ci
956e5c31af7Sopenharmony_ciifdef::editing-notes[]
957e5c31af7Sopenharmony_ci[NOTE]
958e5c31af7Sopenharmony_ci.editing-note
959e5c31af7Sopenharmony_ci====
960e5c31af7Sopenharmony_ciThis is an editing note, marked up as follows:
961e5c31af7Sopenharmony_ci====
962e5c31af7Sopenharmony_ciendif::editing-notes[]
963e5c31af7Sopenharmony_ci
964e5c31af7Sopenharmony_ci[source,asciidoc]
965e5c31af7Sopenharmony_ci.Example Markup
966e5c31af7Sopenharmony_ci----
967e5c31af7Sopenharmony_ci\ifdef::editing-notes[]
968e5c31af7Sopenharmony_ci[NOTE]
969e5c31af7Sopenharmony_ci.editing-note
970e5c31af7Sopenharmony_ci====
971e5c31af7Sopenharmony_ciContents of an editing note go here.
972e5c31af7Sopenharmony_ciIt is good practice to include a Gitlab/GitHub issue number, or link to the
973e5c31af7Sopenharmony_ciissue, in the editing note.
974e5c31af7Sopenharmony_ci====
975e5c31af7Sopenharmony_ci\endif::editing-notes[]
976e5c31af7Sopenharmony_ci----
977e5c31af7Sopenharmony_ci
978e5c31af7Sopenharmony_ci
979e5c31af7Sopenharmony_ci[[markup-implementors-notes]]
980e5c31af7Sopenharmony_ci=== Implementor's Notes
981e5c31af7Sopenharmony_ci
982e5c31af7Sopenharmony_ciImplementor's notes may or may not appear in published versions of
983e5c31af7Sopenharmony_cidocuments, via asciidoctor conditionals.
984e5c31af7Sopenharmony_ciThey describe suggested approaches or guidelines for people writing Vulkan
985e5c31af7Sopenharmony_ciimplementations, and are rare because the hardware being targeted varies so
986e5c31af7Sopenharmony_ciwidely.
987e5c31af7Sopenharmony_ciThey are always given the title _Implementor's Note_, as in the following
988e5c31af7Sopenharmony_ciexample:
989e5c31af7Sopenharmony_ci
990e5c31af7Sopenharmony_ciifdef::implementation-guide[]
991e5c31af7Sopenharmony_ci.Implementor's Note
992e5c31af7Sopenharmony_ci====
993e5c31af7Sopenharmony_ciThis is an implementor's note, marked up as follows:
994e5c31af7Sopenharmony_ci====
995e5c31af7Sopenharmony_ciendif::implementation-guide[]
996e5c31af7Sopenharmony_ci
997e5c31af7Sopenharmony_ci[source,asciidoc]
998e5c31af7Sopenharmony_ci.Example Markup
999e5c31af7Sopenharmony_ci----
1000e5c31af7Sopenharmony_ci\ifdef::implementation-guide[]
1001e5c31af7Sopenharmony_ci.Implementor's Note
1002e5c31af7Sopenharmony_ci====
1003e5c31af7Sopenharmony_ciContents of an implementor's note go here.
1004e5c31af7Sopenharmony_ci====
1005e5c31af7Sopenharmony_ci\endif::implementation-guide[]
1006e5c31af7Sopenharmony_ci----
1007e5c31af7Sopenharmony_ci
1008e5c31af7Sopenharmony_ci
1009e5c31af7Sopenharmony_ci[[markup-word-choices]]
1010e5c31af7Sopenharmony_ci== Word Choices
1011e5c31af7Sopenharmony_ci
1012e5c31af7Sopenharmony_ciThere are a variety of common terms that have several equivalent word
1013e5c31af7Sopenharmony_cichoices.
1014e5c31af7Sopenharmony_ciAlways use the words or phrases in the first column instead of the alternate
1015e5c31af7Sopenharmony_citerms.
1016e5c31af7Sopenharmony_ciThis list may not be comprehensive; when in doubt, be guided by the existing
1017e5c31af7Sopenharmony_ci<<vulkan-spec,Vulkan API Specification>>.
1018e5c31af7Sopenharmony_ci
1019e5c31af7Sopenharmony_ci.Word Choices
1020e5c31af7Sopenharmony_ci[width="100%",options="header"]
1021e5c31af7Sopenharmony_ci|====
1022e5c31af7Sopenharmony_ci| Use This      | Instead Of     | Comments
1023e5c31af7Sopenharmony_ci| allocate      | create
1024e5c31af7Sopenharmony_ci                | When describing objects or memory resulting from
1025e5c31af7Sopenharmony_ci                  ftext:vkAllocate* commands.
1026e5c31af7Sopenharmony_ci| application   | client / user  |
1027e5c31af7Sopenharmony_ci| bitmask       | bit field
1028e5c31af7Sopenharmony_ci                | Technically correct. Vulkan bitmasks are just integers and
1029e5c31af7Sopenharmony_ci                  are not logically addressable at the bit level.
1030e5c31af7Sopenharmony_ci| bound         | currently bound
1031e5c31af7Sopenharmony_ci                | Appears primarily in valid usage statements, which are
1032e5c31af7Sopenharmony_ci                  always referring to the current state of the objects
1033e5c31af7Sopenharmony_ci                  they are validating.
1034e5c31af7Sopenharmony_ci                  Rare exceptions may be justified in other cases.
1035e5c31af7Sopenharmony_ci| command       | function
1036e5c31af7Sopenharmony_ci                | Except when talking about function pointers returned by
1037e5c31af7Sopenharmony_ci                  ftext:vkGet*ProcAddr commands.
1038e5c31af7Sopenharmony_ci| create        | allocate
1039e5c31af7Sopenharmony_ci                | When describing objects resulting from ftext:vkCreate*
1040e5c31af7Sopenharmony_ci                  commands.
1041e5c31af7Sopenharmony_ci| depth/stencil | packed (interleaved, combined, _other prefix_)
1042e5c31af7Sopenharmony_ci                  depth/stencil, depth-stencil, DepthStencil, etc.
1043e5c31af7Sopenharmony_ci                | Combined format implicit in the name.
1044e5c31af7Sopenharmony_ci| device        | GPU / processor / accelerator
1045e5c31af7Sopenharmony_ci                | The Vulkan specification is functional and could be
1046e5c31af7Sopenharmony_ci                  implemented in many different ways.
1047e5c31af7Sopenharmony_ci| dispatching command, +
1048e5c31af7Sopenharmony_ci  drawing command
1049e5c31af7Sopenharmony_ci                | dispatch command,
1050e5c31af7Sopenharmony_ci                  draw command   | Glossary usage
1051e5c31af7Sopenharmony_ci| executable memory +
1052e5c31af7Sopenharmony_ci  executable state +
1053e5c31af7Sopenharmony_ci  pipeline executable
1054e5c31af7Sopenharmony_ci                | executable     | Disambiguation
1055e5c31af7Sopenharmony_ci| heterogeneous | heterogenous   | More common
1056e5c31af7Sopenharmony_ci| homogeneous   | homogenous     | More common
1057e5c31af7Sopenharmony_ci| host          | CPU |
1058e5c31af7Sopenharmony_ci| host endianness | platform endianness |
1059e5c31af7Sopenharmony_ci| image subresource | subresource
1060e5c31af7Sopenharmony_ci                | Except when referring to *host-accessible subresources*
1061e5c31af7Sopenharmony_ci| implementation| system / hardware / software
1062e5c31af7Sopenharmony_ci                | For consistency, and avoids implied requirements.
1063e5c31af7Sopenharmony_ci| implementor   | implementer    | For consistency with historical specification practice
1064e5c31af7Sopenharmony_ci| indices       | indexes        | More common
1065e5c31af7Sopenharmony_ci| member        | field          |
1066e5c31af7Sopenharmony_ci| runtime       | run time / run-time | Arbitrary choice for consistency
1067e5c31af7Sopenharmony_ci| ename:enumerant specifies
1068e5c31af7Sopenharmony_ci                | ename:enumerant indicates (denotes)
1069e5c31af7Sopenharmony_ci                | When giving a brief description of enums in an enumerated
1070e5c31af7Sopenharmony_ci                  type.
1071e5c31af7Sopenharmony_ci                  It is often appropriate to use "`enumerant *is*`" when
1072e5c31af7Sopenharmony_ci                  describing the behavior or meaning of enumerants in other
1073e5c31af7Sopenharmony_ci                  places.
1074e5c31af7Sopenharmony_ci| pname:parameter are/is
1075e5c31af7Sopenharmony_ci                | pname:parameter specifies (denotes, indicates)
1076e5c31af7Sopenharmony_ci                | In cases when _are_ or _if_ are not grammatically
1077e5c31af7Sopenharmony_ci                  appropriate, _specifies_ may be used instead.
1078e5c31af7Sopenharmony_ci| pname:parameter is
1079e5c31af7Sopenharmony_ci                | the value of pname:parameter is
1080e5c31af7Sopenharmony_ci                | In rare cases, _the value of_ is appropriate. See the
1081e5c31af7Sopenharmony_ci                  existing specification language for examples.
1082e5c31af7Sopenharmony_ci| pname:parameter is a _typename_ containing / controlling / defining /
1083e5c31af7Sopenharmony_ci  describing / specifying / etc.
1084e5c31af7Sopenharmony_ci                | pname:parameter is a _typename_ that/which contains
1085e5c31af7Sopenharmony_ci                  (controls, defines, describes, specifies, etc.)
1086e5c31af7Sopenharmony_ci                | Commonly used for more nuanced descriptions of parameters
1087e5c31af7Sopenharmony_ci                  or structure members
1088e5c31af7Sopenharmony_ci| reference monitor   | mastering display|
1089e5c31af7Sopenharmony_ci| begins / begun      | starts / started | For ftext:vkBegin* - also see "`finish`"
1090e5c31af7Sopenharmony_ci| finishes / finished | ends / ended     | For ftext:vkEnd* - also see "`begins`"
1091e5c31af7Sopenharmony_ci| used          | referenced     | When describing attachments specified in a
1092e5c31af7Sopenharmony_ci                                   subpass description.
1093e5c31af7Sopenharmony_ci| statically used | referenced   | When describing resources or push constants
1094e5c31af7Sopenharmony_ci                                   accessed by shader code
1095e5c31af7Sopenharmony_ci| a more specific term | referenced | For all other situations.
1096e5c31af7Sopenharmony_ci| component     | channel        | Specifically this refers to color channels/components
1097e5c31af7Sopenharmony_ci|====
1098e5c31af7Sopenharmony_ci
1099e5c31af7Sopenharmony_ci[NOTE]
1100e5c31af7Sopenharmony_ci.Note
1101e5c31af7Sopenharmony_ci====
1102e5c31af7Sopenharmony_ciThe "`begin/start`" and "`end/finish`" distinction is still being sorted
1103e5c31af7Sopenharmony_ciout.
1104e5c31af7Sopenharmony_ciSee Gitlab issue #61.
1105e5c31af7Sopenharmony_ci====
1106e5c31af7Sopenharmony_ci
1107e5c31af7Sopenharmony_ci
1108e5c31af7Sopenharmony_ci[[markup-avoid-contractions]]
1109e5c31af7Sopenharmony_ci=== Avoid Abbreviations and Contractions
1110e5c31af7Sopenharmony_ci
1111e5c31af7Sopenharmony_ciAbbreviations and contractions make the specification sound less formal.
1112e5c31af7Sopenharmony_ciAvoid using them in specification text.
1113e5c31af7Sopenharmony_ciThe following lists provides some guidance, but are not complete.
1114e5c31af7Sopenharmony_ci
1115e5c31af7Sopenharmony_ci.Word Choices (Contractions)
1116e5c31af7Sopenharmony_ci[width="30%",options="header"]
1117e5c31af7Sopenharmony_ci|====
1118e5c31af7Sopenharmony_ci| Use This      | Instead Of
1119e5c31af7Sopenharmony_ci| are not       | aren't
1120e5c31af7Sopenharmony_ci| cannot{cl}    | can't
1121e5c31af7Sopenharmony_ci| does not      | doesn't
1122e5c31af7Sopenharmony_ci| do not        | don't
1123e5c31af7Sopenharmony_ci| has not       | hasn't
1124e5c31af7Sopenharmony_ci| is not        | isn't
1125e5c31af7Sopenharmony_ci| it is         | it's
1126e5c31af7Sopenharmony_ci| should not    | shouldn't
1127e5c31af7Sopenharmony_ci| that is       | that's
1128e5c31af7Sopenharmony_ci| there is      | there's
1129e5c31af7Sopenharmony_ci| we are        | we're
1130e5c31af7Sopenharmony_ci| we will       | we'll
1131e5c31af7Sopenharmony_ci| we would      | we'd
1132e5c31af7Sopenharmony_ci| what is       | what's
1133e5c31af7Sopenharmony_ci| will not      | won't
1134e5c31af7Sopenharmony_ci| would not     | wouldn't
1135e5c31af7Sopenharmony_ci|====
1136e5c31af7Sopenharmony_ci
1137e5c31af7Sopenharmony_ci.Word Choices (Abbreviations)
1138e5c31af7Sopenharmony_ci[width="30%",options="header"]
1139e5c31af7Sopenharmony_ci|====
1140e5c31af7Sopenharmony_ci| Use This      | Instead Of
1141e5c31af7Sopenharmony_ci| information   | info
1142e5c31af7Sopenharmony_ci| specification | spec
1143e5c31af7Sopenharmony_ci|====
1144e5c31af7Sopenharmony_ci
1145e5c31af7Sopenharmony_ci[NOTE]
1146e5c31af7Sopenharmony_ci.Note
1147e5c31af7Sopenharmony_ci====
1148e5c31af7Sopenharmony_ciAvoid using abbreviations in specification text describing the API, even
1149e5c31af7Sopenharmony_cithough there are certain <<naming-abbreviations, approved abbreviations>>
1150e5c31af7Sopenharmony_ciused in the names of API entities such as commands, structures, and
1151e5c31af7Sopenharmony_cienumerants.
1152e5c31af7Sopenharmony_ci====
1153e5c31af7Sopenharmony_ci
1154e5c31af7Sopenharmony_ci
1155e5c31af7Sopenharmony_ci[[markup-terms-caution]]
1156e5c31af7Sopenharmony_ci=== Terms to Use With Caution
1157e5c31af7Sopenharmony_ci
1158e5c31af7Sopenharmony_ciThe term _subset_ is sometimes used to refer to a _strict subset_, and
1159e5c31af7Sopenharmony_cisometimes used to refer to a subset which may be equal to the entire set.
1160e5c31af7Sopenharmony_ciThis is particularly likely to come up when describing bitmasks.
1161e5c31af7Sopenharmony_ciMake sure to use either _subset_ or _strict subset_ as appropriate.
1162e5c31af7Sopenharmony_ci
1163e5c31af7Sopenharmony_ci
1164e5c31af7Sopenharmony_ci[[markup-terms-avoid]]
1165e5c31af7Sopenharmony_ci=== Terms to Avoid
1166e5c31af7Sopenharmony_ci
1167e5c31af7Sopenharmony_ciDo not describe anything in the documentation using vague or wishy-washy
1168e5c31af7Sopenharmony_citerms.
1169e5c31af7Sopenharmony_ciOur goal is to precisely describe behavior of implementations.
1170e5c31af7Sopenharmony_ci
1171e5c31af7Sopenharmony_ciThe normative terms may{cl}, optional{cl}, and should{cl} are available when
1172e5c31af7Sopenharmony_ciimplementations may make choices of behavior, but when such choices are
1173e5c31af7Sopenharmony_ciallowed, each choice still must have well-defined behavior.
1174e5c31af7Sopenharmony_ci
1175e5c31af7Sopenharmony_ci.Terms to Avoid
1176e5c31af7Sopenharmony_ci[width="100%",options="header"]
1177e5c31af7Sopenharmony_ci|====
1178e5c31af7Sopenharmony_ci| Bad Term | Comments
1179e5c31af7Sopenharmony_ci| expect   | And variants such as _expected_
1180e5c31af7Sopenharmony_ci| likely   | And variants such as _will likely_
1181e5c31af7Sopenharmony_ci| allowed, could, generally, might, probably, perhaps
1182e5c31af7Sopenharmony_ci           | And all other such terms of choice. Use _may{cl}_ or _can{cl}_
1183e5c31af7Sopenharmony_ci             depending on the context.
1184e5c31af7Sopenharmony_ci| may{cl} or may{cl} not   | Just use _may{cl}_.
1185e5c31af7Sopenharmony_ci|====
1186