Pretty Registry (for OpenXR and other Khronos standards)

A tool to perform formatting of the OpenXR registry XML, and potentially other registry XML in the future. (Experimental Vulkan support is included.)

It is split into core, which provides utilities and base classes, and openxr which includes the "policy"-related code parts for OpenXR, as well as the entry point.

Building and Running

This uses the .NET 6.0 SDK (formerly known as .NET Core - the cross-platform open source one) SDK to build. That link has instructions to download and install it.

Releases include binaries which only require the .NET 6.0 runtime, not the SDK, and can be invoked just like any other command -- no need for the dotnet commands below. Running either the OpenXR or Vulkan tools with no arguments will show you help text.

NOTE: At least for Vulkan, you do not want to just directly commit the modifications made by the tool: please be selective in what you stage vs revert, using something like git gui, git add -p, or other interactive/graphical/patch-based interface. Some of the hand-formatted XML is better than the automated stuff. OpenXR has now standardized on using the full automated formatting, however.

If you want to improve the tool, keep following these instructions.

If you're on Windows or Mac, Visual Studio can handle this presumably, but I wrote it on Linux using the CLI, so that's the instructions I'll provide.

In a terminal in the root directory of this repo:

dotnet build

will compile it. To run the OpenXR version of the tool from the build tree, you need to specify the project you want to execute (the solution file in this root doesn't know which ones can be executed, nor which one you want):

# Add any arguments after the csproj
dotnet run --project src/PrettyRegistryXml.OpenXR/PrettyRegistryXml.OpenXR.csproj

Similarly, to run the experimental Vulkan version of the tool from the source/build tree, run:

# Add any arguments after the csproj
dotnet run --project src/PrettyRegistryXml.Vulkan/PrettyRegistryXml.Vulkan.csproj

By default, with no arguments you'll see help/usage.

API Docs

The XML documentation comments in the source can be used by your editor, as well as turned into markdown documents:

All assemblies and docs are within PrettyRegistryXml:

PrettyRegistryXml.Core
- Base functionality
PrettyRegistryXml.GroupedAlignment
- Some more fancy alignment
PrettyRegistryXml.OpenXR
- OpenXR frontend - less complete docs but perhaps useful as an example.

When changes are merged into the main branch, these docs are automatically updated and committed, if applicable, so no need to update them yourself.

You can re-generate these locally for your own reference, however, using XmlDocMarkdown by doing the following:

# This script runs the tool through the local manifest.
./Build-Docs.ps1

Release Process

Make sure all changes have been merged to main and GitHub has completed the
automated docs update.
Bump the version number in the <version> tag of Directory.Build.props.
Commit this version bump.
Create a signed tag at this commit: the tag message will be used to create the
release.
Push the branch and the signed tag to GitHub and let GitHub actions create
your release!