xref: /device/generic/vulkan-cereal/protocols/vulkan/style/markup.txt

// Copyright 2015-2021 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[[markup]]
= Markup Style

This chapter demonstrates Asciidoc and Specification structure, including
text layout and markup style.


[[markup-copyrights]]
== Copyrights and Licenses

The asciidoctor source for the Vulkan Specification and related documents is
under an open source license.

When creating a *new* file, add the following copyright and license
statement at the top:

[source,asciidoc]
.Example Markup
----
// Copyright YEAR AUTHOR
// SPDX-License-Identifier: CC-BY-4.0

----

`YEAR` should be replaced by the year in which the file was created.

`AUTHOR` is normally "`The Khronos Group Inc.`".
If a new file is created by a member company or outside contributor, use
that entity's legal name as the author.

`SPDX-License-Identifier` gives the license used for the file, following the
https://spdx.github.io/spdx-spec/appendix-V-using-SPDX-short-identifiers-in-source-files/[SPDX]
standard for short identifiers in source files.
`CC-BY-4.0` is the short identifier for the
https://spdx.org/licenses/CC-BY-4.0.html[Creative Commons Attribution 4.0
International] license.

No matter who holds the *copyright* on a source file for the Specification,
it must be placed under the `CC-BY-4.0` *license*.
When contributing to the Specification, contributors are required to execute
a Contributor License Agreement to this effect.

When updating an *existing* file, modify the following copyright and license
statement to include the year(s) of modification.
For example:

[source,asciidoc]
.Example Markup
----
// Copyright 2018-2021 The Khronos Group Inc.
// SPDX-License-Identifier: CC-BY-4.0

----

indicates a file which has been been modified in 2018, 2019, and 2020
inclusive.


[[markup-structure]]
== Document Structure

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 link:{docguide}/sections/titles-and-levels/[one line title] 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 asciidoctor delimiters.
Using a mix of one-line and two-line titles causes compatibility issues, and
using the two-line title form may implicitly set a backwards-compatibility
syntax mode we do not want.

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 asciidoctor markup).

