// Copyright (c) 2014-2024, The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

= OpenXR™ Documentation and Extensions: Procedures and Conventions
Rylie Pavlik, Kaye Mason, Jon Leech, Tobias Hector
:data-uri:
:icons: font
:toc2:
:toclevels: 3
:max-width: 100
:numbered:
:doctype: book
:imagewidth: 800
:fullimagewidth: width="800"
:cl: &#x3a;

// Various special / math symbols. This is easier to edit with than Unicode.
include::{config}/attribs.adoc[]

:leveloffset: 1

<<<<

include::{config}/copyright-ccby.adoc[]

<<<<

:uri-schema-vulkan: https://registry.khronos.org/vulkan/specs/1.3/registry.html

[[introduction]]
= Introduction

This document contains required procedures and conventions when writing
specifications for new OpenXR APIs, extensions and layers, or related
Khronos documentation such as white papers and tutorials; or contributing to
existing OpenXR specifications.
These are collectively referred to as _OpenXR 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.

It should be noted that the _OpenXR Documentation_ has been branched from
the Vulkan documentation.
A deliberate decision was made to keep the API standards similar, although
this may diverge over time as changes are made to either standard.
The OpenXR version of this style guide is also influenced by the proposal
that was adopted as a starting point for the OpenXR specification.

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.

Unless explicitly stated otherwise, the procedures and conventions must be
followed when making changes or additions to the OpenXR specification.
If you have a strong desire to modify the procedures and conventions, such
changes must be made through the normal OpenXR Working group process.

Note that some conventions in naming and API design that would be relevant
to a user of the standard are discussed in the "Fundamentals" and "Appendix"
chapters of the specification itself.
If a contradiction is found, the specification itself takes precedence, and
normal working group procedures should be followed to correct this style
guide.

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

[[introduction-structure]]
== Document Structure

The style guide is broken into five sections:

* <<naming>> - the required rules for choosing names of OpenXR identifiers
  of all types.
* <<extensions,Extensions and Layers>> - the required procedures for
  creating formal OpenXR extensions and layers.
* <<markup>> - the required and recommended markup style for writing
  asciidoc 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>> - 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.
* <<schema>> - a brief description of the XML registry format as well as the
  declarative schemas and tools available to assist in verification of
  changes.

[[introduction-asciidoc]]
== Asciidoc Markup

OpenXR Documentation is primarily written in Asciidoc, a form of text markup
language.
Specifically we're using the version of Asciidoc that is actively maintained
by asciidoctor, which is documented on its website at
http://www.asciidoctor.org/.

References to the Asciidoctor User Manual are to sections in the document at
http://asciidoctor.org/docs/user-manual/.

Asciidoctor is implemented in Ruby (https://www.ruby-lang.org/), which is
available for Linux, MacOS, and Microsoft Windows.
Multiple preview tools also exist for the language, primarily using
AsciidoctorJ (https://github.com/asciidoctor/asciidoctorj) or asciidoctor.js
(https://github.com/asciidoctor/asciidoctor.js).
In particular, GitHub and GitLab both have asciidoc previews for `.adoc` or
`.asciidoc` files in repositories, and live preview extensions exist for
Chrome and Firefox.

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.

[[iso-8601]]
International Organization for Standardization, _Data elements and
interchange formats -- Information interchange -- Representation of dates
and times_, http://www.iso.org/iso/catalogue_detail?csnumber=40874,
2004-12-01.
Also see https://www.w3.org/QA/Tips/iso-date for colloquial examples.

// Chapters of the text are included below

include::naming.adoc[]

include::extensions.adoc[]

include::markup.adoc[]

include::writing.adoc[]

include::schema.adoc[]

= Still To Be Done

* Something about verb tenses in the writing chapter.
* Something about the use of abbreviations and acronyms.

// Appendices are included below
// Omitted for now because we have no explicit VUID added.
// include::vuid.adoc[]

= Revision History

* 2017-06-14 - Branch from Vulkan Style Guide for initial commit.
  Some basic edits.
* 2017-07-07 - Changing more things to OpenXR examples.
  Adding OpenXR issues in most TODOs.
* 2020-03-12 - Major revisions in preparation for release.
* Other small changes aligning document with working group practice.
* 2021-05-10 - Reference the extension process document on extending
  bitmasks, remove obsolete references to old Vulkan development models.
* 2022-08-26 - Update to reflect Vulkan script sync and moving all generated
  files into a single directory whose path is accessed using the AsciiDoc
  attribute `\{generated\}`
* 2023-03-17 - Clarify that USB vendor ID, not PCI vendor ID, should be used
  in OpenXR.
* 2023-06-15 - Require vendor suffix in interaction profile paths introduced
  by extensions.
* 2023-07-13 - Document standing recommendation to discourage callbacks in
  OpenXR API design, other small changes to align more closely with existing
  working group practice.
* 2023-08-02 - Document the XML schema and how it differs from the Vulkan
  equivalent.
* 2024-04-08 - Document the intentional breaking change in the XML schema
  released with the OpenXR 1.1 specification, bringing our schema back into
  synchronization with the Vulkan specification by removing an outdated
  convention no longer used by Vulkan.
