1// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a 2// Creative Commons Attribution 4.0 International License; see 3// http://creativecommons.org/licenses/by/4.0/ 4 5[[writing]] 6= Writing Style 7 8 9[[writing-misc]] 10== Miscellaneous Grammar, Spelling, and Punctuation Issues 11 12=== Use the Oxford Comma (Serial Comma) 13 14When writing a sentence listing a series of items, include a comma before 15the "`and`" separating the last item. 16 17*Correct:* The red, green, blue, and alpha components. 18 19*Incorrect:* The red, green, blue and alpha components. 20 21Also see http://blog.oxforddictionaries.com/2011/06/oxford-comma/ 22 23 24=== Date Format 25 26Whenever possible, write dates in the <<iso-8601,ISO 8601>> format: 27YYYY-MM-DD. 28 29If needed for consistency with existing dates, e.g. in appendix changelogs, 30you can also write "`Month DD, YYYY`" where "`Month`" is the English name of 31the month. 32 33Never use ambigious formats such as "`09/12/16`". 34 35[source,asciidoc] 36.Example Markup 37---- 38 * 2016-09-12 39 * September 12, 2016 40---- 41 42 43[[writing-misc-a-an]] 44=== A/An and Markup Macros 45 46Use "`a`" and "`an`" http://www.grammar.com/a-vs-an-when-to-use/[correctly], 47based on the *sound* of the letter beginning the following word. 48 49It is easy to get this wrong when talking about Vulkan API names tagged with 50the <<markup-macros,markup macros>>. 51For example, if you wanted to say: 52 53A ename:VK_ERROR_DEVICE_LOST error 54 55the correct way to mark this up in asciidoc would be: 56 57[source,asciidoc] 58---- 59A ename:VK_ERROR_DEVICE_LOST error 60---- 61 62However, on first glance at this it *appears* wrong, because the "`word`" 63following "`a`" is the macro name, "`ename{cl}`". 64That starts with a vowel, so the temptation is to say 65 66[source,asciidoc] 67---- 68An ename:VK_ERROR_DEVICE_LOST error may occur. 69---- 70 71What matters here is how the *output* document is formatted. 72 73 74=== Numbers in Text 75 76When describing the need for a small number of objects, smaller than ten, 77spell the number out (e.g. "`one`"). 78If you are describing a literal value that is a small number, you may use a 79numeric value (e.g. "`1`"). 80 81For example, instead of writing that a bitmask "`contains 1 or more bits`", 82write that it "`contains one or more bits`". 83A counter example is that it is okay to write "`For non-stereoscopic-3D 84applications, this value is 1.`" 85 86 87=== Use American Spelling Conventions 88 89In case of conflict, use American rather than British spelling conventions, 90except for noted exceptions in the table below. 91 92.Spelling 93[width="60%",options="header"] 94|==== 95| Use Spelling | Instead Of | Comments 96| color | colour | 97| signaled | signalled | 98| tessellation | tesselation | Historical exception 99|==== 100 101 102[[writing-arrays]] 103=== Describing Properties of Array Elements 104 105Many Vulkan parameters are arrays, or pointers to arrays. 106When describing array elements, use the terminology "`each element`" when 107the description applies uniformly and independently to every element of the 108array. 109For example: 110 111[source,asciidoc] 112.Example Markup 113---- 114 * Each element of the pname:pCommandBuffers member of each element of 115 pname:pSubmits must: be in the <<commandbuffers-lifecycle, pending or 116 executable state>>. 117---- 118 119Use the terminology "`any element`" when the description is of zero or more 120elements of the array sharing a property. 121For example: 122 123[source,asciidoc] 124.Example Markup 125---- 126 * If any element of the pname:pCommandBuffers member of any element 127 of pname:pSubmits was not recorded with the 128 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 129 the <<commandbuffers-lifecycle, pending state>>. 130---- 131 132Never use the redundant terminology "`any *given* element`". 133 134 135[[writing-compound-words]] 136=== Compound Words and Preferred Orthography 137 138Unless there is longstanding precedent in computer science literature, or 139the word is a noted exception in the table below, do not arbitrarily cram 140terms together. 141 142This does not apply to parameter names in the API, where capitalization is 143used to distinguish words. 144For example, it is proper to refer to the use of a pname:colorSpace member 145of a structure as a "`color space`" value. 146 147.Spelling 148[width="70%",options="header",cols="20%,20%,60%"] 149|==== 150| Use Spelling | Instead Of | Comments 151| bit plane | bitplane | 152| compile time | compile-time | Per Wikipedia "`compile time`" 153| color space | colorspace | 154| double-buffer | doublebuffer | 155| entry point | entry-point 156 | Except if needed to disambiguate from surrounding terms 157| flat shading | flatshading | 158| GitHub | Github | Site's preferred spelling 159| LOD | lod + 160 level of detail + 161 level-of-detail| Acronym for "`Level of Detail`" 162| mip level + 163 mip layer + 164 mip size + 165 mip tail 166 | miplevel + 167 miplayer + 168 mipsize + 169 miptail | "`mipmap *term*`" may be used in time 1703+h| Exceptions 171| mipmap | mip map | Exception for historical reasons 172| pname:pNext chain 173 | pname:pNext-chain + 174 pname:pNext extension chain 175 | 176| general-purpose 177 | general purpose| When used as an adjective 178| swapchain | swap chain | Exception due to heavy use in WSI extensions 179| happen-before + 180 happen-after | happen before + 181 happen after | As used in concurrent languages such as 182 C++11, Java and OpenCL C. 183|==== 184 185==== Words With "Pre-" Prefixes 186 187// also: premultiply preorder prerotation predefined 188 189When using the prefix "`pre`" to indicate "`prior to`", such as in the words 190"`preinitialized`", "`preprocess`", and "`pretransform`", do not separate 191the prefix from the word with a hyphen. 192This list is not intended to be complete. 193 194 195[[writing-describing]] 196== Describing Commands and Parameters 197 198The <<vulkan-spec,Vulkan API Specification>> describes API commands followed 199by descriptions of their parameters, which are usually simple scalar types, 200handles or pointers to Vulkan objects or arrays of objects; enumerated types 201specifying values or bitmasks which affect the operation of a command; or 202structures containing combinations of scalar types and objects. 203The templates and examples shown and annotated here are based on the 204<<vulkan-spec,Vulkan API Specification>>. 205Do not vary from them without compelling need. 206 207Normative parts of the <<vulkan-spec,Vulkan API Specification>> should 208describe _what_ something does, rather than _how_ or _why_ an application 209would want to use it. 210 211When explicitly allowed by the Specification, the reserved value `NULL` may: 212be used for pointer parameters and members and dispatchable object handles, 213and the reserved value dname:VK_NULL_HANDLE may: be used for 214non-dispatchable Vulkan object handle parameters and members. 215Otherwise, pointers and handles must: refer to valid memory and valid Vulkan 216objects, respectively. 217 218 219[NOTE] 220.Guideline 221==== 222As a simple example, say 223 224"`To create a command pool, call fname:vkCreateCommandPool`" 225 226rather than 227 228"`You/The application/The user can create a command pool by calling 229fname:vkCreateCommandPool`". 230 231==== 232 233Explanations of _why_ and _how_ should largely be confined to reference 234documentation, sample code, tutorials, and other such documents. 235Occasional non-normative explanations can be included in the 236<<vulkan-spec,Vulkan API Specification>> using 237<<markup-informative-notes,informative notes>>. 238 239 240[[writing-latexmath]] 241== Math Markup 242 243There is a considerable amount of math in the documentation, ranging from 244simple arithmetic expressions to complicated conditionals. 245There are two ways of marking up math expressions, described below. 246 247=== Asciidoc Math Markup 248 249Where possible, math is marked up using straight asciidoc features. 250For commonality with LaTeX math (see below), some common LaTeX operators and 251names are defined as asciidoc attributes using the same names, expanding to 252the corresponding Unicode entities. 253The complete set of these attributes is found in `config/attribs.txt`. 254 255.Spelling 256[width="100%",options="header",cols="20%,20%,60%"] 257|==== 258| Feature | Result | Sample Markup 259 260| Subscripts 261| [eq]#a~x~# 262| +++[eq]#a~x~#+++ 263 264| Superscripts 265| [eq]#-2^(b-1)^# 266| +++[eq]#-2^(b-1)^#+++ 267 268| Struct/parameter names as variables 269| [eq]#2^pname:bits^# 270| +++[eq]#2^pname:bits^#+++ 271 272| Greek Letters (selected) 273| [eq]#{alpha}, {beta}, {gamma}, {delta}, {DeltaUpper}, {epsilon}, {lambda}, 274 {rho}, {tau}# 275| +++[eq]#{alpha}, {beta}, {gamma}, {delta}, {DeltaUpper}, {epsilon}, {lambda}, 276 {rho}, {tau}#+++ 277 278| Fractions 279| [eq]#{onequarter} + {onehalf}# 280| +++[eq]#{onequarter} + {onehalf}#+++ 281 282| Closed Ranges 283| [eq]#[0,1]# 284| +++[eq]#[0,1]#+++ 285 286| Open Ranges 287| [eq]#[0,1)# 288| +++[eq]#[0,1)#+++ 289 290| Arithmetic and Relational Operators 291| [eq]#a {times} b#, [eq]#a {leq} b#, [eq]#a {neq} b#, [eq]#a {geq} b#, [eq]#{vert}x{vert}# 292| +++[eq]#a {times} b#+++, +++[eq]#a {leq} b#+++, +++[eq]#a {neq} b#+++, +++[eq]#a {geq} b#+++, +++[eq]#{vert}x{vert}#+++ 293 294| Floor 295| [eq]#{lfloor}w - {onehalf}{rfloor}# 296| +++[eq]#{lfloor}w - {onehalf}{rfloor}#+++ 297 298| Ceiling 299| [eq]#{lceil}log~2~(max(pname:width, pname:height)){rceil} + 1# 300| +++[eq]#{lceil}log~2~(max(pname:width, pname:height)){rceil} + 1#+++ 301 302| Logical and Set Operators 303| [eq]#{land} {lnot} {lor} {oplus} {elem}# 304| +++[eq]#{land} {lnot} {lor} {oplus} {elem}#+++ 305 306| Partial Derivatives 307| [eq]#{partial}r~x~ / {partial}x = 0# 308| +++[eq]#{partial}r~x~ / {partial}x = 0#+++ 309 310| Matrix/Vector Parameter Names 311| [eq]#**P** = t **P**~1~ + (1-t) **P**~2~# 312| +++[eq]#**P** = t **P**~1~ + (1-t) **P**~2~#+++ 313 314|==== 315 316 317=== LaTeX Math Markup 318 319Math markup more complex than easily supported in straight asciidoc markup 320(examples found in the Vulkan Specification include matrices, tensors, 321summation notation, conditional assignments, and division of complex 322expressions) are marked up using LaTeX math notation, which is either passed 323through to the KaTeX in-browser rendering script for HTML outputs, or passed 324through asciidoctor-mathematical for PDF outputs. 325 326[NOTE] 327.Note 328==== 329There are font and style differences between LaTeX and asciidoc math markup 330which lead to minor visual inconsistencies. 331We'll try to make this better over time, but it's not significant enough to 332be a big priority. 333==== 334 335While LaTeX math macros, including the amsmath package, are supported, 336general LaTeX constructs are not. 337 338_Inline math_ is encoded using the latexmath{cl} macro. 339For example: 340 341 * latexmath:[[0,1\]] 342 * latexmath:[\frac{1 - \frac{x}{2}}{x - 1}] 343 * latexmath:[\mathbf{c} = t \mathbf{c}_1 + (1-t) \mathbf{c}_2.] 344 345[source,asciidoc] 346.Example Markup 347---- 348 * latexmath:[[0,1\]] 349 * latexmath:[\frac{1 - \frac{x}{2}}{x - 1}] 350 * latexmath:[\mathbf{c} = t \mathbf{c}_1 + (1-t) \mathbf{c}_2. ] 351---- 352 353Note the escaped bracket in markup for the first expression, which is 354necessary to work around asciidoc macro parsing. 355 356_Block math_ is used for more complex equations. 357This example uses the `aligned` environment to delimit the expression. 358 359[latexmath] 360+++++++++++++++++++ 361\begin{aligned} 362c_{RGB} & = 363 \begin{cases} 364 \frac{c_{sRGB}}{12.92} & \text{for}\ c_{sRGB} \leq 0.04045 \\ 365 \left ( \frac{c_{sRGB}+0.055}{1.055} \right )^{2.4} & \text{for}\ c_{sRGB} > 0.04045 366 \end{cases} 367\end{aligned} 368+++++++++++++++++++ 369 370[source,asciidoc] 371.Example Markup 372---- 373[latexmath] 374+++++++++++++++++++ 375\begin{aligned} 376c_{RGB} & = 377 \begin{cases} 378 \frac{c_{sRGB}}{12.92} & \text{for}\ c_{sRGB} \leq 0.04045 \\ 379 \left ( \frac{c_{sRGB}+0.055}{1.055} \right )^{2.4} & \text{for}\ c_{sRGB} > 0.04045 380 \end{cases} 381\end{aligned} 382+++++++++++++++++++ 383---- 384 385[NOTE] 386.Note 387==== 388The KaTeX processor used to render LaTeX math inside HTML documents does not 389support all features of LaTeX math. 390 391Similarly, the asciidoctor-mathematical processor does not support 392everything, though does have some support for AMSMath. 393 394Some workarounds we've had to make are: 395 396.LaTeX math replacements for KaTeX compatibility 397[width="70%",options="header",cols="20%,20%,60%"] 398|==== 399| Replace | With | Comments 400| `\begin{equation}` | _nothing_ | Unnecessary in blocks. Should not be used for inline. 401| `\end{equation}` | _nothing_ | Unnecessary in blocks. Should not be used for inline. 402| `\begin{align*}` | `\begin{aligned}` | 403| `\end{align*}` | `\end{aligned}` | 404| `\operatorname{foo}` | `\mathbin{foo}` | 405| `{\rm A}` | `\mathrm{A}` | 406| `\text{for }` | `\text{for}\ ` | Text ending in spaces is unpredictable - favour escaped spaces after text 407|==== 408 409See https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX for a list 410of currently supported LaTeX functionality in KaTeX. 411You can also use the live katex preview tool on the KaTeX website to double 412check support, without building the whole spec: 413https://khan.github.io/KaTeX/ 414 415See https://github.com/gjtorikian/mtex2MML/blob/master/SUPPORTED.md for the 416list of supported operations in the PDF build. 417\mathop in particular is not supported properly by the PDF build, but most 418other standard functionality is included. 419 420It is necessary to cross reference these two to make sure that support 421exists before using anything, but almost all standard functionality is 422supported for both. 423==== 424 425This example is among the most complex expressions in the Vulkan 426specification: 427 428[latexmath] 429+++++++++++++++++++ 430V = 431 \begin{cases} 432 (-1)^S \times 0.0, & E = 0, M = 0 \\ 433 (-1)^S \times 2^{-14} \times { M \over 2^{10} }, 434 & E = 0, M \neq 0 \\ 435 (-1)^S \times 2^{E-15} \times { \left( 1 + { M \over 2^{10} } \right) }, 436 & 0 < E < 31 \\ 437 (-1)^S \times Inf, & E = 31, M = 0 \\ 438 NaN, & E = 31, M \neq 0 439 \end{cases} 440+++++++++++++++++++ 441 442[source,asciidoc] 443.Example Markup 444---- 445[latexmath] 446+++++++++++++++++++ 447V = 448 \begin{cases} 449 (-1)^S \times 0.0, & E = 0, M = 0 \\ 450 (-1)^S \times 2^{-14} \times { M \over 2^{10} }, 451 & E = 0, M \neq 0 \\ 452 (-1)^S \times 2^{E-15} \times { \left( 1 + { M \over 2^{10} } \right) }, 453 & 0 < E < 31 \\ 454 (-1)^S \times Inf, & E = 31, M = 0 \\ 455 NaN, & E = 31, M \neq 0 456 \end{cases} 457+++++++++++++++++++ 458---- 459 460 461[[writing-latexmath-in-table-cells]] 462=== LaTeX Math in Table Cells 463 464To use `[latexmath]` or `latexmath{cl}` constructs inside table cells, the 465cell separator must be `a|` instead of just `|`: 466 467[source,asciidoc] 468.Example Markup 469---- 470.Advanced Blend Overlap Modes 471[width="80%",options="header"] 472|==== 473| Overlap Mode | Weighting Equations 474| ename:VK_BLEND_OVERLAP_UNCORRELATED_EXT a| 475[latexmath] 476++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 477 \begin{aligned} 478 p_0(A_s,A_d) & = A_sA_d \\ 479 p_1(A_s,A_d) & = A_s(1-A_d) \\ 480 p_2(A_s,A_d) & = A_d(1-A_s) \\ 481 \end{aligned} 482++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 483---- 484 485 486[[writing-pNext-chain]] 487== Describing Extension Structure Chains 488 489When describing an extension structure which is passed to an existing 490command by placing it in the pname:pNext chain of a structure parameter of 491that command, introduce the structure description in this fashion: 492 493[source,asciidoc] 494---- 495When *performing an operation described by the extension struct*, add 496the slink:VkExtensionStructNameID to the pname:pNext chain of the 497slink:VkBaseExtensionStructName structure passed to the 498flink:vkBaseFunctionName command *saying what the extension struct 499does*. 500---- 501 502 503[[writing-example]] 504== An Example Command Description 505 506The <<sample-command,next section>> is a sample based on the 507<<vulkan-spec,Vulkan API Specification>>, and describes a command in enough 508detail to see the different usage patterns and layout / markup used. 509Informative notes discussing markup and guidelines are interspersed with the 510example description to explain how and why it looks as it does. 511 512 513[[sample-command]] 514== Sample Command Description: Creating Command Pools 515 516// Three dashes are used here to allow the inner [source] block to show the 517// correct two dashes. 518 519[open,refpage='VkCreateCommandPool',desc='Create a new command pool object',type='protos'] 520-- 521To create a command pool, call: 522 523include::../api/protos/vkCreateCommandPool.txt[] 524 525[NOTE] 526.Guideline 527==== 528Begin the command description with an open block delimiting the contents as 529a reference page. 530The open block contains several required attribute values, as described for 531<<writing-refpages, automatic extraction into a reference page>>. 532 533Use a short, active sentence when describing what commands do, instead of 534more passive phrasing like "`A command pool is created by calling:`" or 535"`The application may create a command pool by calling:`". 536 537After the description, include the autogenerated prototype for the command 538from the `../protos/` directory: 539 540// The 'subs=attributes+' and '{blank}--' are one way to allow the inner 541// [source] block to show the correct two dashes. See 542// http://discuss.asciidoctor.org/Another-markup-escaping-question-td5665.html 543 544[source,asciidoc,subs=attributes+] 545---- 546[open,refpage='VkCreateCommandPool',desc='Create a new command pool object',type='protos'] 547{blank}-- 548To create a command pool, call: 549 550\include::../api/protos/vkCreateCommandPool.txt[] 551---- 552 553Note that each autogenerated command, enumeration, flag, or structure 554definition include file also defines a corresponding asciidoc anchor which 555is the base name of the file. 556In this case, the anchor is named `vkCreateCommandPool`. 557==== 558 559 * pname:device is the logical device that the command pool is created on. 560 * pname:pCreateInfo points to an instance of the 561 slink:VkCommandPoolCreateInfo structure containing information used to 562 create the command pool. 563 * pname:pAllocator controls host memory allocation as described in the 564 <<memory-allocation, Memory Allocation>> chapter. 565 * pname:pCommandPool points to a handle in which the created command pool 566 object is returned. 567 568[NOTE] 569.Guideline 570==== 571Each command parameter is described in a separate bullet list entry, 572followed by validity rules, then detailed descriptions of any new 573structures, flags, or enumerations introduced by this command. 574 575Each parameter should appear as a separate bullet list item beginning with 576the parameter name, in the same order as parameters appear in the command. 577This aids in extracting short descriptions of parameters for inclusion in 578annotated headers and similar documentation. 579Make sure to tag each parameter with the pname{cl} macro. 580 581Strive for compact notation, and in particular always try to use the 582phrasing "`pname{cl}param _is_`" rather than wordier forms such as 583"`pname{cl}param _specifies_`" or "`The pname{cl}param parameter 584specifies`". 585In general there is no need to describe a parameter which is a Vulkan object 586handle *as* a handle; for example, say "`pname{cl}device is the logical 587device`" rather than "`pname{cl}device is a handle to the logical device`". 588An exception is object creation functions, where a pointer to a handle of 589the proper type is used to return the newly created object. 590==== 591 592include::../validity/protos/vkCreateCommandPool.txt[] 593-- 594 595[NOTE] 596.Guideline 597==== 598Some parameter and member validation language for commands and structures is 599_implicit_ (autogenerated from `vk.xml`), and included from the 600`../validity/` directories. 601All Vulkan command and structure language should include the autogenerated 602file at the end of their descriptions. 603It is harmless to include a nonexistent file, in the rare cases where no 604implicit validity language exists. 605 606[source,asciidoc,subs=attributes+] 607---- 608\include::../validity/protos/vkCreateCommandPool.txt[] 609{blank}-- 610---- 611 612End the open block surrounding the command description after the implicit 613validity include. 614All content within the block will be extracted for the corresponding 615reference page. 616 617[NOTE] 618.Guideline 619==== 620Open blocks delimiting reference page content should not themselves contain 621section headers, as asciidoctor can't render such nested content correctly. 622Reference pages should in general be relatively short, so this limitation is 623not severe. 624==== 625 626Structures and enumerations first used as parameters of a command are 627described next. 628 629==== 630 631// Three dashes are used here to allow the inner [source] block to show the 632// correct two dashes. 633 634[open,refpage='VkCommandPoolCreateInfo',desc='Structure specifying parameters of a newly created command pool',type='structs'] 635-- 636 637The sname:VkCommandPoolCreateInfo structure is defined as: 638 639include::../api/structs/VkCommandPoolCreateInfo.txt[] 640 641[NOTE] 642.Guideline 643==== 644Begin the structure description with an open block delimiting the contents 645as a reference page, in the same fashion as described above for commands. 646The open block contains several required attribute values, as described for 647<<writing-refpages, automatic extraction into a reference page>>. 648 649Use a short, active paragraph to introduce the structure, usually just "`The 650sname:VkStructureName structure is defined as:`". 651 652After the description, include the autogenerated definition for the 653structure from the `../structs/` directory: 654 655[source,asciidoc,subs=attributes+] 656---- 657[open,refpage='VkCommandPoolCreateInfo',desc='Structure specifying parameters of a newly created command pool',type='structs'] 658{blank}-- 659 660The sname:VkCommandPoolCreateInfo structure is defined as: 661 662\include::../api/structs/VkCommandPoolCreateInfo.txt[] 663---- 664==== 665 666 * pname:sType is the type of this structure. 667 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 668 * pname:flags is a bitmask of elink:VkCommandPoolCreateFlagBits indicating 669 usage behavior for the pool and command buffers allocated from it. 670 * pname:queueFamilyIndex designates a queue family as described in section 671 <<devsandqueues-queueprops,Queue Family Properties>>. 672 All command buffers allocated from this command pool must: be submitted 673 on queues from the same queue family. 674 675[NOTE] 676.Guideline 677==== 678Each structure member is described in a separate bullet list entry. 679For the stext:Vk*CreateInfo structures in particular, there is standard 680boilerplate for the pname:sType and pname:pNext members, followed by the 681members specific to the structure. 682 683[source,asciidoc] 684---- 685 * pname:sType is the type of this structure. 686 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 687 * pname:flags is a bitmask of elink:VkCommandPoolCreateFlagBits indicating 688 usage behavior for the pool and command buffers allocated from it. 689 * pname:queueFamilyIndex designates a queue family as described in section 690 <<devsandqueues-queueprops,Queue Family Properties>>. 691 All command buffers allocated from this command pool must: be submitted 692 on queues from the same queue family. 693---- 694 695These entries should be short and functional, without describing details of 696e.g. new enumerant values, function of individual parameter settings, etc. 697They can refer to other types using the appropriate *link: macros or to 698related sections of the specification using asciidoc xrefs. 699 700In rare cases, an entry will cover multiple paragraphs. 701In these cases the normal list nesting and indentation guidelines cannot be 702applied due to limitations of the asciidoc parser. 703It is usually best to append a continuation block following the first 704paragraph of such a list item: 705 706// @@@ Use VkCommandBufferInheritanceInfo:framebuffer for a current example instead 707ifdef::editing-notes[] 708[NOTE] 709.editing-note 710==== 711This example is obsolete and incorrect. 712Use VkCommandBufferInheritanceInfo:framebuffer for a current example 713instead. 714==== 715endif::editing-notes[] 716 717[source,asciidoc,subs=attributes+] 718---- 719 * pname:flags is a bitmask indicating usage behavior for the pool and 720 command buffers allocated from it. 721 Bits which can: be set include: 722+ 723{blank}-- 724// refBegin VkCommandPoolCreateFlagBits - Bitmask specifying usage behavior for a command pool 725\include::../api/enums/VkCommandPoolCreateFlagBits.txt[] 726{blank}-- 727+ 728 ** ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT 729 indicates that command buffers allocated 730 from the pool will be short-lived. 731 ** ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT 732 controls whether command buffers allocated from 733 the pool can: be individually reset. 734---- 735==== 736 737.Valid Usage 738**** 739 * [[VUID-VkCommandPoolCreateInfo-queueFamilyIndex-00039]] 740 pname:queueFamilyIndex must: be the index of a queue family available in 741 the calling command's pname:device parameter 742**** 743 744[NOTE] 745.Guideline 746==== 747In addition to implicit validity language, there may be additional 748validation language which is explicit. 749Such language is written in a separate block in the specification, 750_preceding_ the validity include. 751The fname:vkCreateCommandPool example above has no such explicit language, 752but this example does have explicit language. 753==== 754 755include::../validity/structs/VkCommandPoolCreateInfo.txt[] 756-- 757 758[NOTE] 759.Guideline 760==== 761Following the definition of structure members, add explicit validity 762language, following by including the implicit (automatically generated) 763validity language include for this structure: 764 765[source,asciidoc] 766---- 767.Valid Usage 768**** 769 * [[VUID-VkCommandPoolCreateInfo-queueFamilyIndex-00039]] 770 pname:queueFamilyIndex must: be the index of a queue family available in 771 the calling command's pname:device parameter 772**** 773 774\include::../validity/structs/VkCommandPoolCreateInfo.txt[] 775---- 776 777Each explicit Valid Usage statement should be a single, self-contained 778assertion, possibly involving multiple subexpressions or parameters. 779For example, instead of writing "`width, height, and depth must: all be 780greater than zero`", write each condition as a separate statement. 781In contrast, "`width {times} height must: be less than 1024`" is a single 782assertion involving multiple parameters. 783 784Do not use "`unless`" to call out exceptions - always write valid usage 785statements of the form "`if _A_ then _B_`". 786This may result in harder to read statements in a few cases, but maintains 787consistency. 788In many cases, it may lead to a simpler VU statement, or splitting one large 789VU into multiple new ones. 790 791Do not use nested lists or other writing structure where Valid Usage 792statements are not self-contained. 793This would make it impossible to extract semantically meaningful 794descriptions for each assigned <<appendix-vuid, Valid Usage ID Tag>>. 795 796Be clear on the distinction between a "`valid pointer`" and a "`pointer to a 797valid object`" when writing Valid Usage statements. 798See the "`Valid Usage`" section of the Vulkan Specification, and 799particularly the "`Valid Usage for Pointers`" section. 800 801Explicit Valid Usage statements must be assigned Valid Usage ID tags before 802publication. 803This process is described in the <<appendix-vuid, Valid Usage ID Tags>> 804appendix, but is normally performed only when preparing to integrate 805functionality into the Vulkan Specification prior to publication. 806It is something authors of new functionality should be aware of, but are not 807themselves responsible for. 808For example, when writing the explicit pname:queueFamilyIndex statement 809shown above, the tag 810 811[source,asciidoc] 812---- 813[[VUID-VkCommandPoolCreateInfo-queueFamilyIndex-00039]] 814---- 815 816was inserted by a script, not the original author. 817==== 818 819 820[[writing-empty-enumerations]] 821== Markup For Empty Enumerated Types 822 823Sometimes an enumerated type has all values defined by extensions, and each 824enumerated value defined by the type will be surrounded by an asciidoc 825conditional for the corresponding extension. 826When a specification is built without any of those extensions enabled, the 827type should still be included, even though it is empty. 828In this case, the enumerated value descriptions must be followed by one 829additional conditional section which is only included when *none* of the 830relevant extensions are enabled. 831 832For example, the relevant part of the 833elink:VkDescriptorSetLayoutCreateFlagBits description, whose only value is 834defined by an extension, will look like this: 835 836[source,asciidoc,subs=attributes+] 837---- 838\include::../api/enums/VkDescriptorSetLayoutCreateFlagBits.txt[] 839 840\ifdef::VK_KHR_push_descriptor[] 841 * ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR specifies 842 that descriptor sets must: not be allocated using this layout, and 843 descriptors are instead pushed by flink:vkCmdPushDescriptorSetKHR. 844\endif::VK_KHR_push_descriptor[] 845 846\ifndef::VK_KHR_push_descriptor[] 847[NOTE] 848.Note 849==== 850All bits for this type are defined by extensions, and none of those 851extensions are enabled in this build of the specification. 852==== 853\endif::VK_KHR_push_descriptor[] 854---- 855 856 857[[writing-refpages]] 858== Markup For Automatic Reference Page Extraction 859 860The Vulkan reference pages are (mostly) extracted from corresponding 861sections of the API Specification. 862This requires that the markup and writing conventions described above be 863adhered to rigidly. 864 865The extraction scripts for a given page rely on the existence of an asciidoc 866`open` block surrounding markup describing that page, with attributes used 867to specify properties of the reference page. 868Additional heuristics and non-asciidoc tags, described below, are used to 869identify subsections of a reference page in some cases. 870 871In general the open block introduction will look like: 872 873[source,asciidoc] 874---- 875[open,refpage='name',desc='short description',type='pagetype',xrefs='xrefs'] 876-- 877---- 878 879Attributes which can be set on the block are: 880 881 * *refpage* - the name of the reference page, e.g. the Vulkan interface 882 (command, structure, enumerant, handle, etc.) name. This attribute is 883 required. 884 * *desc* - short description / summary of the page, used in the page 885 title. 886 This attribute is required. 887 * *type* - type of the interface, which must match the directory name 888 following `api/` in the interface `include::` line within the block, and 889 must be one of `basetypes`, `defines`, `enums`, `flags`, `funcpointers`, 890 `handles`, `protos`, or `structs`. 891 This attribute is required. 892 * *xrefs* - list of whitespace-separated names of other reference pages 893 which should be added to the `See Also` section of this page. 894 Most cross-references are automatically generated based on the immediate 895 dependency information in `vk.xml`, but in some cases, such as referring 896 between `*FlagBits` and `*Flags` types, this additional tagging is 897 useful. 898 This attribute is optional. 899 900Attributes of the open block must be written in this format, using single 901quotes as delimiters (even though asciidoc markup also allows double 902quotes), and escape single quotes in e.g. the *desc* attribute value with 903backquotes. 904 905After the open block is started, the following markup should be provided: 906 907 * A single paragraph of text describing the definition of the interface. 908 This paragraph is optional, but strongly recommended. 909 * The `include` line for the interface, which must be consistent with the 910 page name and type in the open block attributes. 911 This paragraph is required. 912 * A bullet list describing function parameters, structure members, 913 enumerants in an enumerated type, etc. 914 This list should contain no empty lines, as the extraction script 915 classifies the uninterrupted block of text following the `include` 916 directive as the `Parameters` or `Members` section of the ref page. 917 This list is required, unless the interface has nothing to describe, 918 such as an empty structure or enumeration, or a function with no 919 parameters. 920 * Paragraphs of text making up the `Description` section of the ref page. 921 This section is optional. 922 If it is necessary due to constraints of asciidoc markup to have an 923 empty line in the bullet list section^1^, add a `// refBody` comment 924 immediately following the bullet list and preceding this section: 925+ 926[source,asciidoc] 927---- 928// refBody 929---- 930+ 931 * An explicit Valid Usage block. 932 This block is required if the interface has such Valid Usage 933 constraints. 934 * The `include` line for the implicit valid usage block. 935 This line is required for for commands and structures, but not for 936 interfaces such as enumerated types, which do not have implicit valid 937 usage blocks. 938 * Finally, a two-dash asciidoc delimiter closing the open block: 939+ 940[source,asciidoc] 941---- 942-- 943---- 944 9451:: 946 The only example of such markup in the 1.0.28 Vulkan Specification 947 source is the stext:VkPhysicalDeviceLimits structure description. 948 949All elements specifying an interface name (open block `refpage` attributes, 950interface `include` lines, and validity `include` lines) must use the same 951interface name, if present. 952Otherwise the extraction script is either unable to extract that page, or 953will extract the wrong text - and the language will be structurally 954incorrect, as well. 955The extraction process is somewhat fragile, so care should be taken and the 956results of reference page extraction verified after making changes to that 957portion of the specification source. 958