KhronosGroup / KhronosGroup/OpenXR-Docs

PDF outline only goes two levels deep, making it harder to navigate through extension chapters

Open
#196 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

synced to gitlab
Dominant language
Python
Stars
181
Forks
74
PR merge metrics
No merged PRs in 30d

Description

Asciidoctor 1.6 (which is currently in use) has an attribute called "toclevels", which sets how many chapter levels will be included in the ToC. It defaults to 2, therefore excluding extension subchapters from both the outline and ToC. While this makes sense for the ToC (which would blow up to even more pages than it already is), it severely limits the outline's usefulness (e.g. to quickly navigate between specific subchapters of extensions).

Asciidoctor 2.0 introduced a separate attribute "outlinelevels" [1]. This would be perfect, however it obviously requires an upgrade to Asciidoctor >= 2.0. I can see there was a problem that prevented the upgrade here, was this ever investigated again? (Or is there a tracking issue to follow?)

[1] https://docs.asciidoctor.org/pdf-converter/2.0/whats-new/#toc-and-pdf-outline

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with specification/Gemfile around the Asciidoctor 1.6 dependency, then review the referenced openxr.Dockerfile line 55 and the linked upgrade problem. Determine whether the dependency can be upgraded without breaking the documentation build, and verify that extension subchapters appear in the PDF outline while the table of contents remains usable.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, ruby
Domain
build-system, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.