whatwg
Table of contents issue. Orphaned elements.
In the developer's edition, when looking at the table of contents (https://html.spec.whatwg.org/dev/) there exists "4.8 Embedded content". Clicking through takes you to https://html.spec.whatwg.org/dev/embedded-content.html#embedded-content ...
On that page the section table of contents is listed as ...
4.8 Embedded content
4.8.1 The picture element
4.8.2 The source element
4.8.3 The img element
... but there also exists the page https://html.spec.whatwg.org/dev/media.html, which has a section table of contents listed as ...
4.8.9 The video element
4.8.10 The audio element
4.8.11 The track element
4.8.12 Media elements
4.8.12.1 Error codes
[etc...]
That is, this page https://html.spec.whatwg.org/dev/media.html, is not linked to from the front page table of contents (https://html.spec.whatwg.org/dev/). In that sense media.html, and the embedded elements it lists, is orphaned.
Wow, great find. /cc @sideshowbarker. This happens because the TOC only displays two levels deep, but we've cut up that second-level section (4.8 Embedded content) into multiple pages from the multipage edition. The only way you can really access them is via the next/previous buttons on each page. This probably occurs multiple times.
I wonder if we should just expand the TOC to three levels. This is related to https://github.com/whatwg/html/issues/2793.
Alternately we could say it's OK that there are pages you can only access via next/previous? That seems kind of bad though...
This probably occurs multiple times.
So it seems. You can't get, for example, to https://html.spec.whatwg.org/dev/input.html from the front page. You have to jump to https://html.spec.whatwg.org/dev/forms.html#forms and from there click on the (in effect) next button "4.10.5 The input element →" (as you observe above).
I think the possible solutions are:
- (As you mention) "say it's OK that there are pages you can only access via next/previous". I agree this is bad.
- (As you mention) Expand the TOC to three levels.
- Include more level 2 headings.
- Some combination of 2 and 3.
A separate but related issue that the section groupings could probably use some reorganizing for conceptual reasons. E.g. There's a page, https://html.spec.whatwg.org/dev/iframe-embed-object.html, listing
4.8.5 The iframe element
4.8.6 The embed element
4.8.7 The object element
4.8.8 The param element
... perhaps those should be grouped under a new title that properly reflects what they have thematically and uniquely in common (if they don't have anything thematically and uniquely in common they shouldn't be on a page by themselves).
Another example, is the page https://html.spec.whatwg.org/dev/media.html, which, looking at the file name would suggest it is a page about media elements. Yet we have on that page ...
4.8.9 The video element
4.8.10 The audio element
4.8.11 The track element
4.8.12 Media elements
4.8.12.1 Error codes
[etc...]
... a section "4.8.12 Media elements" which should be better titled "Media element usage" (or some such). For video, audio, and track are media elements and might feel excluded given that "4.8.12 Media elements" won't have them.
Solving the TOC issue probably best starts with this conceptual reorganization. That would require courage, as the extreme programming paradigm likes to identify it.
(if they don't have anything thematically and uniquely in common they shouldn't be on a page by themselves).
The issue here is that the groupings are partially governed by size reasons, not necessarily thematic ones. I think the best thematic groupings are already given by the second-level headings, but those just lead to enormous pages that are not fun to scroll through. Thus we broke them up.
Thus I don't think we are really in need of any conceptual reorganization here, and it's just a UI issue with some mismatches about expectations of how the TOC works.
I can definitely see the motive for wanting to chunk stuff into small pages. Generally a good thing for reading reasons. I'm not sure size groupings should override thematic groupings, however.
By way of comparison the current state of the W3C "4.7 Embedded content" page https://www.w3.org/TR/html5/embedded-content-0.html. It is quite long and, at the very least, no sections are orphaned. I don't find this page bad, despite its length: as a reference work it's just a matter of clicking the relevant link at the top of the page to jump to the relevant section on the same page.
On the issue of a conceptual reorganization: I think the onus would be on me to make a stronger case (which you may still wish to reject) by providing specific alternatives. Just to share: I'm writing my own HTML reference, largely tracking the WHATWG and/or W3C specs. I do this for most tech languages/platforms I learn: as a learning process. The resulting reference is idiosyncratic: so it's not necessarily readable by others. Nevertheless, as I progress through it specific alternative groupings might arise that are also shareable. In that case I might share them :)
But I think it's enough for now for me to have flagged the orphaned elements/orphaned sections issue and I'll leave that in your hands.
Thanks for your prior work on the spec!
So after some time my preferred solution to both this and #2793 is to just make the index page list the full TOC, with no omissions or collapsing UI or anything. I think that will be the best solution in the end.
Part of the issue there is styling, as the current layout aligns by section number which doesn't quite work with more nesting. It will probably require some small HTML tweaks which have to be done to the preprocessor. But, at least we have a plan...
Yes I think a full TOC, at the index page https://html.spec.whatwg.org/dev/, sounds necessary to tackle the problem. Yes I don't think a collapsing UI would add much value (edit: or at the very least a simple static TOC would be the worth publishing as a first step ... from there it would become clearer if a collapsible UI would be of value).
An additional thing that could be done for content articles is to take a cue from the W3C in having article relevant TOC as a side bar. As on https://www.w3.org/TR/html52/semantics-embedded-content.html.