Skip to content

#38 Link virtual TOC entries and their targets.

Dennis Hendriks requested to merge 38-asciidoc-fix-virtual-toc-items into develop

Some notes about the merge request:

  • Best to review per commit.
  • Fixed virtual TOC entries linking to the correct targets.
  • Also improved virtual TOC entries/targets naming and styling consistency.
  • Furthermore, fixed highlighting of the home page in the TOC.
  • And some other small improvements. See individual commits.

Some notes about the virtual TOC entries:

  • We have at certain places virtual TOC entries, wrappers that group a number of child pages:
    • Chi documentation: -
    • CIF documentation: SBE (2x), language tutorial (10x), reference manual (2x), tools (6x), simulator (5x)
    • ESCET development documentation: index (1x)
    • ESCET project documentation: -
    • Tooldef documentation: reference manual (2x)
  • These help to structure the pages under them, but are not actual sections (headings) on pages after splitting to multi-page HTML. Hence, they don't link to anything that exists.
  • Potential solutions are:
    • Make them real sections. But, the whole point was to have them be wrappers that only exist in the TOC. If they are sections/headings on the page, and there are multiple of them, you'd get them in the TOC, but the actual pages that they contain after all of them, as you can't mix sections and pages.
    • Make them real pages. But, then the page needs content. This would lead to duplication, as we would need to duplicate the list of child references on the overview page and each virtual TOC entry turned new page. This would be annoying to maintain. Also, having the lists twice is not very intuitive to the user when navigating.
    • Have no such wrappers. But, then we get larger groups of child pages directly under other pages. This is more difficult for users to grasp. It hinders navigation. We have the wrappers for a reason.
    • Somehow relate the virtual TOC entries to their intended targets. Give the TOC entries and their targets relatable IDs (virtual-toc-entry--<something> and virtual-toc-target--<something>). This will work as desired, at the cost of an extra naming convention and some code in the multi-page HTML splitter to make it work.
  • I opted for the last solution, as that is best for end users.

Addresses #38

Merge request reports