// Copyright (c) 2015-2016 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 section 11.2 of the <>) 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. 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. .Example Markup ---- [[markup]] = Markup Style [[markup-sample-section]] == Sample Section ---- [[markup-sample-section]] == Sample Section This is a sample section structurally similar to the <>, 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 en-dash: [NOTE] .Example Markup ==== `An -- en-dash` -> An -- en-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 chapter 10 of the <> 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 double back-ticks as opening marks and double apostrophes as closing marks (\`\`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 <> 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 <> | Example | `====` | For <> | Passthrough | `++++` | For some kinds of <> | Comment | //// | | Listing | ---- | For source code listings | Sidebar | **** | For <> | Table | `\|====` | For <> | Quote | `____` | 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 -- `See reference^2^` -> See reference^2^. .... 2:: 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. .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. ---- [[markup-labelled-lists]] ==== Labelled Lists Labelled lists may be used in some cases such as <>; 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. .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. .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 <>. 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 <>. However, using the <> 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. .Example Markup ---- In general, chapters and sections should always have anchors, following the naming convention <>. ... so it is easy to link to a (for example) a command name such as <>. However, using the <> 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. .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: .Example Markup ---- [[fig-anchorname]] image::images/imagename.{svgpdf}[align="center",title="Figure caption",{fullimagewidth}] ---- There must be both .svg and .pdf versions of each figure checked into the +images/+ directory, to support generating both HTML and PDF outputs. It is best to create images in Inkscape as SVG files and then use the conversion rule in +doc/specs/vulkan/images/Makefile+ to generate PDF. Asciidoc 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: .Example Markup ---- .Caption **** In the <> 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 <> 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. The flink{cl} macro is preferred. | ftext{cl} | Formats the macro argument like fname{cl}. May contain asterisks for wildcards. Not validated. Example: ftext{cl}vkCmd* -> ftext:vkCmd*. Only use ftext{cl} when it is necessary to describe something that should be rendered like a command name, but is not actually one (e.g. is a wildcard or subset of an actual command name). | slink{cl} | Generates a cross-reference or link to the definition of the structure 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. The slink{cl} macro is preferred if a definition of the target type with an anchor exists in the document. | 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 stext{cl} when it is necessary to describe something that should be rendered like a structure name, but is not actually one (e.g. is a wildcard or subset of an actual structure name). | elink{cl} | Formats the macro argument as a Vulkan enumeration name and links to the definition of that enumeration type. Example: ename{cl}VkResult -> ename:VkResult. | ename{cl} | Formats the macro argument as a Vulkan enumerant name. Example: ename{cl}VK_EVENT_SET -> ename:VK_EVENT_SET. | 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 etext{cl} when it is necessary to describe something that should be rendered like a enumerant name, but is not actually one (e.g. is a wildcard or subset of an actual enumerant name). | 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 ptext{cl} when it is necessary to describe something that should be rendered like a parameter name, but is not actually one (e.g. is a wildcard or subset of an actual parameter name). | 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 types at present. | tname{cl} | Formats the macro argument like tlink{cl}. Does not generate a cross-reference. Example: tname{cl}PFN_vkAllocationFunction -> tname:PFN_vkAllocationFunction. The tlink{cl} macro is preferred. | 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 <> | dname{cl} | Formats the macro argument like dlink{cl}. Does not generate a cross-reference. The dlink{cl} macro is preferred. | 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. Primarily used for SPIR-V keywords and builtin C types. Examples: code{cl}uint32_t -> code:uint32_t, code{cl}ClipDistance -> code:ClipDistance, code{cl}VK_NULL_HANDLE -> code:VK_NULL_HANDLE, code{cl}NULL -> code:NULL. |==== 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. .Example Markup ---- flink:vkCmdBindIndexBuffer::pname:indexType slink:VkMemoryHeap::pname:flags ---- ==== Other Markup Uses of standard Asciidoc markup are less common. Occasional asterisk markup is used for *emphasis*. Backtick markup is sometimes used for the C `NULL` macro, but the code{cl} macro should be used for code:NULL instead. .Example Markup ---- *emphasis* `NULL` code: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 <>. However, we will probably change to using custom macros soon, to enable linkage between the glossary and definitions in the spec body. .Example Markup ---- _Glossary terms_ ---- === Normative Terminology Normative terminology is precisely defined in section 1.3 of the <>, 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 <>, 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: | recommend{cl} | recommend: | 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 .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 <>. 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. ==== .Example Markup ---- [NOTE] .Note ==== This is an informative note. ==== ---- If an entire chapter or section is considered informative, it should begin with the sentence: .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 a canonical (+1.0+ or per-extension) public 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[] .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[] .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 in the first column instead of the alternate terms. This list may not be comprehensive; when in doubt, be guided by the existing <>. .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. | 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 | Implementations on non-GPU devices are possible. | heterogeneous | heterogenous | More common | homogeneous | homogenous | More common | host endianness | platform endianness | | image subresource | subresource | Except when referring to *host-accessible subresources* | implementation| system | | indices | indexes | More common | member | field | | pname:parameter are/is | pname:parameter specifies (denotes, indicates) | In rare 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}_. |====