Vulkan-Docs/doc/specs/vulkan/style/writing.txt

[[writing]]
= Writing Style


[[writing-misc]]
== Miscellaneous Grammar, Spelling, and Punctuation Issues

=== Use the Oxford Comma (Serial Comma)

When writing a sentence listing a series of items, include a comma before
the ``and'' separating the last item.

*Correct:* The red, green, blue, and alpha components.

*Incorrect:* The red, green, blue and alpha components.

Also see http://blog.oxforddictionaries.com/2011/06/oxford-comma/

=== Numbers in Text

When describing the need for a small number of objects, smaller than ten, spell
the number out (e.g. ``one''). If you are describing a literal value that is a
small number, you may use a numeric value (e.g. ``1'').

For example, instead of writing that a bitmask ``contains 1 or more bits'',
write that it ``contains one or more bits''. A counter example is that it is okay
to write ``For non-stereoscopic-3D applications, this value is 1.''


=== Use American Spelling Conventions

In case of conflict, use American rather than British spelling
conventions. For example:

*Correct:* color, signaled.

*Incorrect:* colour, signalled.


[[writing-describing]]
== Describing Commands and Parameters

The <<Vulkan API Specification>>
describes API commands followed by descriptions of their
parameters, which are usually simple scalar types, handles or pointers to
Vulkan objects or arrays of objects, or structures containing combinations
of scalar types and objects. The templates and examples shown and annotated
here are based on the <<Vulkan API Specification>>. Do not vary from them without
compelling need.

Normative parts of the <<Vulkan API Specification>> should describe _what_ something does,
rather than _how_ or _why_ an application would want to use it.

[NOTE]
.Guideline
====
As a simple example, say

``To create a command pool, call fname:vkCreateCommandPool''

rather than

``You/The application/The user can create a command pool by calling
fname:vkCreateCommandPool''.

====

Explanations of _why_ and _how_ should largely be confined to reference
documentation, sample code, tutorials, and other such documents. Occasional
non-normative explanations can be included in the <<Vulkan API Specification>>
using <<markup-informative-notes,informative notes>>.


[[writing-latexmath]]
== LaTeX Math Markup

There is a considerable amount of math in the documentation, ranging from
simple arithmetic expressions to complicated conditionals. For the most
part, math is marked up using LaTeX math notation, which is either passed
through to the Mathjax browser renderer for HTML outputs, or passed through
to LaTeX for PDF outputs. For some very simple math expressions, asciidoc
markup can be used.

[NOTE]
.Note
====
We still do not have the latexmath vs. asciidoc font situation sorted out
for all target output forms, so there can be some visual inconsistencies.
====

While LaTeX math macros, including the amsmath package, are supported,
general LaTeX constructs are not.

_Inline math_ is encoded using the latexmath{cl} macro. For example:

  * latexmath:[$[0,1\]$]
  * latexmath:[$x \cdot 0 = 0 \cdot x = 0$]
  * latexmath:[${\textbf c} = t {\textbf c}_1 + (1-t){\textbf c}_2. $]

.Example Markup
----
    latexmath:[$[0,1\]$]
    latexmath:[$x \cdot 0 = 0 \cdot x = 0$]
    latexmath:[${\textbf c} = t {\textbf c}_1 + (1-t){\textbf c}_2. $]
----

Note the escaped bracket in markup for the first expression, which is
necessary to work around asciidoc macro parsing:


_Block math_ is used for more complex equations. This example uses the
amsmath `align*` macros to delimit the expression:

[latexmath]
+++++++++++++++++++
\begin{align*}
c_{RGB} & =
  \begin{cases}
    \frac{c_{sRGB}}{12.92}                              & \textrm{for } c_{sRGB} \leq 0.04045 \\
    \left ( \frac{c_{sRGB}+0.055}{1.055} \right )^{2.4} & \textrm{for } c_{sRGB} > 0.04045
  \end{cases}
\end{align*}
+++++++++++++++++++

.Example Markup
----
[latexmath]
+++++++++++++++++++
\begin{align*}
c_{RGB} & =
  \begin{cases}
    \frac{c_{sRGB}}{12.92}                              & \textrm{for } c_{sRGB} \leq 0.04045 \\
    \left ( \frac{c_{sRGB}+0.055}{1.055} \right )^{2.4} & \textrm{for } c_{sRGB} > 0.04045
  \end{cases}
\end{align*}
+++++++++++++++++++
----

