Navigation bar in HTML version of SYCL spec

[mkinsner]

I find it difficult to quickly navigate the rendered SYCL HTML spec because the navigation pane is fully expanded in its hierarchy. This is very noticeable when working with the SYCL-reference WIP, where the sphinx-rendered HTML has a collapsible hierarchy which defaults to fully collapsed.

Unless I'm missing some way to get better navigation within the SYCL HTML spec render, we should improve this soon. A collapsible nav pane hierarchy defaulting to fully collapsed state is an obvious step forward.

[mkinsner]

Vulkan limits the TOC/navigation pane to only two levels of subsection being displayed. That may be sufficient for SYCL

[tomdeakin]

The latest Vulkan spec pages are new rendered with Antora. They made the switch relatively recently. I think we use a different approach for SYCL currently, but moving to Antora is possible.

[gmlueck]

@oddhack do you know of a way to get asciidoc to render the table of contents in a "collapsed" state by default? Currently, the SYCL spec renders the TOC fully expanded. In the PDF render, there are controls that let you collapse each level of the TOC, but all levels are expanded when you first open the document. In the HTML render, there are no controls at all to collapse the TOC.

[gmlueck]

Vulkan limits the TOC/navigation pane to only two levels of subsection being displayed. That may be sufficient for SYCL

I think limiting the TOC to 2 levels would make things worse because the sub-sections in SYCL are quite large. For example, the sub-section 4.9 "Expressing parallelism through kernels" is 65 pages long in the PDF render. With a 2-level TOC, I'd have to scroll down 60 pages to get to the start of the sub-sub-section 4.9.5 "Specialization constants".

[mkinsner]

Vulkan limits the TOC/navigation pane to only two levels of subsection being displayed. That may be sufficient for SYCL

I think limiting the TOC to 2 levels would make things worse because the sub-sections in SYCL are quite large. For example, the sub-section 4.9 "Expressing parallelism through kernels" is 65 pages long in the PDF render. With a 2-level TOC, I'd have to scroll down 60 pages to get to the start of the sub-sub-section 4.9.5 "Specialization constants".

I agree that 2-level isn't perfect. But it would be better than what we currently have. Collapsed by default would be better, but I haven't found an easy solution there yet. Maybe @oddhack has run into solutions before.

[Pennycook]

I think limiting the TOC to 2 levels would make things worse because the sub-sections in SYCL are quite large. For example, the sub-section 4.9 "Expressing parallelism through kernels" is 65 pages long in the PDF render. With a 2-level TOC, I'd have to scroll down 60 pages to get to the start of the sub-sub-section 4.9.5 "Specialization constants".

I know this wouldn't be a quick fix, but is this a sign that we should perhaps be trying to flatten the specification?

Section 4.9 doesn't have any text in it (i.e., Section 4.9.1 appears immediately). Is the grouping useful?

There are also some very small sections that are very deeply nested (e.g., Section 4.7.6.9.4.2. "Discard access modes" contains one sentence).

[oddhack]

@mkinsner it is not supported OOTB, but it's possible to inject a script that will do accordion ToCs. I have not looked at this for years, but Part 1 is modifying the build to include the script loading - see https://docs.asciidoctor.org/asciidoc/latest/docinfo/ - and Part 2 is finding a suitable script. This is a very old thread but may be useful: https://discuss.asciidoctor.org/Collapsable-Expandable-TOC-td789.html#a8227

[mkinsner]

should perhaps be trying to flatten the specification?

I considered suggesting this, but was worried that external sources might reference "section x.y.z..." in the spec, particularly when referencing/linking the PDF version. Maybe that's not a concern, or maybe this is something to do with a future major revision of the spec.

[oddhack]

Related, both Antora and the current 'chunked' Vulkan spec build (which is just a postprocess run on the monolithic HTML doc) break it into file-per-chapter HTML and add a Lunr-based searchbox. Searching is often a helpful alternative to ToC.

I've never been attached to fixed section numbers. The Vulkan spec evolves too frequently for "x.y.z" references to remain valid for any length of time, mostly due to extensions which add chapters and sections but even w/o that, there are occasional big refactorings. In Antora you don't even get section numbering OOTB and I think other contemporary web docs often do not have it either.

[mkinsner]

The SYCL spec is large enough that we should also consider one of those approaches (Antora or chunked) to help with load and search times. Unless we can commit to Antora soon, though, I think we need to solve the massive fully expanded ToC problem first.

One path might be to collapse/rework hierarchy in the sections that become too long without a third level, and then limit the ToC expansion to two levels. That would substantially improve usability, with probably only minor section renumbering. This seems more efficient than injecting a script, unless we're too opposed to some hierarchy tweaking in the spec.

[oddhack]

I recommend holding off on Antora a while. Vulkan is just partway through rolling it out and we are learning stuff as we go that hopefully can be applied more broadly. The chunked approach is a trivial addition to the existing build.

[oddhack]

Here's the issue I referred to years ago when prototyping this for Vulkan: asciidoctor/asciidoctor#699 . See internal vulkan/vulkan MR 2070 for my attempt at the time, but this is way out of date WRT the spec, the asciidoctor implementation, and the ToC script in the github issue, so is probably worse than useless as a reference.

[keryell]

I was the culprit to have the full expansion of the TOC because I did not want to hide anything.
Of course, a better solution is always welcome.

[gmlueck]

I implemented an Asciidoctor extension and associated CSS styling to make the TOC expandable / collapsible in the HTML output. I proposed we do this instead. See #560.