representation of table of contents in the manifest

[iherman]

(Translating a telco discussion to an issue.)

The current (2018.06.19) draft has a separate term for the ToC infoset item in the manifest, tentatively using tableOfContents. The question is whether:

1. not use a separate term, but use a PublishingLink instance in resources, using (IANA) rel value of contents
2. not have an entry in the manifest at all, relying on the fact that the TOC is already defined as a link to an HTML element with a particular aria attribute value; if the TOC is restricted to such an element in the entry page, it is unnecessary to duplicate the information in the manifest

[iherman]

Arguments in the telco:

• Pro 1: consistency with the rest; we should not pick some special resources for a special treatment. (per @HadrienGardeur)
• Con 1: ToC is probably the most widely used structural term, and it is important to simplify the job of authors as much as we can (per @iherman, with +1 from @buehlerart)
• Pro 2: the ToC is already part of the DOM that has been parsed from the entry page, why duplicating the information (per @BigBlueHat)
• Con 2: It may be restrictive if the ToC is required to be part of the entry page; some may prefer it to be in a separate resource (e.g., it may be generated by some workflow).

[iherman]

(We should try to get to a decision on this via github...)

[HadrienGardeur]

I'm quite concerned about consistency across the board.

When designing such terms, there are two different ways to handle things:

• the JSON approach, where each infoset item has its own term (WAM follows this approach, with icons or screenshots for example)
• a hypermedia approach, where we have a link structure and extension points

So far, we've been fairly close from a hypermedia approach with three collections (readingOrder, resources and probably links/externalResources).
IMO, we can't go half way and decide that for example ToC and cover should use the JSON approach, while privacy policy and metadata records should take the hypermedia approach (rel value and MIME type to identify the resource).

IMO the right approach is to:

• omit the reference to the ToC in the manifest if it's contained in the entry page
• use contents as a rel value if the ToC is contained in a different resource

If the ToC is contained in a different resource from the entry page, the resource will have to be listed in either readingOrder or resources anyway. You might as well include a rel value in there, this is IMO much easier than having a second element for the ToC somewhere else in the manifest.

[iherman]

@HadrienGardeur ie, you propose a mixture of (1) and (2).

I can live with this.

[TzviyaSiegman]

proposed resolution:

• ToC SHOULD be in entry page
• If ToC is in entry it does not need to be in manifest
• Use contents as a rel value if the ToC is in a different resource

[HadrienGardeur]

We might need additional language in the case where an HTML document contains multiple <nav> with doc-toc.

[iherman]

True. But that is true overall: we need to specify what happens at the corner cases. I would propose to have the first draft of the manifest done (@mattgarrish is doing some great editing right now) and then we will have to go through all those systematically and ask/answer similar questions.