xml.xproc.html-outline.xpl Maven / Gradle / Ivy
Apply the HTML5
outline algorithm.
Returns the outline of a HTML document and optionally transforms the document in a
certain way in relation to the outline.
Note that the outline algorithm was never implemented in web browsers nor assistive
technology. Therefore it should not be used by authors to convey document structure. The
algorithm is however useful in the context of transformations, for example to generate a
table of contents, or to rename heading elements according to their outline depth.
HTML document
The HTML document from which the outline must be extracted.
Table of contents
A table of contents referencing some sections or headings in the source
document. Only required if the "fix-heading-ranks" option is set to "toc-depth" (and not
more than one document is allowed). The table of contents should be formatted as the
ol element from a EPUB
<nav epub:type="toc"> element.
The modified HTML document.
Depending on the values of the "fix-heading-ranks", "fix-sectioning" and
"fix-untitled-sections" options, heading elements may be inserted or renamed and section
elements may be inserted, but the outline is guaranteed to be unchanged.
All body, article, aside,
nav, section, h1, h2,
h3, h4, h5, h6 and
hgroup elements get an id attribute.
The outline in HTML format
The outline of the HTML document as a ol element. Can be
used directly to include in a EPUB
<nav epub:type="toc"> element.
The raw outline
The unformatted outline of the HTML document as a d:outline
document.
The base URI of the resulting TOC document.
May be omitted if the "toc" output is not used.
Whether the a elements in the "result" output should only reference
heading elements (h1, h2, h3, h4,
h5, h6 or hgroup) or whether they may also
reference sectioning elements (body, article,
aside, nav or section). If this option is set to
"true", "fix-untitled-sections" is "keep" and "fix-untitled-sections-in-outline" is
"imply-heading", the outline will contain generated section titles but they will be
spans, not as.
Whether to change the rank of heading content
elements in the HTML document.
- outline-depth
- The rank must match the outline
depth of the heading (or 6 if the depth is higher).
- toc-depth
- The rank of a heading is set to the number of ancestor
ol elements
of the a element in the "input-toc" document that references the
heading or the sectioning content element associated with the heading. If the
heading is not referenced in the table of contents, the rank is 1.
- keep
- Don't rename heading elements. Default value.
Whether to insert sectioning
content elements.
- outline-depth
- For all nodes, the number of ancestor sectioning content and sectioning
root elements must match the outline
depth. All nodes that belong to a certain section have a single common ancestor
element that wraps that section, or the outline containing that section. This means
that elements in the source that span multiple sections may have to split up in the
result.
- no-implied
- Like outline-depth, but in addition create new sections as needed to get rid of
implied sections completely. Note that this may result in multiple
body
elements or may break the structure or semantics of the document some other
way. This feature is intended for creating an intermediary HTML document that will
be converted further into a format that does not allow implied sections (like
DTBook).
- keep
- Do nothing. Default value.
Whether to generate a heading content
element for sections that don't have one.
- imply-heading
- Insert heading elements. The rank is determined by the "fix-heading-ranks"
option, whereby "keep" is treated as "toc-depth".
- imply-heading-from-aria-label
- Same as 'imply-heading' but only use
aria-label
attributes on sectioning elements to derive the headings from, don't generate
"dummy" headings. The aria-label is replaced with a aria-labelledby.
- keep
- Don't insert heading elements. Default value.
How to handle sections in the outline without an associated heading content
element. Setting this option has no effect if "fix-untitled-sections" is set to
"imply-heading".
- imply-heading
- Generate a heading text for a such sections. This is the default value.
- unwrap
- Replace the sections with their subsections.
px:assert
px:html-add-ids
Add ID attributes
Create the outline