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

add section numbers in the spec (at least as optional?) #37

Open dneto0 opened 1 year ago

dneto0 commented 1 year ago

The site looks really nice and is very responsive!

When looking at the spec, I'd like to see chapter and section numbers like in the ordinary rendering of the spec.

  1. I think it's useful when referring to the spec externally, to reference a numbered-and-named section.

  2. It helps keep me oriented. e.g. I know section 14 is descriptors, and section 15 is shader interfaces. :-)

oddhack commented 1 year ago

I'm neutral on this. It would require some work as Antora treats each chapter ('page') as a separate document and does not number them, which apparently is consistent with modern HTML docs practice, but can be done in the conversion script that translates asciidoctor markup to Antora conventions. Chapter / section numbers do change when an extension adds a new chapter, or when a chapter gets split (as we would have to do to address https://github.com/KhronosGroup/Vulkan-Docs/issues/2231).

An advantage of the Antora presentation is that deep links will be much faster as they don't require loading the whole enormous single-page spec document, while page names are stable even across adding new chapters, unlike the 'chunked' HTML build published in the registry today.