| // Copyright 2014-2023 The Khronos Group Inc. |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| [appendix] |
| [[revisions]] |
| = Revision History |
| |
| * 2023-10-11 - Add rules for <<writing-titlecase, writing chapter and |
| section titles>>. |
| * 2023-10-05 - Mention that <<extensions-reserving-bitmask-values, bit |
| position 31>> may not be used for enumerated type bitmasks, due to |
| portability concerns. |
| * 2023-07-07 - Remove style guide requirement to |
| <<sample-writing-explicit-vu, not use nested bullet points or other |
| complex markup in a valid usage statement>>, which is now allowed due to |
| toolchain improvements. |
| * 2023-07-07 - Add "`use case`" as <<writing-compound-words, preferred |
| orthography>> (internal merge request 5991). |
| * 2023-07-05 - Change the boilerplate language for `sType` to refer to |
| `VkStructureType` (internal issue 3493). |
| * 2023-06-21 - Remove the style guide advice to keep valid usage statements |
| "`atomic`" with respect to preprocessor directives, as a recent script and |
| validation layer change has enabled preprocessor directives within VUs. |
| In its place, add new advice about making sure all version and extension |
| information is included in the text of the valid usage statement rather |
| than relying on preprocessor directives. |
| * 2023-05-03 - Add <<markup-word-choices, preferred way to write>> "`called |
| _in_ a command buffer`" (internal issue 3480). |
| * 2023-04-30 - Update <<markup-blocks, Blocks>> to remove tilde markup for |
| source blocks inside refpages, and use `[open]`-tagged listing blocks for |
| <<markup-blocks-nested-open, continuation blocks inside refpages>> |
| instead. |
| * 2023-02-26 - update description of computing numeric enumerant values, and |
| reference the normative references section for the registry schema |
| document (public issue 2069). |
| * 2022-11-29 - Add a NOTE to the <<writing-conventions, Use American |
| Spelling Conventions>> section explain why there are a few uses of |
| "`colour`" in the Vulkan Video extensions (internal issue 3254). |
| * 2022-11-16 - Update `basetype` <<markup-macros-api, markup macro>> |
| description to exclude types without definitions in the Vulkan |
| Specification, such as the Video `Std*` types (internal issue 2703). |
| * 2022-11-11 - Add <<markup-word-choices, preferred way to write>> |
| "`_handle_ is not dlink{cl}VK_NULL_HANDLE`" |
| * 2022-10-12 - Add <<markup-word-choices, preferred way to write>> "`_verb_ |
| on the device`", and re-order part of that table (internal merge request |
| 5475). |
| * 2022-09-05 - Refactor markup to separate <<introduction, Introduction>> |
| chapter from `styleguide.adoc` and make anchor naming scheme consistent. |
| Convert <<revisions, Revision History>> from a chapter to an appendix and |
| add an anchor. |
| * 2022-07-14 - Add <<markup-sample-section-features, Feature |
| Cross-References>> section specifying how to mark up API feature links. |
| * 2021-11-21 - Add preferred uses of "`indirect (drawing/dispatching) |
| command`" to the <<writing-compound-words, Compound Words and Preferred |
| Orthography>> section. |
| * 2021-11-15 - Add <<markup-include-file-paths, Include File Paths>> section |
| requiring using full paths to included markup files. |
| * 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 incompatibilities (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 elements 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 are 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. |
| |
| |
| ifdef::VKSC_VERSION_1_0[] |
| == Vulkan SC Revision History |
| |
| * 2019-06-25 - Added <appendix-scid, Safety Critical ID Tags (SCID)>> |
| appendix. |
| endif::VKSC_VERSION_1_0[] |
