889 lines
30 KiB
Plaintext
889 lines
30 KiB
Plaintext
// Copyright (c) 2015-2019 Khronos Group. This work is licensed under a
|
||
// Creative Commons Attribution 4.0 International License; see
|
||
// http://creativecommons.org/licenses/by/4.0/
|
||
|
||
[[markup]]
|
||
= Markup Style
|
||
|
||
This chapter demonstrates Asciidoc and Specification structure, including
|
||
text layout and markup style.
|
||
|
||
Chapters and sections follow a rigid template consisting of an optional
|
||
anchor (if other parts of the document cross-reference the section) followed
|
||
by a one line title (see
|
||
http://asciidoctor.org/docs/user-manual/#sections[section 19 of the
|
||
Asciidoctor User Manual]) and a blank line.
|
||
The anchor is typically the base name of the file containing the chapter,
|
||
with a lowercased version of the section name following, with spaces
|
||
replaced by dashes.
|
||
|
||
Always use the one-line title form, with one to four = signs preceding the
|
||
chapter/section title.
|
||
The two-line title form cannot be easily searched for and often looks like
|
||
other types of asciidoc delimiters.
|
||
Using a mix of one-line and two-line titles causes compatibility issues, and
|
||
using the two-line title form
|
||
http://asciidoctor.org/docs/user-manual/#changed-syntax[implicitly sets
|
||
syntax compatibility mode].
|
||
|
||
Always precede the anchor by two blank lines (except at the beginning of a
|
||
file), and follow the title by a blank line, to set off sections visibly.
|
||
|
||
[source,asciidoc]
|
||
.Example Markup
|
||
----
|
||
[[markup]]
|
||
= Markup Style
|
||
|
||
|
||
[[markup-sample-section]]
|
||
== Sample Section
|
||
----
|
||
|
||
|
||
[[markup-sample-section]]
|
||
== Sample Section
|
||
|
||
This is a sample section structurally similar to the <<vulkan-spec,Vulkan
|
||
API Specification>>, nested one level inside a chapter.
|
||
Sections can be nested up to level 5, although not all levels are included
|
||
in the Table of Contents.
|
||
|
||
|
||
[[markup-layout]]
|
||
== Asciidoc Markup And Text Layout
|
||
|
||
Asciidoc source should be text filled to 76 columns with hard line breaks.
|
||
Each sentence in a paragraph ends with a newline to minimize git diff
|
||
conflicts.
|
||
Except when necessary for lists or other markup, text should begin at the
|
||
first column of each line (leading spaces are often semantically meaningful
|
||
in asciidoc markup).
|
||
|
||
UTF-8 characters outside the ASCII subset should be used sparingly, only
|
||
when needed for non-English names.
|
||
Instead use asciidoc markup for special characters, if required.
|
||
For example, two hyphens produces an em-dash:
|
||
|
||
[NOTE]
|
||
.Example Markup
|
||
====
|
||
|
||
`An -- em-dash` -> An -- em-dash
|
||
====
|
||
|
||
As an exception, multiplication should be marked with the unicode
|
||
multiplication symbol "`×`" (and *not* an asterisk) when used in plain text.
|
||
You may also use the `{times}` asciidoc attribute for this symbol.
|
||
In math sections, the same symbol should be referred to as `\times`.
|
||
In code sections, a conventional asterisk (`*`) should be used instead.
|
||
|
||
See http://asciidoctor.org/docs/user-manual/#special-characters[section 40
|
||
of the Asciidoctor User Manual] for supported special characters, as well as
|
||
use of entity references.
|
||
|
||
Quotation marks should use the 66/99 convention.
|
||
That is, double asymmetric quotation marks, indicated by a quotation mark
|
||
then a backtick as opening marks, and a backtick then quotation mark as
|
||
closing marks (pass:["`like this`"]), which renders "`like this`".
|
||
|
||
_Never_ use hard tabs or trailing blanks.
|
||
|
||
* In some cases, limitations of asciidoc markup may result in lines that are
|
||
longer than 76 characters and cannot easily be shortened without
|
||
compromising the output documents.
|
||
|
||
|
||
[[markup-blocks]]
|
||
=== Blocks
|
||
|
||
There are a variety of asciidoc _block_ constructs.
|
||
With the exception of <<markup-sample-section-tables,tables>> and of _open
|
||
blocks_ used to group markup together, blocks should be delimited by exactly
|
||
four repeated characters indicating the block type, for consistency.
|
||
The block types and delimiters are shown in the following table.
|
||
|
||
.Asciidoc Block Delimiters
|
||
[width="70%",options="header",cols="25%,10%,65%"]
|
||
|====
|
||
| Table Type | Delimiter | Comments
|
||
| Open | `--` | For <<markup-sample-section-bullet-lists,continuation blocks>>
|
||
| Example | `====` | For <<markup-informative-notes,Notes>>
|
||
| Passthrough | pass:[++++] | For some kinds of <<writing-math,math markup>>
|
||
| Comment | //// |
|
||
| Listing | ---- | For source code listings
|
||
| Sidebar | pass:[****] | For <<markup-implementors-notes,implementor's notes>>
|
||
| Table | `\|====` | For <<markup-sample-section-tables,tables>>
|
||
| Quote | pass:[____] | Currently unused in the Vulkan Specification
|
||
| Literal | .... | Currently unused in the Vulkan Specification
|
||
|====
|
||
|
||
|
||
[[markup-footnotes]]
|
||
=== Footnotes
|
||
|
||
Use manually marked-up footnotes (the asciidoc footnote construct is OK for
|
||
PDF outputs, but does not work well with long HTML documents since it places
|
||
all footnotes at the end of the document).
|
||
|
||
Refer to footnotes with asciidoc superscript notation^1^, and mark up the
|
||
footnotes below, but near the references as labelled lists.
|
||
Manually assigned footnote numbers will inevitably be reused, which is OK as
|
||
long as the colliding numbers are not in the same section.
|
||
|
||
1::
|
||
Like this example footnote.
|
||
|
||
[NOTE]
|
||
====
|
||
.Example Markup
|
||
[source,asciidoc]
|
||
----
|
||
See reference^2^
|
||
|
||
2::
|
||
Reference 2.
|
||
----
|
||
|
||
->
|
||
|
||
See reference^2^
|
||
|
||
2::
|
||
Reference 2.
|
||
====
|
||
|
||
[[markup-sample-section-lists]]
|
||
=== Lists
|
||
|
||
[[markup-sample-section-bullet-lists]]
|
||
==== Bullet Lists and Continuation Blocks
|
||
|
||
* Bullet lists are the preferred form of list, aside from glossary
|
||
definitions.
|
||
* Lists should have text indented by 4 spaces and the list item delimiter
|
||
(e.g. one or more asterisks, for bullet lists) indented by two spaces.
|
||
+
|
||
Note that continuation blocks for list items longer than one paragraph
|
||
cannot be indented, only the first paragraph.
|
||
+
|
||
In general, successive list items should not be separated by white space.
|
||
However, list continuation blocks should be followed by a `+` on a line by
|
||
itself, or by a blank line, due to limitations of the asciidoc parser.
|
||
+
|
||
* Indent bullet lists two spaces (to the bullet), 4 spaces (to the text,
|
||
if it extends over multiple lines).
|
||
This lets us visually distinguish lists from other kinds of markup.
|
||
** Nested lists should align the leftmost list item delimiter (bullet,
|
||
etc.) with the parent delimiter.
|
||
|
||
[source,asciidoc]
|
||
.Example Markup
|
||
----
|
||
* This is the first item in a bullet list.
|
||
* The second item is described with two paragraphs.
|
||
The second paragraph is in a continuation block:
|
||
+
|
||
This is a continuation block containing the second paragraph,
|
||
+
|
||
** This is a nested list item for the second item.
|
||
Since it follows a continuation block, it must be separated by a blank
|
||
line or `+` from that block.
|
||
----
|
||
|
||
[example]
|
||
====
|
||
* This is the first item in a bullet list.
|
||
* The second item is described with two paragraphs.
|
||
The second paragraph is in a continuation block:
|
||
+
|
||
This is a continuation block containing the second paragraph,
|
||
+
|
||
** This is a nested list item for the second item.
|
||
Since it follows a continuation block, it must be separated by a blank
|
||
line or `+` from that block.
|
||
====
|
||
|
||
* It's possible to continue a paragraph of the first bullet after a list
|
||
of sub-bullets if so desired by using continuations in a similar
|
||
fashion:
|
||
|
||
[source,asciidoc]
|
||
.Example Markup
|
||
----
|
||
* This an item in a bullet list.
|
||
+
|
||
** This is a nested list item for the second item.
|
||
Since it follows a continuation block, it must be separated by a blank
|
||
line or `+` from that block.
|
||
+
|
||
This is a continuation of the first bullet
|
||
----
|
||
|
||
[example]
|
||
====
|
||
* This an item in a bullet list.
|
||
+
|
||
** This is a nested list item for the second item.
|
||
Since it follows a continuation block, it must be separated by a blank
|
||
line or `+` from that block.
|
||
+
|
||
This is a continuation of the first bullet
|
||
====
|
||
|
||
[[markup-labelled-lists]]
|
||
==== Labelled Lists
|
||
|
||
Labelled lists may be used in some cases such as
|
||
<<markup-footnotes,footnotes>>; glossary entries; and long lists of
|
||
information about similar names, such as the "`Features, Limits, and
|
||
Formats`" chapter of the Vulkan Specification.
|
||
Whenever labelled lists are used the label and its terminating double colon
|
||
must be alone on a line, followed by the contents of that list entry.
|
||
|
||
For consistency do not use labels ending in three or four colons, or two
|
||
semicolons, even though these forms are allowed in asciidoc markup.
|
||
|
||
[source,asciidoc]
|
||
.Example Markup
|
||
----
|
||
Glossary Entry::
|
||
This is a glossary entry.
|
||
|
||
Last Modified Date::
|
||
2016-02-16
|
||
----
|
||
|
||
|
||
[[markup-numbered-lists]]
|
||
==== Numbered Lists
|
||
|
||
Numbered lists may be used if strictly necessary to place an ordering on
|
||
list items.
|
||
Always use _implicit numbering_, with the bullet point being a single
|
||
period.
|
||
|
||
. Explicit numbering with a number preceding the period is prone to
|
||
accumulating errors as edits are made.
|
||
. In addition, the markup is harder to recognize for scripts and tools
|
||
(other than asciidoc itself) operating on the document source.
|
||
|
||
[source,asciidoc]
|
||
.Example Markup
|
||
----
|
||
. First list item.
|
||
. Second list item.
|
||
. Etc.
|
||
----
|
||
|
||
|
||
[[markup-sample-section-anchors]]
|
||
=== Anchors and Cross-references
|
||
|
||
In general, chapters and sections should always have anchors, following the
|
||
naming convention <<markup,discussed above>>.
|
||
Anchors to other sections of the document may be inserted as needed.
|
||
In addition, the autogenerated include files defining commands, structures,
|
||
enumerations and flags all define anchors whose name is the name of the
|
||
command or type being defined, so it is easy to link to a (for example) a
|
||
command name such as <<vkCreateCommandPool,vkCreateCommandPool>>.
|
||
However, using the <<markup-macros,markup macros>> described below is
|
||
preferred when linking to anchors corresponding to API names, such as
|
||
flink:vkCreateCommandPool.
|
||
|
||
If you want a cross-reference to an anchor to appear as something other than
|
||
the raw anchor name, always make sure to include that text as part of the
|
||
cross-reference.
|
||
There are several different toolchains followed for various forms of
|
||
asciidoc output, and not all of them treat anchors without alt-text the same
|
||
way.
|
||
|
||
[source,asciidoc]
|
||
.Example Markup
|
||
----
|
||
In general, chapters and sections should always have anchors, following the
|
||
naming convention <<markup,discussed above>>.
|
||
...
|
||
so it is easy to link to a (for example) a command name such as
|
||
<<vkCreateCommandPool,vkCreateCommandPool>>. However, using the
|
||
<<markup-macros,markup macros>> described below is preferred when linking to
|
||
anchors corresponding to API names, such as flink:vkCreateCommandPool.
|
||
----
|
||
|
||
|
||
[[markup-sample-section-tables]]
|
||
=== Tables
|
||
|
||
Asciidoc tables should use the block prefix `|====`.
|
||
Where feasible, align the `|` separating cells across rows.
|
||
This will sometimes result in very wide tables in the source document, but
|
||
makes it easier to see which cells belong to which column.
|
||
Alternatively, long cells can be broken onto a separate line with the `|`
|
||
separator appearing first, except for the first row of the table, which must
|
||
all appear on a single line.
|
||
|
||
Tables should usually be preceded with a short title.
|
||
|
||
[source,asciidoc]
|
||
.Example Markup
|
||
----
|
||
.Normative Terminology Macros
|
||
[width="100%",options="header"]
|
||
|====
|
||
| Macro Name | Output
|
||
| can{cl} | can:
|
||
| cannot{cl} | cannot:
|
||
|====
|
||
----
|
||
|
||
|
||
[[markup-sample-section-images]]
|
||
=== Figures
|
||
|
||
All figures (images) must be marked up as follows, to ensure there is an
|
||
anchor and that the figure is given a caption which shows the figure number
|
||
and is added to the list of figures:
|
||
|
||
[source,asciidoc]
|
||
.Example Markup
|
||
----
|
||
[[fig-anchorname]]
|
||
image::images/imagename.svg[align="center",title="Figure caption",opts="{imageopts}"]
|
||
----
|
||
|
||
There must be SVG versions of each figure checked into the `images/`
|
||
directory, to support generating both HTML and PDF outputs.
|
||
The PDF generation pipeline is now able to use SVG images, so PDF versions
|
||
of each image are no longer required.
|
||
The `opts=` attribute defaults to `inline`, which decreases output image
|
||
size in the generated HTML.
|
||
However, the `inline` option interferes with generating HTML diffs between
|
||
two specifications with the script we currently use.
|
||
By using an asciidoctor attribute, this behavior can be controlled.
|
||
|
||
Asciidoctor restricts captions in figures to be a single line in the source
|
||
document.
|
||
If a longer caption is required, follow the figure directive with a sidebar
|
||
block including the full caption preceded by a link to the figure:
|
||
|
||
[source,asciidoc]
|
||
.Example Markup
|
||
----
|
||
.Caption
|
||
****
|
||
In the <<fig-anchorname,Figure caption>> diagram, the diagram represents
|
||
... long caption text here.
|
||
****
|
||
----
|
||
|
||
|
||
[[markup-macros]]
|
||
== Markup Macros and Normative Terminology
|
||
|
||
This section discusses Asciidoc macros used in the document.
|
||
In addition to the macros defined by asciidoc itself, additional macros are
|
||
defined by the <<vulkan-spec,Vulkan API Specification>> and Reference Page
|
||
configuration files.
|
||
|
||
|
||
[[markup-macros-api]]
|
||
=== API Markup Macros
|
||
|
||
These macros must be used to tag command, structure, enumeration, enumerant,
|
||
and other Vulkan-specific names so they can be rendered in a distinctive
|
||
fashion, link to definitions of those names, and be easily searched for in
|
||
the source documents.
|
||
The validation scripts (`make allchecks` output) also rely on these macros
|
||
being used consistently and correctly.
|
||
The API markup macros, with examples of their use, are in the following
|
||
table:
|
||
|
||
.API Markup Macros
|
||
[width="100%",options="header",cols="20%,80%"]
|
||
|====
|
||
| Macro Name | Usage and Meaning
|
||
| flink{cl} | Generates a cross-reference or link to the definition of
|
||
the command name in the macro argument. Example:
|
||
flink{cl}vkCreateCommandPool -> flink:vkCreateCommandPool.
|
||
| fname{cl} | Formats the macro argument like flink{cl}. Does not
|
||
generate a cross-reference. Example:
|
||
fname{cl}vkCreateCommandPool -> fname:vkCreateCommandPool.
|
||
|
||
Only use this macro <<markup-macros-api-name, when
|
||
necessary>>.
|
||
| ftext{cl} | Formats the macro argument like fname{cl}. May contain
|
||
asterisks for wildcards. Not validated. Example:
|
||
ftext{cl}vkCmd* -> ftext:vkCmd*.
|
||
|
||
Only use this macro <<markup-macros-api-text, when
|
||
necessary>>.
|
||
| slink{cl} | Generates a cross-reference or link to the definition
|
||
of the structure or handle in the macro argument. Example:
|
||
slink{cl}VkMemoryHeap -> slink:VkMemoryHeap.
|
||
| sname{cl} | Formats the macro argument like slink{cl}. Does not
|
||
generate a cross-reference. May also be an abstract
|
||
structure or handle name. Example:
|
||
sname{cl}VkCommandPoolCreateInfo ->
|
||
sname:VkCommandPoolCreateInfo.
|
||
|
||
Only use this macro <<markup-macros-api-name, when
|
||
necessary>>.
|
||
| stext{cl} | Formats the macro argument like sname{cl}. May contain
|
||
asterisks for wildcards. Not validated. Example:
|
||
stext{cl}Vk*CreateInfo -> stext:Vk*CreateInfo.
|
||
|
||
Only use this macro <<markup-macros-api-text, when
|
||
necessary>>.
|
||
| elink{cl} | Formats the macro argument as a Vulkan enumerated
|
||
type name and links to the definition of that enumeration
|
||
type. Example: elink{cl}VkResult -> elink:VkResult.
|
||
| ename{cl} | Formats the macro argument as a Vulkan enumerant name.
|
||
Example: ename{cl}VK_EVENT_SET -> ename:VK_EVENT_SET.
|
||
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
|
||
or API handle name. Not validated. Examples:
|
||
basetype{cl}VkBool32 -> basetype:VkBool32,
|
||
basetype{cl}VkDeviceSize -> basetype:VkDeviceSize.
|
||
| code{cl} | Formats the macro argument as a code sample.
|
||
Used for SPIR-V keywords, builtin C types, and names
|
||
belonging to other APIs such as Linux or Windows system
|
||
calls.
|
||
Examples: code{cl}uint32_t -> code:uint32_t,
|
||
code{cl}ClipDistance -> code:ClipDistance.
|
||
|====
|
||
|
||
When referring to a compound name (function-parameter, or structure-member),
|
||
combine the macros separated by two colons, resulting in
|
||
flink:vkCmdBindIndexBuffer::pname:indexType and
|
||
slink:VkMemoryHeap::pname:flags.
|
||
This is often done when referring to a particular parameter or member in a
|
||
part of the document other than the description of the corresponding
|
||
function or structure.
|
||
|
||
[source,asciidoc]
|
||
.Example Markup
|
||
----
|
||
flink:vkCmdBindIndexBuffer::pname:indexType
|
||
slink:VkMemoryHeap::pname:flags
|
||
----
|
||
|
||
|
||
[[markup-macros-api-name]]
|
||
==== When To Use *name: Macros
|
||
|
||
Only use the fname{cl}, sname{cl}, tname{cl}, and dname{cl} macros if no
|
||
definition of the target type with a corresponding anchor exists in the
|
||
document.
|
||
Anchors are automatically defined when including the generated API interface
|
||
definitions under `api/.../*txt`.
|
||
If an anchor does exist, use the corresponding *link{cl} macro.
|
||
|
||
[NOTE]
|
||
.Note
|
||
====
|
||
There are many legacy uses of the *name{cl} macros that will be replaced
|
||
over time.
|
||
These uses date from before anchors were added to the generated API
|
||
definitions.
|
||
====
|
||
|
||
|
||
[[markup-macros-api-text]]
|
||
==== When To Use *text: Macros
|
||
|
||
Only use the ftext{cl}, stext{cl}, etext{cl}, and ptext{cl} macros when
|
||
describing something that should be rendered like a command, structure,
|
||
enumerant, or parameter name, respectively, but is not actually one.
|
||
Typically these macros are used for wildcards describing multiple API names
|
||
with common prefixes or suffixes, or common subsets of API names.
|
||
|
||
|
||
==== Other Markup
|
||
|
||
Uses of standard Asciidoc markup are less common.
|
||
Occasional asterisk markup is used for *emphasis*.
|
||
Underscores are used for _glossary terms_.
|
||
Backtick markup is used for the C `NULL` macro.
|
||
|
||
[source,asciidoc]
|
||
.Example Markup
|
||
----
|
||
*emphasis*
|
||
`NULL`
|
||
----
|
||
|
||
|
||
==== Glossary Terms
|
||
|
||
Glossary terms are currently marked up using underscore markup where they
|
||
are defined in the documents, as well as being added to the formal Glossary
|
||
appendix in the <<vulkan-spec,Vulkan API Specification>>.
|
||
However, we will probably change to using custom macros soon, to enable
|
||
linkage between the glossary and definitions in the spec body.
|
||
|
||
[source,asciidoc]
|
||
.Example Markup
|
||
----
|
||
_Glossary terms_
|
||
----
|
||
|
||
|
||
=== Normative Terminology
|
||
|
||
Normative terminology is precisely defined in section 1.3 of the
|
||
<<vulkan-spec,Vulkan API Specification>>, and is used to visually tag terms
|
||
which express mandatory and optional behavior of Vulkan implementations, and
|
||
of applications using Vulkan.
|
||
|
||
Whenever one of these terms appears in the <<vulkan-spec,Vulkan API
|
||
Specification>> outside of an <<markup-informative,informative section>>, it
|
||
must be tagged using the macros, to indicate that its use has been carefully
|
||
considered and is consistent with the definitions in section 1.3.
|
||
This is extremely important for determining IP that is in and out of Scope
|
||
during Ratification reviews.
|
||
The normative terminology macros are defined in the following table:
|
||
|
||
.Normative Terminology Macros
|
||
[width="30%",options="header"]
|
||
|====
|
||
| Macro Name | Output
|
||
| can{cl} | can:
|
||
| cannot{cl} | cannot:
|
||
| may{cl} | may:
|
||
| may{cl} not | may: not
|
||
| must{cl} | must:
|
||
| must{cl} not | must: not
|
||
| optional{cl} | optional:
|
||
| optionally{cl} | optionally:
|
||
| required{cl} | required:
|
||
| should{cl} | should:
|
||
| should{cl} not | should: not
|
||
|====
|
||
|
||
Note that the macros are lower-case only, so language should be written such
|
||
that these terms do not appear at the beginning of a sentence (if really
|
||
necessary, additional capitalized macros could be added).
|
||
|
||
|
||
==== Optional Behavior
|
||
|
||
If a described behavior of the implementation is not necessary for
|
||
conformance, use the terms _may{cl}_ or _optional{cl}_ to describe it.
|
||
|
||
If a described usage pattern by the application is allowed but not
|
||
necessary, use the term _can{cl}_ to describe it.
|
||
|
||
If language flows more logically using the term "may not", use the term
|
||
_may{cl} not_ to describe it.
|
||
|
||
|
||
==== Optional Functionality
|
||
|
||
If functionality (rather than behavior) is optional, it should be described
|
||
as
|
||
|
||
[source,asciidoc]
|
||
.Example Markup
|
||
----
|
||
not required:
|
||
----
|
||
|
||
Implementations are not mandated to support functionality which is not
|
||
required, but if they do, they must behave as described by the
|
||
<<vulkan-spec,Vulkan API Specification>>.
|
||
The term _functionality_ includes API features, extensions, and layers.
|
||
|
||
|
||
[[markup-informative]]
|
||
== Informative, Editing and Implementor's Notes
|
||
|
||
There are several possible types of notes.
|
||
Depending on the type of output, they are rendered in different styles, but
|
||
always include a note title, and are usually set off in a box or with an
|
||
icon.
|
||
While asciidoc supports a wide set of _admonition paragraphs_ such as TIP,
|
||
IMPORTANT, WARNING, and CAUTION, we always use the NOTE form, augmented by a
|
||
note title.
|
||
Each type of note is discussed below.
|
||
|
||
|
||
[[markup-informative-notes]]
|
||
=== Informative Notes
|
||
|
||
Informative notes always appear as part of the document, but are considered
|
||
non-normative.
|
||
They usually describe usage advice for applications, and are always given
|
||
the title _Note_, as in the following example:
|
||
|
||
[NOTE]
|
||
.Note
|
||
====
|
||
This is an informative note.
|
||
====
|
||
|
||
[source,asciidoc]
|
||
.Example Markup
|
||
----
|
||
[NOTE]
|
||
.Note
|
||
====
|
||
This is an informative note.
|
||
====
|
||
----
|
||
|
||
If an entire chapter or section is considered informative, it should begin
|
||
with the sentence:
|
||
|
||
[source,asciidoc]
|
||
.Example Markup
|
||
----
|
||
This chapter/section is Informative.
|
||
----
|
||
|
||
|
||
[[markup-editing-notes]]
|
||
=== Editing Notes
|
||
|
||
Editing notes usually only appear in internal (non-published) versions of
|
||
documents, via asciidoc conditionals.
|
||
If they are not resolved, or are internal issues that should not be visible
|
||
in public, they should be removed from the source before pushing content to
|
||
the canonical GitHub repository.
|
||
They usually tag places where an outstanding Gitlab/GitHub issue is being
|
||
worked, and are always given the title _editing-note_, as in the following
|
||
example:
|
||
|
||
ifdef::editing-notes[]
|
||
[NOTE]
|
||
.editing-note
|
||
====
|
||
This is an editing note, marked up as follows:
|
||
====
|
||
endif::editing-notes[]
|
||
|
||
[source,asciidoc]
|
||
.Example Markup
|
||
----
|
||
\ifdef::editing-notes[]
|
||
[NOTE]
|
||
.editing-note
|
||
====
|
||
Contents of an editing note go here.
|
||
It is good practice to include a Gitlab/GitHub issue number, or link to the
|
||
issue, in the editing note.
|
||
====
|
||
\endif::editing-notes[]
|
||
----
|
||
|
||
|
||
[[markup-implementors-notes]]
|
||
=== Implementor's Notes
|
||
|
||
Implementor's notes may or may not appear in published versions of
|
||
documents, via asciidoc conditionals.
|
||
They describe suggested approaches or guidelines for people writing Vulkan
|
||
implementations, and are rare because the hardware being targeted varies so
|
||
widely.
|
||
They are always given the title _Implementor's Note_, as in the following
|
||
example:
|
||
|
||
ifdef::implementation-guide[]
|
||
.Implementor's Note
|
||
====
|
||
This is an implementor's note, marked up as follows:
|
||
====
|
||
endif::implementation-guide[]
|
||
|
||
[source,asciidoc]
|
||
.Example Markup
|
||
----
|
||
\ifdef::implementation-guide[]
|
||
.Implementor's Note
|
||
====
|
||
Contents of an implementor's note go here.
|
||
====
|
||
\endif::implementation-guide[]
|
||
----
|
||
|
||
|
||
[[markup-word-choices]]
|
||
== Word Choices
|
||
|
||
There are a variety of common terms that have several equivalent word
|
||
choices.
|
||
Always use the words or phrases in the first column instead of the alternate
|
||
terms.
|
||
This list may not be comprehensive; when in doubt, be guided by the existing
|
||
<<vulkan-spec,Vulkan API Specification>>.
|
||
|
||
.Word Choices
|
||
[width="100%",options="header"]
|
||
|====
|
||
| Use This | Instead Of | Comments
|
||
| allocate | create
|
||
| When describing objects or memory resulting from
|
||
ftext:vkAllocate* commands.
|
||
| application | client |
|
||
| bitmask | bit field
|
||
| Technically correct. Vulkan bitmasks are just integers and
|
||
are not logically addressable at the bit level.
|
||
| bound | currently bound
|
||
| Appears primarily in valid usage statements, which are
|
||
always referring to the current state of the objects
|
||
they are validating.
|
||
Rare exceptions may be justified in other cases.
|
||
| command | function
|
||
| Except when talking about function pointers returned by
|
||
ftext:vkGet*ProcAddr commands.
|
||
| create | allocate
|
||
| When describing objects resulting from ftext:vkCreate*
|
||
commands.
|
||
| depth/stencil | packed (interleaved, combined, _other prefix_)
|
||
depth/stencil, depth-stencil, DepthStencil, etc.
|
||
| Combined format implicit in the name.
|
||
| device | GPU / processor / accelerator
|
||
| The Vulkan specification is functional and could be
|
||
implemented in many different ways.
|
||
| heterogeneous | heterogenous | More common
|
||
| homogeneous | homogenous | More common
|
||
| host | CPU |
|
||
| host endianness | platform endianness |
|
||
| image subresource | subresource
|
||
| Except when referring to *host-accessible subresources*
|
||
| implementation| system / hardware / software
|
||
| For consistency, and avoids implied requirements.
|
||
| indices | indexes | More common
|
||
| member | field |
|
||
| ename:enumerant specifies
|
||
| ename:enumerant indicates (denotes)
|
||
| When giving a brief description of enums in an enumerated
|
||
type.
|
||
It is often appropriate to use "`enumerant *is*`" when
|
||
describing the behavior or meaning of enumerants in other
|
||
places.
|
||
| pname:parameter are/is
|
||
| pname:parameter specifies (denotes, indicates)
|
||
| In cases when _are_ or _if_ are not grammatically
|
||
appropriate, _specifies_ may be used instead.
|
||
| pname:parameter is
|
||
| the value of pname:parameter is
|
||
| In rare cases, _the value of_ is appropriate. See the
|
||
existing specification language for examples.
|
||
| begins / begun | starts / started | For ftext:vkBegin* - also see "`finish`"
|
||
| finishes / finished | ends / ended | For ftext:vkEnd* - also see "`begins`"
|
||
| used | referenced | When describing attachments specified in a
|
||
subpass description.
|
||
| statically used | referenced | When describing resources or push constants
|
||
accessed by shader code
|
||
| a more specific term | referenced | For all other situations.
|
||
| component | channel | Specifically this refers to color channels/components
|
||
|====
|
||
|
||
[NOTE]
|
||
.Note
|
||
====
|
||
The "`begin/start`" and "`end/finish`" distinction is still being sorted
|
||
out.
|
||
See Gitlab issue #61.
|
||
====
|
||
|
||
|
||
[[markup-avoid-contractions]]
|
||
=== Avoid Contractions
|
||
|
||
Contractions make the specification sound less formal and using them would
|
||
be inconsistent with the many non-contraction forms already in use in the
|
||
spec.
|
||
|
||
.Word Choices
|
||
[width="30%",options="header"]
|
||
|====
|
||
| Use This | Instead Of
|
||
| are not | aren't
|
||
| cannot{cl} | can't
|
||
| does not | doesn't
|
||
| do not | don't
|
||
| has not | hasn't
|
||
| is not | isn't
|
||
| it is | it's
|
||
| that is | that's
|
||
| there is | there's
|
||
| we are | we're
|
||
| will not | won't
|
||
|====
|
||
|
||
|
||
[[markup-terms-caution]]
|
||
=== Terms to Use With Caution
|
||
|
||
The term _subset_ is sometimes used to refer to a _strict subset_, and
|
||
sometimes used to refer to a subset which may be equal to the entire set.
|
||
This is particularly likely to come up when describing bitmasks.
|
||
Make sure to use either _subset_ or _strict subset_ as appropriate.
|
||
|
||
|
||
[[markup-terms-avoid]]
|
||
=== Terms to Avoid
|
||
|
||
Do not describe anything in the documentation using vague or wishy-washy
|
||
terms.
|
||
Our goal is to precisely describe behavior of implementations.
|
||
|
||
The normative terms may{cl}, optional{cl}, and should{cl} are available when
|
||
implementations may make choices of behavior, but when such choices are
|
||
allowed, each choice still must have well-defined behavior.
|
||
|
||
.Terms to Avoid
|
||
[width="100%",options="header"]
|
||
|====
|
||
| Bad Term | Comments
|
||
| expect | And variants such as _expected_
|
||
| likely | And variants such as _will likely_
|
||
| allowed, could, generally, might, probably, perhaps
|
||
| And all other such terms of choice. Use _may{cl}_ or _can{cl}_
|
||
depending on the context.
|
||
| may{cl} or may{cl} not | Just use _may{cl}_.
|
||
|====
|