Ideas for px:html-outline refactoring

[bertfrees]

• px:html-outline is based on the HTML5 outline algorithm, make that more clear in the documentation

  • Add link to the specification: https://html.spec.whatwg.org/multipage/sections.html#headings-and-sections
  • Explain that the outline algorithm was never implemented by assistive software, so it should not be used to convey document structure to users (see https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Using_HTML_sections_and_outlines). The algorithm is however useful for generating a table of contents with the correct outline, or even for renaming the heading elements (to make their rank match their outline depth), and this is exactly what the px:html-outline step does.
  • Describe the algorithm in comments in the XSLT.

• Give the step two outputs:

  • the outline (current output)
  • the (possibly modified) content document

• Step options:

  • Rename heading elements in content document
    • no (current behavior)
    • according to outline depth
    • according to outline depth but as if sections with implied heading were unwrapped
    • rename all to h1 (except secondary headings inside hgroup)
  • Unwrap section elements (section, article, aside, nav) to create "flat" HTML
  • Insert dummy headings in content document
    • yes
    • no (current behavior)
  • Make implicit sections in content document explicit
  • Insert dummy headings in outline
    • yes (current behavior)
    • unwrap sections in outline without heading
    • no, but list nesting should match the outline
    • no, but list nesting depth should match the outline, and merge list items without heading with their preceding sibling item

• Delete nav-fixer.xsl from px:epub3-nav-create-toc and use the new px:html-outline options instead.

• Merge generate-missing-headlines.xsl from the Nordic html-to-epub3 into px:html-outline?

• Merge Jostein's create-hidden-headlines.xsl into px:html-outline?

@josteinaj Does this sound right to you? When this is finished I would then remove the code in html5-to-html4.xsl that deals with heading levels and replace it with a px:html-outline step somewhere.

[josteinaj]

Yes, this sounds right. 👍

[bertfrees]

Fixed by #23.

When addressing one of the items that have not been checked off, create a new issue.