UTF-8 characters outside the ASCII subset should be used sparingly, only
when needed for non-English names.
Instead use asciidoctor 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}` asciidoctor 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.

The trailing `+` character causes a hard break in asciidoctor markup, and
should not be used except for this purpose.
Markup addition with the \{plus} asciidoctor attribute, except in
<<writing-math-latexmath, LaTeX math>> and <<markup-blocks, source blocks>>.

See the Asciidoctor docs for
link:{docguide}/subs/special-characters[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 asciidoctor markup may result in lines that
  are longer than 76 characters and cannot easily be shortened without
  compromising the output documents.


[[markup-minimize-indentation]]
=== Minimize Indentation

Indentation (leading whitespace) for markup should not be used, except for
<<markup-sample-section-bullet-lists, bullet lists>> as described below.
Leading whitespace can affect asciidoctor processing.

When presenting unformatted text, use asciidoctor source blocks as described
in the next section.
Source blocks do allow leading whitespace, for example when including sample
code in C.


[[markup-blocks]]
=== Blocks

There are a variety of asciidoctor _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
| Listing (alt.)| `pass:[~~~~]` | For source code listings <<markup-blocks-source, imbedded in Open blocks>>
| Sidebar       | `pass:[****]` | For <<markup-implementors-notes,implementor's notes>>
| Table         | `\|====`      | For <<markup-sample-section-tables,tables>>
| Quote         | `pass:[____]` |
| Literal       | `pass:[....]` |
|====


[[markup-blocks-source]]
==== Listing Blocks Imbedded in Open Blocks

If you need to include a `source` block that would normally use `----`
delimiters inside an open block delimiting a reference page, use
`pass:[~~~~]` delimiters around the inner source block instead.
This avoids confusing some of the toolchain which makes assumptions about
block delimiters not being nested, such as the VUID assignment script.
Tildes are not standard asciidoctor markup, but are supported by a custom
Ruby extension.


[[markup-footnotes]]
=== Footnotes

Use manually marked-up footnotes (the asciidoctor 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 asciidoctor 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 asciidoctor 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 is 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 asciidoctor 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 asciidoctor 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
asciidoctor 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.
This directory is referred to as `\{images}` so that there's a consistent
path no matter what directory the file including the images is in.
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-indentation-equations]]
=== Indentation of Equations

Asciidoctor separates structural markup in asciidoctor source from
formatting, in HTML CSS stylesheets and invoked via asciidoctor "`role`"
attributes on blocks.
However, the flexibility of CSS stylesheets is not available in PDF layout
using the existing PDF toolchain and YML stylesheets.

Explicit indentation should be used sparingly in the specification, but one
place it is useful is with equations.
Using <<writing-math, asciidoctor math markup>>, the easiest way to produce
indentation is with a list where the leading bullet or descriptive text is
suppressed

[source,asciidoc]
.Example Markup
----
[none]
  * A {plus} B

or

  {empty}:: A {plus} B
----

->

[example]
====
[none]
  * A {plus} B

or

  {empty}:: A {plus} B
====


[[markup-italicized-enumerant-names]]
=== Italicized Enumerant Names

When writing a "`wildcard`" enumerant name containing an italicized term
within it, it's difficult to directly combine constrained formatting markup
(double underscores) and the single underscores that separate words in the
enumerant.
Instead, use attribute substitution as suggested in the "`Escape
unconstrained formatting marks`" section of the AsciiDoc Language
Documentation.
To help when this is required, an attribute `\{ibit}` expanding to
`pass:[_i_]` is defined in `config/attribs.txt`, and the same technique can
be used for similar markup in other cases if `_i_` is not the desired
italicized term:

[source,asciidoc]
.Example Markup
----
`VK_IMAGE_ASPECT_PLANE__{ibit}__BIT`
----

->

[example]
====
`VK_IMAGE_ASPECT_PLANE__{ibit}__BIT`
====

[NOTE]
.Note
====
This technique cannot be used with the <<markup-macros, markup macros>> that
are normally used to semantically tag API names.
Because there are so few places it's needed, conventional backquote
formatting markup is used instead.
====


[[markup-macros]]
== Markup Macros and Normative Terminology

This section discusses Asciidoc macros used in the document.
In addition to the macros defined by asciidoctor 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 (note that these examples will not actually successfully link into
corresponding specification or reference pages, since they are in an
unrelated document).

.API Markup Macros
[width="100%",options="header",cols="20%,80%"]
|====
| Macro Name    | Usage and Meaning
| reflink{cl}   | Generates a cross-reference or link to an unknown type of
                  API entity. This is only used in generated content in the
                  reference pages which refers to other reference pages
                  which are not actually part of the API. Example:
                  reflink{cl}WSIheaders -> reflink:WSIheaders.
| pass:c[`apiext:`] | Generates a cross-reference or link to the description
                  of an extension. Example: pass:c[`apiext:VK_KHR_ray_tracing_pipeline`]
                  -> `apiext:VK_KHR_ray_tracing_pipeline`.
| 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.
                  Note that this is not related to elink{cl}, unlike the
                  other macro link{cl}/text{cl} pairings.
| 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 and `Vk*Flags`
                  types at present, although it is a potentially a catch-all
                  for other types not covered by a more specific macro.
| 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,
                  handle name, of type defined by an external API. Not
                  validated.
                  Examples: basetype{cl}VkBool32 -> basetype:VkBool32,
                  basetype{cl}AHardwareBuffer -> basetype:AHardwareBuffer,
                  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.
                  code{cl}OpImage*Gather -> code:OpImage*Gather.

                  This macro allows imbedded field member (`.`) and wildcard
                  (`*`) text separating words, ending with an optional
                  wildcard.
|====

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.
When a nested member within the compound name is referred to, use normal C
markup:

[source,asciidoc]
.Example Markup
----
flink:vkCmdBindIndexBuffer::pname:indexType
sname:VkExternalImageFormatProperties::pname:externalMemoryProperties.externalMemoryFeatures
pname:pAllocateInfo->memoryTypeIndex
----

[NOTE]
.Note
====
In the macros, "```\->```" is correct markup for the C arrow operator.
But in any other context (including a "```````" delimited inline literal) it
would be subject to link:{docguide}/subs/replacements/[Asciidoctor character
replacement substitutions], resulting in a unicode arrow: ->.
====


