KhronosGroup / KhronosGroup/OpenXR-Docs
PDF outline only goes two levels deep, making it harder to navigate through extension chapters
Nobody has claimed this yet.
- 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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