[[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 <> 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 <>. Do not vary from them without compelling need. Normative parts of the <> 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 <> using <>. [[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 <> is a sample based on the <>, 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 To create a command pool, call: [NOTE] .Guideline ==== 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:''. ==== include::../api/protos/vkCreateCommandPool.txt[] [NOTE] .Guideline ==== After the description, include the autogenerated prototype for the command from the `../protos/` directory: 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 <> 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[] ==== The sname:VkCommandPoolCreateInfo structure is defined as: include::../api/structs/VkCommandPoolCreateInfo.txt[] [NOTE] .Guideline ==== Structures and enumerations first used as parameters of a command are described next, by including the autogenerated interface file for that structure or enumeration: 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: + -- 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 combination of bitmask flags indicating usage behavior for the pool and command buffers allocated from it. Possible values include: + -- \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[] ====