[[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 `\{generated}/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 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.


[[markup-macros-prime-symbols]]
==== Prime Symbols

Occasionally we want to use mathematical prime symbols as markup in regular
text, outside of <<latexmath, LaTeX math markup>>.
While it is easy to write the single quote character for this, since that's
what LaTeX uses, asciidoctor will turn this into a curved quote character
whenever it is followed by an alphabetic character.
For example, when writing the {YCbCr} term widely used to describe a color
encoding, the obvious markup does not look quite right:

.Prime Attributes (incorrect, with curved prime symbol)
[width="30%",options="header"]
|====
| Markup              | Output
| `pass:[Y'C~b~C~r~]` | Y'C~b~C~r~
|====

Using a backslash to escape the apostrophe works in body text, but not
places such as section titles, captions, and link text.
When prime symbols are needed, use the Unicode ``prime'' symbol.
Several predefined asciidoctor variables are available to help with this,
including symbols for {YCbCr} and {RGBprime} because they are frequently
used in the specification.

.Prime Attributes (correct)
[width="30%",options="header"]
|====
| Markup              | Output
| `pass:[{prime}]`    | {prime}
| `pass:[{YCbCr}]`    | {YCbCr}
| `pass:[{RGBprime}]` | {RGBprime}
|====


==== 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 specification 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}_, _optional{cl}_, or _optionally{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 asciidoctor 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 Sections and Notes

If an entire chapter or section is considered informative, its title should
be suffixed with "`(Informative)`".
Additionally, the chapter or section text may begin with the sentence:

[source,asciidoc]
.Example Markup
----
== Explanatory Section (Informative)

This chapter/section is Informative.
----

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.
====
----

It is not necessary to include the text "`Informative`" in the body of the
note.


[[markup-editing-notes]]
=== Editing Notes

Editing notes usually only appear in internal (non-published) versions of
documents, via asciidoctor 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 asciidoctor 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 / user  |
| 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.
| dispatching command, +
  drawing command
                | dispatch command,
                  draw command   | Glossary usage
| executable memory +
  executable state +
  pipeline executable
                | executable     | Disambiguation
| 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.
| implementor   | implementer    | For consistency with historical specification practice
| indices       | indexes        | More common
| member        | field          |
| runtime       | run time / run-time | Arbitrary choice for consistency
| 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.
| pname:parameter is a _typename_ containing / controlling / defining /
  describing / specifying / etc.
                | pname:parameter is a _typename_ that/which contains
                  (controls, defines, describes, specifies, etc.)
                | Commonly used for more nuanced descriptions of parameters
                  or structure members
| reference monitor   | mastering display|
| 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 Abbreviations and Contractions

Abbreviations and contractions make the specification sound less formal.
Avoid using them in specification text.
The following lists provides some guidance, but are not complete.

.Word Choices (Contractions)
[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
| should not    | shouldn't
| that is       | that's
| there is      | there's
| we are        | we're
| we will       | we'll
| we would      | we'd
| what is       | what's
| will not      | won't
| would not     | wouldn't
|====

.Word Choices (Abbreviations)
[width="30%",options="header"]
|====
| Use This      | Instead Of
| information   | info
| specification | spec
|====

[NOTE]
.Note
====
Avoid using abbreviations in specification text describing the API, even
though there are certain <<naming-abbreviations, approved abbreviations>>
used in the names of API entities such as commands, structures, and
enumerants.
====


[[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}_.
|====