Add content and processing requirements for machine-readable toc #371
Conversation
…or a machine-readable table of contents - adds a reference to the new appendix from section 4.7.3. - removes the explicit WebIDL entry for TOC (and its acolytes), in line with the proposal in #338
mattgarrish
requested review from
BigBlueHat,
HadrienGardeur,
deborahgu,
iherman,
rdeltour,
TzviyaSiegman,
dauwhe,
GeorgeKerscher,
GarthConboy,
wareid,
avneeshsingh and
llemeurfr
|
Just a note: as said in the minutes of the 26th of Nov. the issue of whether a TOC in JSON should be added to WP or not will be considered separately. This PR is only on resolutions on that meeting. |
|
The relaxing relative to ol/ul is IMO the most efficient, we heard about many EPUB files presenting this issue. The other evolutions seem ok also, but I have an issue with backward compatibility with EPUB: the WP spec constrains processing Re. details, in the ol/ul spec I see "in this order" -> li (one elt type only), which is not useful. |
You can still provide a top-level heading. That's mentioned both in the content model and in the processing (see the first bullet about obtaining a title for the toc). But spans are problematic to keep if we're loosening the content model and allowing any other tagging to be included. A span could appear for any number of reasons not related to the text label to use, while an It's also technically not incompatible with EPUB, as you can include an |
Ya, that's odd. It's in the EPUB spec that way, but I can strip "in this order". |
|
@mattgarrish ok for the first issue (top-level heading), I missed it when reading. For the second point, I agree that a simple transform ( Therefore I'm ready to approve the PR. |
There was a problem hiding this comment.
I find the approach a bit too ambiguous: defining both the content model and the processing of it as normative makes the whole processing model quite unclear IMO.
I would prefer a more solid "User Agent Processing" section, ideally backed by well-defined terminology (the one used in DOM), then a "HTML Structure" section that is a purely informative guidance for authors.
| elements</a>), user agents can easily differentiate the information they need from any | ||
| peripheral content (asides) or stylistic tagging that has also been added. The table of contents can | ||
| consist of both active links (with an <code>href</code> attribute) and inactive links (excluding the | ||
| <code>href</code> attribute), providing additional flexibility in how the table of contents is |
There was a problem hiding this comment.
I don't think the terminology "active link"/"inactive link" is well-chosen; strictly speaking, for HTML, an a element without an href attribute does not represent a hyperlink.
There was a problem hiding this comment.
Yes, but the html spec wasn't terribly helpful. All it calls them is "placeholders" for links.
| <h3>HTML Structure</h3> | ||
|
|
||
| <p>To optimize the machine processing of an HTML table of contents by user agents, authors SHOULD adhere | ||
| to the following structuring guidelines.</p> |
There was a problem hiding this comment.
If the UA processing section is well defined, this entire section can be made informative, no? I understand the usefulness of author guidance, but do we really need conformance statements?
There was a problem hiding this comment.
It's definitely duplicative.
| <dt><a href="https://www.w3.org/TR/html/sections.html#the-nav-element" | ||
| ><code>nav</code></a></dt> | ||
| <dd> | ||
| <p>A <code>role</code> attribute with the value <code>doc-toc</code> is REQUIRED</p> |
There was a problem hiding this comment.
(this comment only holds if we really want to put this as conformance statements)
what's the meaning of REQUIRED when this whole content model is a big SHOULD?
There was a problem hiding this comment.
I don't think following the suggested practice being recommended has a bearing on there being requirements when you do follow it.
| <ul class="nomark"> | ||
| <li><a href="https://www.w3.org/TR/html/dom.html#heading-content"><code>HTML Heading | ||
| content</code></a> | ||
| <code>[0 or 1]</code></li> |
There was a problem hiding this comment.
what does [0 or 1] mean when we say that other elements or content are allowed? wouldn't it always implicitly be [0 or more], i.e. [optional]?
There was a problem hiding this comment.
This is the "processed model". It's only what you have to include. That's why I put the note at the start that says any other content is allowed. The full content model is the nav element's content model, but that's entirely unhelpful for authoring.
| <li> | ||
| <p>The <code>a</code> element MUST provide a non-zero length text label after concatenation of | ||
| all child content and application of white space normalization rules. If a meaningful label | ||
| cannot be constructed from the text content of the <code>a</code> element — for |
There was a problem hiding this comment.
"meaningful" isn't well defined, which makes this statement ambiguous. Besides, doesn't that contradict the MUST above? ("it MUST be non-empty, but when it is there MUST be an ARAI label")
There was a problem hiding this comment.
Doesn't contradict, no, as you can have a non-zero label that is unintelligible if it depends on visuals, embeded content, etc. But I think we can merge. Either a non-zero label or an aria-label, and also an aria-label when the simple concatenation of the text content would lead to an incomplete representation of the link.
index.html
Outdated
| tree of links can be extracted from it. The root list within the <code>nav</code> element represents | ||
| the root of the tree, and each list item is either a branch (if it contains a sub-list) or a leaf | ||
| (if it contains only a link). The following algorithm describes how to construct this tree. (It does | ||
| not define how the extracted table of contents is presented to users.)</p> |
There was a problem hiding this comment.
I suggest we reuse DOM's tree definition and the Infra standard which clearly define all these terms (tree, descendant, ordered set, etc).
index.html
Outdated
| of <a href="https://www.w3.org/TR/html/dom.html#heading-content">heading content</a>.</li> | ||
| <li>Locate the first descendant list element (<code>ol</code> or <code>ul</code>) of the | ||
| <code>nav</code> element. This list is used to produce the hierarchical tree of links. Any | ||
| subsequent lists MUST be ignored.</li> |
There was a problem hiding this comment.
This list is used to produce the hierarchical tree of links.
the algorithm language could be made a bit more explicit, using constructs like variables and assignments ( "let toc be an empty tree", "append current branch to the children of parent branch", etc, etc.)
index.html
Outdated
| value of the attribute as the label.</li> | ||
| <li>Otherwise, use the <a href="https://www.w3.org/TR/domcore/#dom-node-textcontent" | ||
| >text content</a> [[!DOM4]] of the element as the label.</li> | ||
| </ul> |
There was a problem hiding this comment.
same comment as above: what if we have a link with a described image?
index.html
Outdated
| <li>If the <code>a</code> item has an <code>href</code> attribute, and the destination of | ||
| IRI contained in the attribute is a resource in the <a>default reading order</a> or | ||
| <code>resource list</code>, store the IRI. Otherwise, the node is not linkable and | ||
| no IRI is associated with it.</li> |
There was a problem hiding this comment.
we also need to cover deep links (the URL points to some location within a resource in the reading order)
index.html
Outdated
| </ol> | ||
|
|
||
| <p>If the table of contents <code>nav</code> uses a different content model, processing of it to obtain | ||
| a hierarchy of links is OPTIONAL. In such cases, the user agent MAY simply extract all |
There was a problem hiding this comment.
I'm not a fan of defining this section based on the content model; it would be much clearer and less error-prone the other way around IMO. The above text basically says to UA "you should validate the content model", but the spec doesn't clearly define how.
|
I'll see what I can do to clean up the processing @rdeltour. Then maybe we can get the group to decide on whether to keep the content model stuff or just reduce it to explanation and examples. |
|
Curious to know the use case for providing anchor without meaningful href. |
The two probably most relevant for publications:
There are other cases that aren't particularly relevant to a machine-readable table of contents, like removing the href from the link to the page the user is currently on so that they aren't presented with a redundant link. |
|
The "Childrens Literature" EPUB3 sample exhibits such Navigation Document, with some list items used as "containers" (each with a |
|
@rdeltour made excellent suggestions. This looks really good. |
|
Sorry, I should have mentioned that we've been working on a complete overhaul to use a model like the one defined for the outline algorithm (not to compile a toc from headings or anything like that, but similar in terms of walking over the nodes of the toc nav to extract what is needed). I have that plus a working model of the algorithm almost ready for review, so will hopefully be able to update this PR either tonight or tomorrow. The revisions are ongoing in the toc-algo branch, for those interested, but will be merged into this branch: https://cdn.staticaly.com/gh/w3c/wpub/toc-algo/index.html?env=dev#app-toc-ua |
|
Further to my last comment, I've now pushed the new algorithm for extracting the table of contents: The working implementation of this model is at: At this point, what we'd like to get is feedback on the technical approach, including if there are any obvious bugs in the algorithm. (Especially from anyone who has experience in this kind of extraction, if it needs saying. @danielweck?) Content issues, like the structure of the table of contents, can be taken up later. This update is just a new implementation of the basic list structure parsing we've already agreed on. |
|
(For some reasons, the 'preview' of the original PR has not been updates with the new commit. Look at the date of the draft, it should say 6th of December!) |
|
Hm, looks like I committed to the wrong branch. I wonder what toc-updates was for? |
… adapts the dom-walk approach used in the html outline algorithm
|
Yup, definitely a case of pebkac. That was a stale branch with my pre-squashed work the first time around. Need better housekeeping. Anyway, the preview looks like it's updated now, but the direct links are:
(I'll adjust the urls in the previous comment and get to deleting branches.) |
|
A minor extension: I wonder if keeping, if available, the value of the rel and type attributes of the 'a' element in the generated object wouldn't be valuable, eg, if the target is a media object. |
Those are simple enough to add in, as it's just a couple of additional attributes to inspect on the |
|
Looks good to me! There are still a few issues that are worth discussing further IMO:
But all these can be treated in separate issues 🙂 |
In my view, s/can/should/ :-) (It would be important to have a consistent version in the main branch, allowing further discussions...) |
oh yes, I wasn't aware GitHub comments were also subject to RFC2119 conformance 😁 |
|
In the interest of moving on to more specific issues, and as there hasn't been any new negative feedback, I'm going to merge this PR now. |
This PR contains an adaptation of the EPUB toc rules, but simplified in the following ways:
olorulcan be used to construct the list of links, and can be used interchangeably throughout the tocatag without anhrefattribute can be used for unlinked labelsaria-labelis required for links whose text content is not comprehensible due to images and/or embedded content (removes the more complex rules about title/alt attributes, etc.)Feedback is, as always, welcome from everyone on these changes.
Preview | Diff