// Copyright 2014-2022 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[appendix]
[[revisions]]
= Revision History

* 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.