This example uses normal LaTeX math brackets to delimit the expression:

[latexmath]
+++++++++++++++++++
\[
V =
  \begin{cases}
    (-1)^S \times 0.0,                      & E = 0, M = 0     \\
    (-1)^S \times 2^{-14} \times { M \over 2^{10} },
                                            & E = 0,  M \neq 0 \\
    (-1)^S \times 2^{E-15} \times { \left( 1 + { M \over 2^{10} } \right) },
                                            & 0 < E < 31       \\
    (-1)^S \times Inf,             & E = 31, M = 0             \\
    NaN,                           & E = 31, M \neq 0
  \end{cases}
\]
+++++++++++++++++++

.Example Markup
----
[latexmath]
+++++++++++++++++++
\[
V =
  \begin{cases}
    (-1)^S \times 0.0,                      & E = 0, M = 0     \\
    (-1)^S \times 2^{-14} \times { M \over 2^{10} },
                                            & E = 0,  M \neq 0 \\
    (-1)^S \times 2^{E-15} \times { \left( 1 + { M \over 2^{10} } \right) },
                                            & 0 < E < 31       \\
    (-1)^S \times Inf,             & E = 31, M = 0             \\
    NaN,                           & E = 31, M \neq 0
  \end{cases}
\]
+++++++++++++++++++
----


[[writing-example]]
== An Example Command Description

The <<sample-command,next section>> is a sample based on the <<Vulkan API Specification>>,
and describes a command in enough detail to see the different usage patterns
and layout / markup used. Informative notes discussing markup and guidelines
are interspersed with the example description to explain how and why it
looks as it does.


[[sample-command]]
== Sample Command Description: Creating Command Pools

// refBegin vkCreateCommandPool Create a new command pool object.

To create a command pool, call:

include::../api/protos/vkCreateCommandPool.txt[]

[NOTE]
.Guideline
====
Begin the command description with a comment delimiting the language for
<<writing-refpages,automatic extraction into a reference page>>.

Use a short, active sentence when describing what commands do, instead of
more passive phrasing like ``A command pool is created by calling:'' or ``The
application may create a command pool by calling:''.

After the description, include the autogenerated prototype for the
command from the `../protos/` directory:

    // refBegin vkCreateCommandPool Create a new command pool object.

    To create a command pool, call:

    include::../api/protos/vkCreateCommandPool.txt[]

Note that each autogenerated command, enumeration, flag, or structure
definition include file also defines a corresponding asciidoc anchor which
is the base name of the file. In this case, the anchor is named
`vkCreateCommandPool`.
====

  * pname:device is the logical device that the command pool is created on.
  * pname:pCreateInfo points to an instance of the
    slink:VkCommandPoolCreateInfo structure containing information used to
    create the command pool.
  * pname:pAllocator controls host memory allocation as described in the
    <<memory-allocation, Memory Allocation>> chapter.
  * pname:pCommandPool points to a handle in which the created command pool
    object is returned.

[NOTE]
.Guideline
====
Each command parameter is described in a separate bullet list entry,
followed by validity rules, then detailed descriptions of any new
structures, flags, or enumerations introduced by this command.

Each parameter should appear as a separate bullet list item beginning with
the parameter name, in the same order as parameters appear in the command.
This aids in extracting short descriptions of parameters for inclusion in
annotated headers and similar documentation. Make sure to tag each parameter
with the pname{cl} macro.

Strive for compact notation, and in particular always try to use the
phrasing ``pname{cl}param _is_'' rather than wordier forms such as
``pname{cl}param _specifies_'' or ``The pname{cl}param parameter specifies''. In
general there is no need to describe a parameter which is a Vulkan object
handle *as* a handle; for example, say ``pname{cl}device is the logical
device'' rather than ``pname{cl}device is a handle to the logical device''. An
exception is object creation functions, where a pointer to a handle of the
proper type is used to return the newly created object.
====

include::../validity/protos/vkCreateCommandPool.txt[]

[NOTE]
.Guideline
====
Parameter and member validation language for commands and structures is also
autogenerated from vk.xml, and included from the `../validity/` directories:

    include::../validity/protos/vkCreateCommandPool.txt[]

Structures and enumerations first used as parameters of a command are
described next.
====

// refBegin VkCommandPoolCreateInfo - Structure specifying parameters of a newly created command pool

The sname:VkCommandPoolCreateInfo structure is defined as:

include::../api/structs/VkCommandPoolCreateInfo.txt[]

[NOTE]
.Guideline
====
Begin the structure description with a comment delimiting the language for
<<writing-refpages,automatic extraction into a reference page>>.

Use a short, active paragraph to introduce the structure, usually just
``The sname:VkStructureName structure is defined as:''.

After the description, include the autogenerated definition for the
structure from the `../structs/` directory:

    // refBegin VkCommandPoolCreateInfo - Structure specifying parameters of a newly created command pool

    The sname:VkCommandPoolCreateInfo structure is defined as:

    include::../api/structs/VkCommandPoolCreateInfo.txt[]
====

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to an extension-specific structure.
  * pname:flags is a combination of bitmask flags indicating usage behavior
    for the pool and command buffers allocated from it. Possible values
    include:
+
--
// refBegin VkCommandPoolCreateFlagBits - Bitmask specifying usage behavior for a command pool
include::../api/enums/VkCommandPoolCreateFlagBits.txt[]
--
+
  ** ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT indicates that command buffers
     allocated from the pool will be short-lived.
  ** ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT controls whether
     command buffers allocated from the pool can: be individually reset.
  * pname:queueFamilyIndex designates a queue family. Command buffers in
    this command pool must: be submitted on queues from the same family.

[NOTE]
.Guideline
====
Each structure member is described in a separate bullet list entry. For the
stext:Vk*CreateInfo structures in particular, there is standard boilerplate
for the pname:sType and pname:pNext members, followed by the members
specific to the structure.

----
  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to an extension-specific structure.
----

In some cases, such as when the type of a member is itself a new type, the
entry will cover multiple paragraphs. In these cases the normal list nesting
and indentation guidelines cannot be applied due to limitations of the
asciidoc parser. It is usually best to append a block following the first
paragraph of such a list item:

----
  * pname:flags is a bitmask indicating usage behavior for the pool and
    command buffers allocated from it. Bits which can: be set include:
+
--
// refBegin VkCommandPoolCreateFlagBits - Bitmask specifying usage behavior for a command pool
include::../api/enums/VkCommandPoolCreateFlagBits.txt[]
--
+
  ** ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT
     indicates that command buffers allocated
     from the pool will be short-lived.
  ** ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT
     controls whether command buffers allocated from
     the pool can: be individually reset.
--
----
====

include::../validity/structs/VkCommandPoolCreateInfo.txt[]

[NOTE]
.Guideline
====
Following the definition of structure members, include the validity language
for this structure:

    include::../validity/structs/VkCommandPoolCreateInfo.txt[]
====


[[writing-refpages]]
== Markup For Automatic Reference Page Extraction

The Vulkan reference pages are (mostly) being extracted from
corresponding sections of the API Specification. This requires that the
markup and writing conventions described above be adhered to rigidly.

The extraction scripts for a given page rely on the existence of the
asciidoc +include+ of the autogenerated definition of that command,
structure, or other API interface element. Various heuristics are used
to determine which text to extract for that page; the general model is:

  * Optional (but usually specified) comment line specifying the
    interface name and the short description used in the title of the
    corresponding ref page:
+
----
    // refBegin name - description
----
+
  * A paragraph of text introducing the definition of the interface. If
    the +refBegin+ comment does not exist, this paragraph must be
    present.
  * The +include+ line for the interface, which must be consistent
    with the interface name in the comment line.
  * A bullet list describing function parameters, structure members,
    enumerants in an enumerated type, etc. This list should contain no
    empty lines, as the extraction script classifies the uninterrupted
    block of text following the +include+ directive as the +Parameters+
    or +Members+ section of the ref page.
  * Optional paragraphs of text making up the +Description+ section of
    the ref page.
  * The +include+ line for the validity statement of commands and
    structures. Other interfaces such as enumerated types do not have
    validity statements.
  * Comment line specifying the end of the extracted text for the
    reference page and optional page names to link to in the +See Also+
    section of the page. If the validity +include+ is not present, this
    line must be present:
+
----
    // refEnd name [seeAlsoNames]*
----

All elements specifying an interface name (+refBegin+ and +refEnd+
comments, interface +include+ line, and validity +include+ line) must
use the same interface name, if present. Otherwise the extraction script
is either unable to extract that page, or will extract the wrong text.
The extraction process is somewhat fragile, so care should be taken and
the results of reference page extraction verified after making changes
to that portion of the specification source.