ifdef::env-github[]
:note-caption: :information_source:
endif::[]

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

= OpenXR™ API Documentation Project

This repository contains sources for the formal documentation of the OpenXR
API. This includes:

[options="compact"]
 * the OpenXR API Specification
 * OpenXR header files (generated from the specification)
 * related tools and scripts.

The authoritative public repository is located at
https://github.com/KhronosGroup/OpenXR-Docs/.
It hosts public Issue tracker, and accepts patches (Pull Requests) from the
general public.

== Directory Structure

The directory structure is as follows:

// REUSE-IgnoreStart
```
README.adoc           This file
COPYING.md            Copyright and licensing information
CODE_OF_CONDUCT.md    Code of Conduct
specification/        Specification - files to generate the spec
include/openxr/       Static OpenXR header (not generated from the Registry)
```
// REUSE-IgnoreEnd


== Building the Specification and Reference Pages, and Regenerating Headers

The document sources are marked up in Asciidoctor format, and we use
`asciidoctor` and related toolchain components to generate output documents.
See link:specification/README.md[specification/README.md]
for more information on installing the toolchain and building the
Specification.

== Note about `git blame`

We are tracking "bulk commits" in the `.git-blame-ignore-revs` file, for better
git blame output. Sadly it appears that web interfaces do not yet handle this
file, but you can if using the command line. See
link:https://git-scm.com/docs/git-blame#Documentation/git-blame.txt---ignore-revs-fileltfilegt[--ignore-revs-file docs]
for details, and
link:https://www.moxio.com/blog/43/ignoring-bulk-change-commits-with-git-blame[this blog post about ignore-revs]
for some useful usage details.
