search

KhronosGroup / Vulkan-Site

Vulkan Documentation Project framework for integrated documentation site with spec, proposals, guide, and more
Other
25 stars 2 forks source link

Ability to browse different versions of the spec #9

Open Valakor opened 1 year ago

Valakor commented 1 year ago

It'd be nice to have a dropdown (or other ability) to change which version of the spec I'm currently browsing, perhaps similar to how the existing LunarG (https://vulkan.lunarg.com/doc/sdk/1.3.243.0/windows/getting_started.html) or Python (https://docs.python.org/3/) docs work.

I'm conflicted on whether this should only support major versions (e.g. 1.2 vs 1.3) or if all released SDK's should be available (e.g. 1.3.329 vs. 1.3.243).

As a bonus: It might be interesting to be able to diff two versions of the spec, or have some other way to very easily see a structured list of changes introduced in a specific version.

oddhack commented 1 year ago

Separate versions are a possibility, although we'd really like to get away from publishing (1.0,1.1,1.2,1.3) x (core,KHR,all extensions) specs even in the current monolithic form. There are already comments in the API code blocks saying which versions/extensions provide a given API, but the way in which those annotations are presented could probably be improved. If you have thoughts about that they are welcome.

Supporting many point versions of the spec is a big project with fewer uses, but we'll keep it in mind. Generally the meaningful changes in a point release are to add new valid usage statements, add new extensions, and make minor fixes and clarifications to existing spec language. Sometimes a whole chunk of the spec will get refactored but that's rare.

We have an HTML diff tool that came from the W3C but it doesn't do a great job, and so far I don't know of anything much better though I haven't done an exhaustive search. At best such a tool will generate HTML with areas with changes marked up in some visual fashion and a way to skip between them, which may not have a lot to do with the semantic structure of the changes.

Valakor commented 1 year ago

I think just having the major releases (1.0, 1.1, 1,2, ..., latest) seems reasonable as long as we can expect no major (functional) spec revisions from point releases. That being said, I find it handy that the current docs at least provide release notes summarizing the changes in each point release (especially new extensions).

I think this request just comes from my desire to reduce noise in the spec related to spec versions and extensions that I don't care about (usually because I can't or am not currently targeting said spec version or extensions). The mental burden of reconciling all the different versions and extensions is pretty high as-is, and will only grow as more versions and extensions are added over time.

My ultimate desire would be able to browse the spec at a specific version with a specific list of included extensions that I know I will be targeting. If this were possible, the amount of spec language I need to read would be drastically reduced. For some specific examples:

  1. Say I know I can't or will not be targeting VK_KHR_dynamic_rendering - a huge chunk of the Render Pass chapter in the spec could just be dropped, and any other mentions of this extension elsewhere in the spec (usage statements, etc.) could also removed.
  2. Say I know I will be targeting Vulkan 1.2 - all language mentioning extensions that have been promoted to 1.2 (or earlier versions) could be dropped; same with any language mentioning the (now-deprecated) KHR API's that have been replaced with core API's.
  3. Similarly, any language mentioning the promotion of extensions to newer Vulkan versions (e.g. 1.3) could be dropped.
oddhack commented 1 year ago

It is possible to build the spec with arbitrary combinations of core versions and extensions, but it's a lengthy build process. Originally I thought vendors and middleware providers might want to publish versions of the spec with just the functionality they supported, but it's never worked out that way.

The direction we're heading in now is to stop publishing the existing (12!) different spec variants (1.[0123] x {core, core + ratified extensions, core + all extensions) in favor of just the current core version + all extensions, and if there's demand for it, generate more documentation on how to spin up your own API spec. Eventually we want to retire the current registry HTML spec(s) completely in favor of the Antora site, which will just be 1.3 + all extensions.