KhronosGroup / KhronosGroup/Vulkan-Docs
Make identifying extensions clear
- Dominant language
- JavaScript
- Stars
- 3.3k
- Forks
- 549
- Avg merge
- 5d 5h
- Merged PRs (30d)
- 2
Description
Unlike GL extensions, where all changes that an extension introduces to the spec are presented in a single document, Vulkan extensions are integrated with the spec. There are certainly merits to that, but it's hard to find every place the extension touches, either for an implementation to make sure they have everything covered, or for users to make sure they respect the extension requirements fully.
To improve the situation, I suggest marking paragraphs, sentences, enum values or anything else the extension adds with a small well-formatted tag that can be shrunk or expanded. Something like this for example:
Core specifications on some subject. X requires Y and such.
[-][VK_EXT_something]
When VK_EXT_something is enabled, X additionally requires Z.
More core specifications.
The above `[-]` should be present only in interactive media (for example HTML, and not PDF or man). When shrunk, the core spec would be clear, unencumbered by details from an uninteresting extension:
Core specifications on some subject. X requires Y and such.
[+][VK_EXT_something]
More core specifications.
Note that the `[VK_EXT_something]` tag would likely benefit from having a smaller font. If multiple extensions expose the same thing, `[+][VK_EXT_something][VK_EXT_other]` could be used.
Note also that some times the extension modifies the text like if ext, A B C, if !ext D E F. Toggling the extension should support making D E F visible or invisible based on whether A B C is or not.
For non-paragraph additions, either a small delimiter or some form of extra spacing can be used to identify the end of the addition by extension (especially for the sake of non-interactive formats, as the interactive ones could use other methods, like highlighting on hover):
Core sentence. [-][VK_EXT_something] Extensions sentence. More core sentences.
Core sentence. [+][VK_EXT_something]. More core sentences.
enum VkX
{
VK_X_CORE_VALUE_0,
VK_X_CORE_VALUE_1,
VK_X_CORE_VALUE_2,
[-][VK_EXT_something]
VK_X_STH_VALUE_0,
VK_X_STH_VALUE_1,
[-][VK_EXT_other]
VK_X_OTHER_VALUE_0,
VK_X_OTHER_VALUE_1,
};
enum VkX
{
VK_X_CORE_VALUE_0,
VK_X_CORE_VALUE_1,
VK_X_CORE_VALUE_2,
[+][VK_EXT_something]
[+][VK_EXT_other]
};
Again, the tags should use a smaller font.
The idea here is:
1. It's clear what is introduced due to which spec, which makes it easy to ignore details from extensions that are not interesting. This also makes the two builds of the spec (with or without all extensions) somewhat redundant.
2. It becomes trivial to find all parts of the spec any extension touches, simply by searching for `[VK_EXT_something]`.
Contributor guide
Research direction
No files, tests, or entry points are named. Start by examining how Vulkan extensions are integrated into the specification and how HTML, PDF, and man outputs are generated. Done means extension additions are identifiable and collapsible in interactive output while remaining appropriately represented in non-interactive formats.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 20/100