diff options
Diffstat (limited to 'codegen/vulkan/styleguide.txt')
-rw-r--r-- | codegen/vulkan/styleguide.txt | 381 |
1 files changed, 381 insertions, 0 deletions
diff --git a/codegen/vulkan/styleguide.txt b/codegen/vulkan/styleguide.txt new file mode 100644 index 00000000..3c1a8dd6 --- /dev/null +++ b/codegen/vulkan/styleguide.txt @@ -0,0 +1,381 @@ +// Copyright 2014-2021 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + += Vulkan^®^ Documentation and Extensions: Procedures and Conventions +Jon Leech, Tobias Hector +:data-uri: +:icons: font +:toc2: +:toclevels: 3 +:numbered: +:source-highlighter: rouge +:rouge-style: github +:doctype: book +:imagewidth: 800 +:fullimagewidth: width="800" +:cl: : + +// Various special / math symbols. This is easier to edit with than Unicode. +include::{config}/attribs.txt[] + +// Where the current Asciidoctor documentation is found. +:docguide: https://docs.asciidoctor.org/asciidoc/latest + +:leveloffset: 1 + +<<<< + +include::{config}/copyright-ccby.txt[] + +<<<< + +[[introduction]] += Introduction + +This document contains required procedures and conventions when writing +specifications for new Vulkan APIs, extensions and layers, or related +Khronos^{reg}^ documentation such as white papers and tutorials; or +contributing to existing Vulkan specifications. +These are collectively referred to as _Vulkan Documentation_ or just +_documentation_ below. +The primary focus is the API Specification and API extensions, although all +of the markup and most of the writing style is equally applicable to other +documentation. + +The primary purpose is to achieve consistency across the API, as well as +across all of our source and output documents. +Consistency makes it easier for developers, editors, reviewers, and users of +our documentation to understand and modify it. + +This document is now formally voted on and approved by the Vulkan Working +Group. +This means that unless explicitly stated otherwise, the procedures and +conventions must be followed. +If you have a strong desire to modify the procedures and conventions, such +changes must be made through the normal Vulkan Working Group processes. + + +[[introduction-terminology]] +== Terminology + +The key words *must*, *required*, *should*, *recommend*, *may*, and +*optional* in this document are to be interpreted as described in RFC 2119 +and by the Vulkan Specification in the "`Terminology`" section. + + +[[introduction-structure]] +== Document Structure + +The style guide is broken into four sections: + + * <<naming,API Naming Conventions>> - the required rules for choosing + names of Vulkan identifiers of all types. + * <<extensions,Extensions and Layers>> - the required procedures for + creating formal Vulkan extensions and layers. + * <<markup,Markup Style>> - the required and recommended markup style for + writing asciidoctor and XML source that follows consistent formatting + and layout guidelines, tags special terms and phrases for proper + processing by the spec generation tools, etc. + * <<writing,Writing Style>> - the required and recommended writing style + for overall and fine-grained structure and conventions, normative + language use, API naming conventions, common words and phrases to use + and to avoid, linking and cross-referencing, etc. + + +[[introduction-asciidoc]] +== Asciidoctor Markup + +Vulkan Documentation is primarily written in Asciidoctor, a text markup +language. +We use the command-line asciidoctor client that is actively maintained by +asciidoctor, which is documented on its website at https://asciidoctor.org. + +References to the Asciidoctor User Manual are to sections in the document at +https://asciidoctor.org/docs/user-manual/. + +Asciidoctor is implemented in Ruby (https://www.ruby-lang.org/), which is +available for Linux, MacOS, and Microsoft Windows. + +[NOTE] +.Note +==== +There are other implementations of asciidoctor, such as AsciidoctorJ +(https://github.com/asciidoctor/asciidoctorj) and asciidoctor.js +(https://github.com/asciidoctor/asciidoctor.js). +In particular, GitHub and GitLab both have preview renderers for .adoc or +.asciidoc files in repositories, and live preview extensions exist for +Chrome and Firefox. + +However, because of the use of custom Ruby macros in the Vulkan +Specification toolchain, and the high complexity of the documents and +toolchain used to generate it, these web tools cannot currently render the +Specification from source. +Instead, we generate HTML and PDF versions of the Specification and publish +them on the Khronos website. + +The Asciidoctor toolchain and build process are not addressed by this +document, which concentrates solely on source documents. +==== + + +[[introduction-normative]] +== Normative References + +Normative references are references to external documents or resources to +which documentation authors must comply. + +[[acm-references]] +Association for Computing Machinery. +_Citation Style and Reference Formats_. +Retrieved July 27, 2019. +https://www.acm.org/publications/authors/reference-formatting . + +[[iso-8601]] +International Organization for Standardization. +_Data elements and interchange formats -- Information interchange -- +Representation of dates and times_ (2004-12-01). +https://www.iso.org/standard/40874.html . +Also see https://www.w3.org/QA/Tips/iso-date for colloquial examples. + +[[vulkan-docs]] +Khronos Vulkan Working Group. +`KhronosGroup/Vulkan-Docs` project on GitHub (July 5, 2016). +https://github.com/KhronosGroup/Vulkan-Docs . + +[[vulkan-spec]] +Khronos Vulkan Working Group. +_Vulkan 1.1.116 - A Specification_ (July 20, 2019). +https://www.khronos.org/registry/vulkan/ . + +Version 1.1.116 is the latest patch release of the Vulkan API Specification +as of the time this reference was created, but that Specification is +frequently updated with minor bugfixes and clarifications. +When a more recent patch release is made, it becomes the normative reference +for the API. + + +// Chapters of the text are included below + +include::style/naming.txt[] + +include::style/extensions.txt[] + +include::style/markup.txt[] + +include::style/writing.txt[] + +include::style/misc.txt[] + +// Appendices are included below +include::style/vuid.txt[] + + += Revision History + +* 2021-11-04 - Remove backquote markup around recommended use of the + `apiext:` macro, since that macro now styles the extension name argument + itself. +* 2021-10-29 - add "`render pass" to the <<writing-compound-words, Compound + Words and Preferred Orthography>> section. +* 2021-10-04 - Update the <<extensions-documenting-extensions, Changes for + New Extensions>> section to require use of the `apiext:` macro for links + to extension names (internal issue 2831). +* 2021-09-12 - Add a new subsection with more details on using + tilde-delimited source blocks <<markup-blocks-source, inside reference + page open blocks>>, and rewrite the <<sample-command, Sample Command + Description>> section to follow current phrasing and markup patterns + (internal issue 2040). +* 2021-09-09 - Add the <<markup-italicized-enumerant-names, Italicized + Enumerant Names>> section to clarify how to write wildcard enumerant names + with imbedded italicized text. +* 2021-09-06 - Add the <<writing-inclusivity, Use Inclusive Language>> + section based on the Khronos Inclusive Language list (internal issue + 2293). +* 2021-09-06 - add "`cube map`" to the <<writing-compound-words, Compound + Words and Preferred Orthography>> section (internal merge request 4794). +* 2021-07-20 - Add additional contraction examples to the table in the + <<markup-avoid-contractions, Avoid Abbreviations and Contractions>> + section. +* 2021-05-31 - Add "`implementation-dependent`" as an exception in the + <<writing-compound-words, Compound Words and Preferred Orthography>> + section (internal merge request 4611). +* 2021-05-24 - Add escapes to prevent expansion of attribute names in a few + places where markup examples are given. +* 2021-05-22 - Expand the <<markup-avoid-contractions, markup rules>> to + include avoiding abbreviations, as well as contractions. +* 2021-05-07 - Add <<markup-word-choices, preferred way to write + "`drawing/dispatching command">>. +* 2021-04-28 - Add <<markup-word-choices, disambiguations for + "`executable`">>. +* 2021-04-28 - Add <<writing-pointers-instances, usage for pointers and + handles>> which may be `NULL` or dname:VK_NULL_HANDLE, respectively + (internal issue 2662). +* 2021-04-14 - Add "`side effect`" and "`reuse`" as + <<writing-compound-words, preferred orthography>> (public issue 1484). +* 2021-03-31 - Update description of the code{cl} macro in the + <<markup-macros-api, API Markup Macros>> section to match current + behavior. +* 2021-03-21 - Note that the <<extensions-reserving-bitmask-values same bit + should be reserved>> for the same purpose in comparable 32- and 64-bit + bitmask types (internal issue 2565). +* 2020-09-14 - Change <<markup-informative-notes, Informative Sections and + Notes>> section to track actual usage and update the description of the + undefined{cl} macro to further clarify its purpose and uses (internal + issue 2195). +* 2020-08-16 - Add "`reference monitor`" to the preferred + <<markup-word-choices, Word Choices>> (internal issue 2291). +* 2020-08-10 - Add a <<writing-describing-errors, Commands which Return + Error Codes>> section to guide authors of new commands (internal issue + 2290). +* 2020-07-28 - Add a <<markup-copyrights, Copyrights and Licenses>> section + describing how to properly attribute this information. +* 2020-06-23 - Update the <<extensions-documenting-extensions, Changes for + New Extensions>> section to recommend placing most extension language + inline in existing specification source files, rather than in separate + files, and to base extension revision numbers at `1` starting with initial + public release (public issue 1263). +* 2020-04-29 - Expand use of `basetype` macros to include external API + types. +* 2020-03-16 - Add documentation of writing links to extension appendices in + the <<extensions-documenting-extensions, Changes for New Extensions>> + section and document the apiext{cl} and reflink{cl} macros in the + <<markup-macros-api, API Markup Macros>> section. + Improve documentation of writing <<writing-refpages, Markup For Automatic + Reference Page Extraction>> including how to mark up content in the + Specification source so it only appears in generated reference pages; + however, this section is still out of date (internal issue 1999). +* 2020-03-11 - Specify in the <<sample-command, Sample Command Description>> + section that a valid usage statement must be defined at the place (command + or structure specification) that all information need to evaluate the + statement is known. + Update the description of <<appendix-vuid-creating, Creating VUID tags>> + to match the current scripts. + Use the term "`asciidoctor`" instead of "`asciidoc`" everywhere. + Note in the <<introduction-asciidoc, Asciidoctor Markup>> section that the + Specification can only be built using the command-line asciidoctor client, + not by asciidoctor web clients. +* 2020-02-22 - Document that it is no longer needed to escape C arrows in + macros. +* 2019-12-15 - Add a markup section on <<markup-macros-prime-symbols, Prime + Symbols>> (internal issue 1110). +* 2019-11-27 - Expand the <<writing-pNext-chain, Describing Extension + Structure Chains>> section and make all spec language consistent with it + (internal issue 1814). +* 2019-09-09 - Define markup for nested structure members in the + <<markup-macros-api, API Markup Macros>> section (internal issue 1765). +* 2019-09-08 - Add language to the end of the + <<extensions-documenting-extensions, Changes for New Extensions>> section + describing how to mark up asciidoctor conditionals (internal issue 1808). +* 2019-08-25 - Add the <<markup-indentation-equations, Indentation of + Equations>> section (internal issue 1793). +* 2019-08-25 - Add the <<writing-describing-layers, Extensions and Grouping + Related Language>> section (internal issue 979) and the + <<markup-minimize-indentation, Minimize Indentation>> section (internal + issue 747). + Disallow use of standalone `+` except in latexmath and source blocks, in + the <<markup-layout, Asciidoc Markup And Text Layout>> section (internal + issue 736). +* 2019-08-19 - Add the <<writing-pointers-instances, Describing Pointers and + Instances>> section (internal issue 1553). +* 2019-08-13 - Add a NOTE to the <<appendix-vuid-format, Format of VUID + Tags>> appendix specifying allowed characters in VUID tags (based on + discussion for internal merge request 3239). +* 2019-07-27 - Add the <<writing-references, References>> section and + rewrite external references accordingly. +* 2019-05-09 - Specify rules for defining <<extensions-new-flags-types, new + flags and bitmask types>> (internal issue 1649). +* 2019-01-06 - Add details on <<extensions-reserving-bitmask-values, + Reserving Bitmask Values>> (internal issue 1411). +* 2018-11-19 - Add details to the <<extensions-documenting-extensions, + Changes for New Extensions>> section including the new "`Description`" + section, and other standard parts of extension appendices. +* 2018-08-13 - Add %inline directive to the <<markup-sample-section-images, + Figures>> section (public pull request 734). +* 2018-07-30 - Added a section on <<writing-undefined, Describing Undefined + Behavior>> (as part of the fixes for public issue 379), and describing why + the undefined{cl} macro should always be used. +* 2018-07-08 - Remove requirement to explicitly include extension appendices + in the <<extensions-documenting-extensions, Changes for New Extensions>> + section. +* 2018-06-25 - Modify the process for <<extensions-vendor-id, Registering a + Vendor ID with Khronos>> to define vendor ID values as part of an + enumerated type. +* 2018-03-07 - Updated for Vulkan 1.1 release. +* 2018-01-10 - Move details of mandated extension compatibility from the + <<extensions-rules, General Rules/Guidelines>> section into the + Fundamentals section of the API Specification, where they are changed + slightly to allow explicit incompatibilies (public issue 638). +* 2017-10-27 - Add language about proper use of "`valid pointer`" and + "`pointer to valid object`" for valid usage statements, in the + <<sample-command, Sample Command Description>> section (related to public + pull request 547). +* 2017-10-15 - Describe how to write <<writing-latexmath-in-table-cells, + LaTeX Math in Table Cells>> (internal issue 908). +* 2017-10-15 - Add more details of <<extensions-naming-author-IDs, `KHX` + extensions>> (public issues 536, 580). +* 2017-09-10 - Add descriptions of <<writing-arrays, how to use `each` and + `any`>> to refer to properties of elments of arrays (internal issue 884). +* 2017-09-10 - Add <<extensions-interactions-parent, Valid Usage and + Extension pname:pNext Chains>> language specifying where to describe + interactions of structures in a pname:pNext chain (internal issue 715). +* 2017-09-10 - Add example of marking up an enumerated type all of whose + values are defined by extensions (internal issue 864). +* 2017-08-25 - Add language to the <<extensions,API Versions, Extensions, + and Layers>> chapter describing how to write new API versions (internal + issue 892). +* 2017-06-12 - Add sections describing when to use the + <<markup-macros-api-name, *name{cl}>> and <<markup-macros-api-text, + *text{cl}>> markup macros instead of the *link{cl} macros, and clarify + that slink{cl} should be used for handle as well as structure names + (internal issue 886). +* 2017-05-08 - Add appendix describing <<appendix-vuid, Valid Usage ID + Tags>> and how they're generated. +* 2017-03-19 - Add naming rule for <<naming-extension-structures, Extension + Structure Names>>. +* 2017-02-11 - Finish transitioning to asciidoctor markup. +* 2016-09-28 - Add asciidoc math markup guidelines. +* 2016-09-16 - Make style guide markup more consistent with its own + recommendations. + Simplify some tables of preferred terms. + Add sections on block and table markup. +* 2016-09-12 - Describe writing and markup style for labelled lists. + Require use of the ISO 8601 date format except in rare legacy cases. + Expand the description of <<markup-layout,Line Lengths>> and add a + description of markup for <<markup-footnotes,Footnotes>>. +* 2016-09-08 - Add a writing section about proper use of + <<writing-misc-a-an,"`a`" and "`an`">> (internal issue 432). +* 2016-08-30 - Remove mustnot{cl} and shouldnot{cl} macro definitions, which + are no longer used in the Specification (internal issue 407). +* 2016-08-29 - Add spelling and compound word rules (public issue 352). +* 2016-08-23 - Modify description of specifying extensions in the + <<extensions,Layers and Extensions>> chapter to refer to the new + single-branch model for extensions (internal issue 397). +* 2016-07-26 - Add section describing <<writing-refpages,markup for + automatic reference page extraction>>. +* 2016-07-18 - Add examples of function-parameter and structure-member + markup (based on public issue 286). +* 2016-07-11 - Change the document title. +* 2016-07-07 - Rename document, change license to CC BY, clarify required + and recommended actions, and reserve use of "`normative`" for the + Specifications. +* 2016-06-26 - Move Layers and Extensions chapter from Appendix C of the + Vulkan API Specification and merge content with the naming guide. + Put extension and naming chapters into their own source files. +* 2016-06-20 - Add API naming guide. +* 2016-05-22 - Add markup and image creation rules, after fixing missing + figure captions for public issue 219. +* 2016-05-01 - Include feedback from public issues 120 and 190. + Use consistent conventions for defining structures. + Use American rather than British spelling conventions. +* 2016-03-12 - Recommend against "the value of". +* 2016-02-26 - Replace use of the "maynot{cl}" macro with "may{cl} not". +* 2016-02-16 - Place asciidoc conversion post-release. +* 2016-02-09 - Added quotation mark convention. +* 2016-02-01 - Add the Oxford Comma section and issue resolution. +* 2016-01-26 - Add bullet-list style description of command parameters. +* 2016-01-11 - Add "`Numbers in Text`" section from WSI work. +* 2015-12-16 - Make "`begin / end`" preferred terms to "`start / finish`". +* 2015-12-15 - Make "`implementation`" preferred term instead of "`system`". +* 2015-12-13 - Add tlink{cl}/tname{cl} macros for function pointer types. +* 2015-12-10 - Initial release for feedback. |