Dual-approach for the TOC

[HadrienGardeur]

As a follow-up to our discussions at TPAC, I think it's worth re-opening the case of the dual-approach for the TOC.

While this idea was proposed before (https://github.com/w3c/wpub/issues/291#issuecomment-416344052, https://github.com/w3c/wpub/issues/291#issuecomment-416352888, https://github.com/w3c/wpub/issues/291#issuecomment-416356123), it still seems very relevant following comments from Penguin Random House and Hachette Livre (respectively the largest trade publishers in the US and in France) that this is how they're producing EPUB files today.

If my understanding is correct (cc @laudrain and @liisamk) this is how they handle their EPUB production today:

• a navigation document (machine readable TOC) is produced but excluded from the reading order, it is only meant to be parsed and not displayed directly
• a more visually rich TOC is created separately, included in the reading order but it's not identifiable as such

Our current attempt in EPUB and in this group to use the same document for rendering and machine readable info still feels like a dead end IMO. No matter how we define an algorithm for extracting the TOC, we always reach a limit where things eventually fail. Publishers might also decide that they want a radically different navigation (for example a map as an SVG) or add a lot of additional information that should not be processed (@liisamk mentioned such examples at TPAC).

This makes me wonder if we're not trying to use the term TOC for two separate concepts:

• a machine-readable document, mean to be processed by UAs to facilitate navigation
• a (potentially) visually-rich document, primarily meant to look good to the reader and that isn't necessarily text-based

While some publications may be able to use the same document for both purposes, I don't think that's true for all publications, far from it (as we can see with content produced by some of the largest trade publishers).

I've updated an earlier example to further illustrate how this could work:

• Entry page
• Manifest
• TOC

The idea is fairly basic:

• the machine readable TOC is identified by the contents rel value
• the "visually rich" navigation document is identified by the navigation rel value

The UAs could potentially do the following:

• provide the ability to jump to the "visually rich" navigation document
• parse and use the content of the machine readable document in its own affordances
• if the machine readable TOC is the only one present but can't be parsed, it would be rendered instead
• if both are presents and the machine readable document can't be parsed, the visually rich document would be rendered instead

[iherman]

Is there (should there be?) an equivalent to the doc-toc ARIA attribute that we would use for the visually rich navigation document?

[HadrienGardeur]

@iherman I haven't looked into it yet but it's not clear that something else than doc-toc would be needed.

[laudrain]

The answer is no, neither in Digital Publishing roles nor in ARIA roles. But that is normal as role is for accessibility not for semantics.

[liisamk]

Hadrien-

You are correct that Hachette and PRH are both creating two docs with somewhat different purposes. This summary explains the goals/issues we have at PRH and I suspect is similar to what the experience is for Hachette or other Trade and Educational publishers.

• The navigation doc/machine readable TOC is meant to be as rich as possible and help a reader easily navigate through the text

  • It often has more levels of navigation than would exist in print
    • Examples: recipes, charts, subheads/sections within business books
  • Current issues:
    • There is not consistent support for 3 or more levels across reading systems
    • We would love to have support for a minimal amount of styling- essentially Bold and Italic so that we can call out Titles of other works

• A more visually rich TOC that is often more of an introduction to the book and its content

  • This may have more explanatory text that is not in the navigation
  • It may be a higher level and not have as much detail as what is in the navigation
  • It may be illustrated or even pictoral
  • It may not exist in the digital product because it was not included in print
  • It is typically identified in the guide with a type=”toc”
  • It is included in the spine

I think it is rare that you would want to use the same doc for both of these purposes.

Let me know if it would help to have examples to see how this works.

Thanks!

Liisa

From: Hadrien Gardeur notifications@github.com Reply-To: w3c/wpub reply@reply.github.com Date: Tuesday, October 23, 2018 at 3:42 AM To: w3c/wpub wpub@noreply.github.com Cc: "McCloy-Kelley, Liisa" lmccloy-kelley@penguinrandomhouse.com, Mention mention@noreply.github.com Subject: [w3c/wpub] Dual-approach for the TOC (#350)

As a follow-up to our discussions at TPAC, I think it's worth re-opening the case of the dual-approach for the TOC.

While this idea was proposed before (#291 (comment)https://github.com/w3c/wpub/issues/291#issuecomment-416344052, #291 (comment)https://github.com/w3c/wpub/issues/291#issuecomment-416352888, #291 (comment)https://github.com/w3c/wpub/issues/291#issuecomment-416356123), it still seems very relevant following comments from Penguin Random House and Hachette Livre (respectively the largest trade publishers in the US and in France) that this is how they're producing EPUB files today.

If my understanding is correct (cc @laudrainhttps://github.com/laudrain and @liisamkhttps://github.com/liisamk) this is how they handle their EPUB production today:

• a navigation document (machine readable TOC) is produced but excluded from the reading order, it is only meant to be parsed and not displayed directly
• a more visually rich TOC is created separately, included in the reading order but it's not identifiable as such

Our current attempt in EPUB and in this group to use the same document for rendering and machine readable info still feels like a dead end IMO. No matter how we define an algorithm for extracting the TOC, we always reach a limit where things eventually fail. Publishers might also decide that they want a radically different navigation (for example a map as an SVG) or add a lot of additional information that should not be processed (@liisamkhttps://github.com/liisamk mentioned such examples at TPAC).

This makes me wonder if we're not trying to use the term TOC for two separate concepts:

• a machine-readable document, mean to be processed by UAs to facilitate navigation
• a (potentially) visually-rich document, primarily meant to look good to the reader and that isn't necessarily text-based

While some publications may be able to use the same document for both purposes, I don't think that's true for all publications, far from it (as we can see with content produced by some of the largest trade publishers).

I've updated an earlier example to further illustrate how this could work:

• Entry pagehttps://hadriengardeur.github.io/webpub-manifest/examples/why/
• Manifesthttps://hadriengardeur.github.io/webpub-manifest/examples/why/wp.json
• TOChttps://hadriengardeur.github.io/webpub-manifest/examples/why/toc.html

The idea is fairly basic:

• the machine readable TOC is identified by the contents rel value
• the "visually rich" navigation document is identified by the navigation rel value

The UAs could potentially do the following:

• provide the ability to jump to the "visually rich" navigation document
• parse and use the content of the machine readable document in its own affordances
• if the machine readable TOC is the only one present but can't be parsed, it would be rendered instead
• if both are presents and the machine readable document can't be parsed, the visually rich document would be rendered instead

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://github.com/w3c/wpub/issues/350, or mute the threadhttps://github.com/notifications/unsubscribe-auth/AZh2yeXHG1SNENkxC30TNMyDZRuUfjaSks5unshogaJpZM4X051d.

[HadrienGardeur]

Thanks @liisamk this is very helpful.

@laudrain @liisamk do you have examples that could be publicly shared with this group? This would be very helpful to further illustrate and understand this use case.

[...] It is typically identified in the guide with a type=”toc”

There's no equivalent currently for the guide and its various types in WP. If some of them are useful (which seems to be the case here), we would need to either identify or define equivalent rel values.

[iherman]

@HadrienGardeur,

I haven't looked into it yet but it's not clear that something else than doc-toc would be needed.

At the moment, the draft uses a two-step approach for the TOC (and the page list). First, the (PublicationList) entry in the reading order or the resources identifies a resource using the rel value, but the URL in the PublicationList does not contain a fragment. As a second step, the TOC or pagelist is identified through a required doc-toc (resp. doc-pagelist) value for the role attribute.

Ideally, a similar mechanism should be used to identify the rich navigation element, but, as @laudrain said, there is currently no ARIA value to be used. There may be two ways to move forward:

1. we relax the current mechanism and allow for fragment URL-s to be used in PublicationLink (which may generate issues elsewhere, because we loose the feature whereby the same resource cannot be repeated in the union of the resource list and the reading order).
2. we use a different identification mechanism to find the navigation element (e.g., use of a special class attribute value, brrrrrr:-(. However, I would argue that the same approach should be used for all three such 'identification', ie, TOC, pagelist, and navigation, ie, such changes may have to be retrofitted to the other two.

(I do not have a very strong opinion on which of these two should be used, just listing them.)

Looking ahead, it is also not clear what the WebIDL representation should be. At the moment, we use HTMLElement for the TOC and the pagelist as a direct attribute value (or, depending on the outcome of #338, as a return value for a helper method) but this would probably change to return the result of JuansAlgorithm. I do not presume the navigation would have such algorithm. (A possibility is to leave it as an HTMLElement, or not to define a helper function if that is decided in #338.)

[HadrienGardeur]

@iherman

I'm not entirely convinced that we need an ARIA role for the visually-rich use case. Currently in EPUB, there's no epub:type for it. It would probably be better in terms of accessibility, but we don't need it for the kind of additional semantics that we require from doc-toc (identifying the HTML element to extract its content).

Defining a rel value would be the equivalent of the guide property that currently exists in EPUB.

Looking ahead, it is also not clear what the WebIDL representation should be.

IMO nothing is required.

I've already said this previously, but duplicating information is not a good thing and since we're not considering making this document machine processable, we don't need a place to store the info once processed.

[iherman]

I'm not entirely convinced that we need an ARIA role for the visually-rich use case. Currently in EPUB, there's no epub:type for it. It would probably be better in terms of accessibility, but we don't need it for the kind of additional semantics that we require from doc-toc (identifying the HTML element to extract its content).

I actually do not necessarily care about accessibility in this case, only a 'sign' that signals that this is a visually rich entry. Please look at my summary of the current process (see above): the role of doc-toc is not used as an accessibility hook, "just" as identification. This is what I am talking about.

I've already said this previously, but duplicating information is not a good thing and since we're not considering making this document machine processable, we don't need a place to store the info once processed.

A visually navigation should be treated like ToC and and the page list. This means that, obviously, results of #338 are relevant for this entry as well. That issue is still open.

[HadrienGardeur]

I actually do not necessarily care about accessibility in this case, only a 'sign' that signals that this is a visually rich entry.

The rel values already handles that: https://github.com/HadrienGardeur/webpub-manifest/blob/gh-pages/examples/why/wp.json#L22

[laudrain]

@HadrienGardeur we have an epub:type for the visual table of content. In Hachette, for EPUB3 today, we use epub:type="toc" in the spine document with the visual TOC. This is not the nav document.

[HadrienGardeur]

@laudrain is there any valid reason not to use doc-toc then?

The two documents would still be properly identified by different rel values in the manifest.

[laudrain]

We map role="doc-toc" from epub:type="toc".

[iherman]

I actually do not necessarily care about accessibility in this case, only a 'sign' that signals that this is a visually rich entry.

The rel values already handles that: https://github.com/HadrienGardeur/webpub-manifest/blob/gh-pages/examples/why/wp.json#L22

Please look at https://github.com/w3c/wpub/issues/350#issuecomment-432508128. The current draft does not allow fragmented URI-s for resources, so the rel value is not enough. Or we have to relax that restriction overall.

[iherman]

@laudrain is there any valid reason not to use doc-toc then?

doc-toc has a specific meaning in ARIA. This may not be valid for the navigation document.

---

There were some discussions at TPAC and it may (I said MAY) be possible that a new, general purpose attribute would be introduced in HTML that does not have the ARIA baggage to it. We could then define terms to be used for that new attribute, and this may solve the issue.

No commitment, though.

[HadrienGardeur]

I'm sorry @iherman but I have a hard time following you on that one.

I'm not suggesting that we use a URI fragment. I simply believe that for "additional navigation" having:

• the rel value set to navigation (TBD) in the manifest (for a resource showing up under readingOrder or resources)
• and optionally, an ARIA role to further identify the nature of the element

... are more than enough.

[laudrain]

doc-toc has a specific meaning in ARIA. This may not be valid for the navigation document.

@iherman I'll check with my DAISY friends

[iherman]

@HadrianGardeur

Indeed, we seem to mutually not understanding one another, as it seems.

In my understanding, this is what you propose:

"resources" : [{
        ...
    },{
        "type":"PublicationLink",
        "url": "http://www.example.org/nav.html",
        "rel": "navigation"
    }],

What happens if there are several nav elements in nav.html? What happens if you have a TOC as well as visual rich navigation element in http://www.example.org/nav.html? How would you find the right navigation element?

Your proposal only works if http://www.example.org/nav.html is only used for (a single) visually rich navigation. I do not think this restriction is acceptable. Alternatively, you have to use http://www.example.org/nav.html#visuallyrichnavigation in the Publication Link. This is against the current draft requirement.

[HadrienGardeur]

@iherman

What happens if there are several nav elements in nav.html?

Since that document is meant to be rendered, I think that's not really an issue. From an affordance perspective, I think rendering the document is enough, no need to jump to a specific fragment id.

What happens if you have a TOC as well as visual rich navigation element in http://www.example.org/nav.html?

They're not semantically the same thing and IMO should be tied to different affordances as well.

In my first post, I suggested the following behavior:

• provide the ability to jump to the "visually rich" navigation document
• parse and use the content of the machine readable document in its own affordances
• if the machine readable TOC is the only one present but can't be parsed, it would be rendered instead
• if both are presents and the machine readable document can't be parsed, the visually rich document would be rendered instead

I'll let @laudrain and @liisamk chime in to make sure that this is aligned with their expectations.

How would you find the right navigation element?

I don't think that's necessary.

To summarize my proposal:

• in addition to the TOC and page list, I'd like to introduce the concept of resources meant for "navigation", a generic solution to cover all other navigation use cases
• unlike TOC and page list, there's no expectation that the UA would process such resources to extract any kind of structure from them
• the only affordance expected from the UA would be to jump at any time to such navigation resources and render them as is

I think this is aligned with a real-world use case, as it's been expressed during TPAC by major trade publishers.

[iherman]

Well... in my view, they way you put it this is grossly underspecified. The only thing we specify is a resource that MAY include several visually rich navigation elements without specifying which one should be used by the UA as part of its specific (and obviously different) affordance for navigation, that MAY be present alongside the navigation meant for specific TOC which may lead to a possible confusion for the UA, etc.

You do not think it is necessary to specify it more precisely, I disagree. At this point we should agree that we disagree, and I let @laudrain, @llemeurfr, @liisamk, and the others decide whether such a loosely specified thing is useful or not.

[laudrain]

In the EPUB real world (the Hachette Livre one at least), we have and need:

• one and only one main visually rich table of content (VRTOC), present on the reading order (spine),
• one and only one machine readable navigation TOC (MRTOC) for a11y (the EPUB3 nav document).

There may be optional sub-tables at specific locations (parts) addressed in the main VRTOC, these are also in the reading order or included in the part documents.

IMO, I don't think useful for user experience to complexify that model with multiple VRTOC and multiple MRTOC.

[llemeurfr]

I'll try to put it differently: this issue seems to me similar to the cover-image vs cover-page issue. A printed book as a cover page, it has a ToC, both can be categorized as "visually rich". A WP-aware UA (i.e. a reading system) needs some machine processable data, as simple to process as possible: a cover image (optional) to be used into a catalog view or a book description; and a ToC (optional but recommended) to be displayed at a fingertip without leaving the current page.

The cover page and visually rich TOC are both usually accessed in reading order. The UA has no real need to get a specific reference to them.

Publishers tell us that this machine ToC is often different from the visually rich ToC (the former is often more complete than the latter). The UA needs a specific reference to the machine ToC and will render it with a UA specific layout (often in a panel). It will use the rel=contents solution and the corresponding structure will get an ARIA doc-toc attribute, because people using specific a11y tools need to access a complete ToC also.

I conclude that using rel=contents is sufficient for publishers and reading system needs, and we don't need to define any rel=navigation for help accessing the visually rich ToC.

And this should bring peace to @iherman and @HadrienGardeur :-)

Same for a page list and other landmarks.

[HadrienGardeur]

@iherman I'm trying to be very pragmatic here and simply stick to the requirements of the industry.

If @laudrain and @liisamk both believe that:

• we don't need an affordance to jump directly to such a "visually-rich" navigation document
• there's no need for additional navigation aside from the machine-readable TOC and the page list

... then I'm happy to close this issue.

[iherman]

Obviously, if publishers do not really need a separate entry in the manifest, then I am fine with closing this...

[avneeshsingh]

Regarding aria doc-toc attribute, it is for both semantics and accessibility (until we have a separate semantics related attribute available in HTML). So, it should be present in both machine readable TOCs as well as visually rich navigation document (if we go on this path) to enable AT recognize that the document provides navigation structure.

[iherman]

This issue was discussed in a meeting.

• RESOLVED: The WP manifest will have a reference to a machine-readable TOC, the draft will have to define the HTML structure for it. The TOC is recommended. There should be documentation in the spec on how that TOC is to be used by Reading Systems and Authors.
• RESOLVED: close issue #350, possibly replace it with a more general notion of landmarks
  View the transcript

  TOC
  Wendy Reid: https://github.com/w3c/wpub/issues/291
  Wendy Reid: https://github.com/w3c/wpub/issues/350
  Wendy Reid: As mentioned in the agenda, we’re going to talk about TOC again. As mentioned, as part of the new system, a short-ish explainer about TOCs and what we want to propose to the group. the TOC issue has been dragging on for a while. But it’s time to come to an agreement, even if it’s a basic definition.
  … In looking over the comments, we’re in more-or-less consensus over a few things. We can go between a limited HTML TOC with a subset of HTML (undetermined) such as the epub3 spec, or our full HTML TOC as identified in the manifest that contains everything and the UAs will have to parse whatever it is.
  … There is a 3rd, a data TOC that’s in JSON in the manifest, but the core is really around the first two options. Comments?
  … 291 is about a more detailed definition, 350 is more about the TOC
  Benjamin Young: I asked this a couple weeks ago - do we have use cases or explanations about why the TOC must be machine readable? It seems unrelated to the ability to access it from anywhere. It has it’s own sense of requirements. Is there a use-case approach?
  Deborah Kaplan: While we might not have formal use cases, there are tons in the comments about them being machine readable. At this point, i’d really vote for saying ‘we have discussed this into the ground’ There are a couple of proposals, none make everyone happy, but a couple proposals that are in the tickets make people ‘tolerate’ them.
  Tzviya Siegman: https://w3c.github.io/dpub-pwp-ucr/#tableofcontents
  Deborah Kaplan: I would be much more in favor of voting on some of the proposals. Discussion will not be needed, I think it’s just time to vote and we’ll figure out the best possible option.
  … There might still be some unresolved issues, but we can’t just keep talking.
  Ivan Herman: I just want to emphasis one thing, the proposal is to be able to have both - and it’s up to the author to choose either a structured HTML/machine readable stuff, or a fully HTML, or both or the two… That goes in the direction of Deborah, but if we discuss, we’ll never close this.
  Tzviya Siegman: Link to the UC document where this is address has been linked
  Deborah Kaplan: What I will say that should make most people tolerate - if the spec allows both (one or the other) and then there are 2 sets of docs NOT in the spec, that are very clear. One for reading system creators - here is what you must do in the presence of one or another - and one is for creators that says ‘here are the cases where you will use one/neither/both’
  … As long as we document the solution, I think we can all live with this
  Wendy Reid: +1
  Wendy Reid: Do we allow for both, and do we provide information to reading systems and content creators on how to use them, or do we only allow one in the spec?
  Jeff Buehler: +1 to the dual solution
  Ivan Herman: +1 to both
  Nick Ruffilo: +1 both
  Ben Schroeter: +1 both
  Luc Audrain: +1 to dual
  Laurent Le Meur: +1 for both
  Ric Wright: +1 to both
  Wolfgang Schindler: +1 dual option
  Romain Deltour: ±0
  Evan Owens: +1 to both
  Benjamin Young: +0
  Tzviya Siegman: +1 with extremely explicit documentation
  Deborah Kaplan: +1 with documentation for user agents and for content creators
  Ivan Herman: Lets get the proposed text exactly then, as a resolution
  Tzviya Siegman: It could be just a document in the publication…
  Garth Conboy: On the visual TOC that we have talked about, that would be pointable in the manifest, is that true or false?
  Tzviya Siegman: Pointable to as it is explicitly the TOC, or that it’s the document?
  Garth Conboy: That it is identifiable as the visual TOC, so that if you provided neither of the other options, the reading systems could then bring this up.
  Tzviya Siegman: My opinion is that it shouldn’t have a special marking. Letting reading systems have so many fallbacks seems unnecessary
  Evan Owens: Visual TOC - is that what’s in a printed book? Are these two options different from that? Calling it all TOC is confusing. Manifest or web navigation makes it clearer. Is this separate from the text of the table of contents?
  Ivan Herman: There is in the explainer, what we call the structured TOC, which is the machine interpretable HTML structure, which usually is a TOC that you refer to. What we call the visual TOC is usable for the User Agent, but we don’t talk about how it’s built up, layered, and there we some notes that it could have SVG with all sorts of items or an image map, but which we don’t say anything about that
  … As for what tzviya was saying, the manifest would show a machine readable version, but it would be having the identification of a visual TOC - is also something we may want to have. As duga said, i’m not laying down on the road over this. I’m saying give the option that if you want to have a TOC visually displayed, you can. That was my feeling.
  Deborah Kaplan: I just wanted to say there are two separate issues - ‘how is the navigation going to be encoded’ and then there’s the question of ‘what happens for visual navigation’ machine VS human readable. I think that will be a 2nd ticket with how the documentation will be.
  … We need to know if you’re not using a WP compliant reading system, etc, but i think it’s different.
  Wendy Reid: NickRuffilo: Is our TOC the solution for reading order, is having a logical readingOrder part of the MVP?
  Wendy Reid: Ivan: ReadingOrder is separate to TOC
  Wendy Reid: NickRuffilo: I am always thinking of how to get rid of redundant information, having a TOC with reading order in it, is it necessary?
  Tzviya Siegman: A long time ago we agreed to separate TOC and reading order. I liked the direction deborah was going in - to separate navigation and visual. I thought we got to the point where we reached a vote. maybe we want to go back there
  Deborah Kaplan: Please - lets not discuss, lets vote, then create new topics on the unresolved issues.
  Proposed resolution: the WP manifest does have a reference to a machine resolvable TOC; the draft will have to define the HTML structure for it. The TOC is optional. (Ivan Herman)
  Avneesh Singh: For the accessibility - identifiability of TOC is very important for accessibility needs.
  Garth Conboy: How does that proposed text match with the ‘dual’ option above?
  Ivan Herman: I think we should separate those two things.
  Proposed resolution: the WP manifest does have a reference to a machine resolvable TOC; the draft will have to define the HTML structure for it. The TOC is optional. There should be documentation (possibly separate from the WP draft) on how that TOC is used be RS-s and authors (Ivan Herman)
  Tzviya Siegman: A few comments: I don’t recall why we have the TOC as optional, but that troubles me. I would like to take out the parenthetical.
  Matt Garrish: Is it optional or recommended. We don’t have an optional - is it still a should?
  Deborah Kaplan: As for optional, if it is not present, our documentation for reading systems needs to say what happens. For accessibility reasons, in the absence of explicit navigation, the reading system will have to create navigation implicitly. So if we make the TOC we will need to clearly document for both reading systems and content creators what is the implicit behavior in the absence of explicit navigation.
  Garth Conboy: If that was the proposed language, i’d give it a +1. I know you wanted to separate the issues, what the other issue in the dual approach
  Ivan Herman: the other one is if the manifest should have a separate preference to a visual TOC.
  Garth Conboy: Thank you. I just wanted to know if the other was JSON or not, but it’s not…
  Wendy Reid: Yes, that’s a separate issue.
  … If we can decide on this, then we can log issues on the TOC for further changes.
  Ivan Herman: I think the reason goes that the reading order … it’s important do document, but it’s important we don’t say must. Recommended sounds like a sound argument.
  Proposed resolution: the WP manifest does have a reference to a machine resolvable TOC; the draft will have to define the HTML structure for it. The TOC is recommended. The should be documentation on how that TOC is used be RS-s and authors. (Ivan Herman)
  Garth Conboy: The proposed, most recent - change resolvable to readable, then drop the parenthetical?
  Proposed resolution: The WP manifest will have a reference to a machine-readable TOC, the draft will have to define the HTML structure for it. The TOC is recommended. There should be documentation in the spec on how that TOC is to be used by Reading Systems and Authors. (Wendy Reid)
  Garth Conboy: +1
  Ivan Herman: +1
  Nick Ruffilo: +1
  Tim Cole: +1
  Jeff Buehler: +1
  Matt Garrish: +1
  Brady Duga: +1
  Joshua Pyle: +1
  Wolfgang Schindler: +1
  Tzviya Siegman: +1
  Juan Corona: +1
  Deborah Kaplan: +1
  Ric Wright: +1
  Avneesh Singh: +1
  Luc Audrain: +1
  Ben Schroeter: +1
  George Kerscher: +1
  Romain Deltour: +0.5
  Mustapha Lazrek: +1
  Benjamin Young: +0
  Teenya Franklin: +1
  Dave Cramer: +0.5
  George Kerscher: If there’s only 1 document in the publication, the reading order is defined by that one thing, so the reading order must be defined, even if only one document?
  Ivan Herman: That’s already in the spec.
  Romain Deltour: I’m just wondering what we mean by there “should be” spec. My thinking is that the way we define the HTML structure, if we are to define how reading systems are using it, thats the part of the spec that matters.
  … How the reading systems are interpreting this HTML structure.
  Wendy Reid: This was the documentation proposed by Deborah as to using one method VS the other, one for RS one from authors.
  Tzviya Siegman: +1 to romain
  Romain Deltour: I think this documentation should be in the spec and not just documents. So it should be how the RS uses the TOC structure.
  Wendy Reid: Which is why we specified it should be in the spec.
  Tzviya Siegman: I agree with Romain, but I think we should have documentation for authors so that it’s clear for them how they should be creating things. We want to let both reading systems and Authors know what to do.
  Wolfgang Schindler: +1 to Tzviya’s proposal of a documentation for authors!
  Resolution #2: The WP manifest will have a reference to a machine-readable TOC, the draft will have to define the HTML structure for it. The TOC is recommended. There should be documentation in the spec on how that TOC is to be used by Reading Systems and Authors.
  Wendy Reid: Resolved, I haven’t seen any -1s.
  Ivan Herman: I think that is the other option on the table, we should once and for all say yeah or nay
  Proposed resolution: the wp manifest will have a reference to a TOC which is not defined to be machine-readable. Such a TOC is optional (Ivan Herman)
  Wendy Reid: NickRuffilo: Do we want to add something saying it is defined in some way?
  Wendy Reid: Ivan: It can be an image, SVG, etc
  Wendy Reid: NickRuffilo: We should have a way to identify it
  Brady Duga: My question is - is this visual TOC different from other things we might identify, such as ‘where is the reading start’ or other interesting points. Is this visual TOC one of the many things we might want to point to, or an extra special thing (or only thing)
  Matt Garrish: I’m just wondering if this is even necessary. What’s the difference between a visual TOC and machine readable. The reading system needs to make a determination about the usability of the TOC. Do we just have two different semantics when we could just have 1. If the RS can’t parse it, it can’t parse it.
  Ivan Herman: Responding to Brady, if we do this, it is one of those that you refer to. We have the structure that if we have resources listed in the manifest, we can add additional things as part of the rel value. There would be a rel value for ‘visualTOC’ there might be other requirements for different types. Structurally it’s exactly the same.
  Brady Duga: it feels like this answers Matt’s question, it isn’t two ways to display the TOC, it’s two different things. A machine readable TOC, and things that are interesting. As just one thing among many, but it is odd to vote on it separately, that’s odd. Do we want to have a way to note interesting places
  Ivan Herman: we do have things like cover, description, and we already have one of those ways to describe important things.
  Garth Conboy: I like that answer - if the machine readable part was a TOC, but if it didn’t have a machine readable thing, it would just flip to it…
  Tzviya Siegman: Brady said much of what I wanted to say - are we trying to duplicate epub here? Much of what we’re doing here exists in epub, but we should consider what it is we are trying to accomplish. ‘does this add value to the reader’ These are two distinct things.
  Joshua Pyle: Following on Tzviya, these two things are different. The specification, even though we can’t imaging a TOC that is both machine readable and presentational. I haven’t given up on that dream. I just request that the specification doesn’t preclude that something is both machine readable and presentational.
  Avneesh Singh: I’m confused here. All the discussion is about having 2 for TOC - machine readable and visual, and a note that the visual may not be a TOC. I’m just looking at the MVP and that TOC would be only presented. It would be recommended, not compulsory. The requirement that TOC should be only content. So reading system should be able to identify it and put it in front of the user. If it’s not identified in the proper way, how would the reader present?
  Tzviya Siegman: What we’ve proposed is mimicking what epub3 does with the nav document. It uses strict HTML structuring, so a bit more expansive than what’s in the nav document. It is HTML so it can be rendered as an HTML document, and assistive technology, but it can be input for an automated TOC by reading systems.
  … When we are visual, we’re talking about TOCs that use SVG, or heavy CSS, so maybe visual TOC is misleading, but we’re talking about TOCs that are different from the machine-readable one. The proposal is similar to epub…
  … But it would have a list, and be used by the RS.
  Ivan Herman: tzviya also answered Josh’s question
  Matt Garrish: I think what’s been mentioned earlier - using landmarks from epub, maybe we should consider that to differentiate the machine readable and the content and how the RS gets you there. it looks like competing TOCs and fallbacks, and they have distinct purposes, but we should be clearer…
  … maybe there should be landmarks instead of a bunch of links.
  Tim Cole: Does our manifest prohibit content from appearing twice, so that something could appear with two different rels (so that you could have a machine readable and visual TOC)
  Ivan Herman: Yes/no. At the moment, the resources should have only a single entry for a specific resource. The rel value can be an array of values. So the same resources can be identified 15 different ways.
  Deborah Kaplan: We don’t need to solve every publication that everyone is going to write. Somebody is going to say they don’t like footnotes with ARIA, so they make sidebar footnotes, but as long as we document that to be an accessible WP, you also have to include footnotes in a specific way, someone will just do something different…
  … My visual TOC of poetry is 3 different pages, done in 3 different ways - that’s fine, but we haven’t described that use case, and we don’t have to. If they want to compliant, they just need to have the machine readable one and it’ll work, we don’t have to note each use case and address it.
  Ivan Herman: I have a new proposal.
  Proposed resolution: drop the notion of ‘visual TOC’ and close issue #350 (Ivan Herman)
  Tzviya Siegman: +1
  Brady Duga: +1
  Wendy Reid: +1
  Ivan Herman: +1
  Garth Conboy: -1
  Nick Ruffilo: +1
  Deborah Kaplan: +1
  Tim Cole: -1
  George Kerscher: I realize the use of a visual TOC but that can be overwhelming if there are 6 depths to the TOC, and a presentation to the reader would be more palatable. in hopes of getting to only the machine readable, could you possibly trim the tree at a certain level? Or having the presentation that is more palatable for a human?
  Ivan Herman: That can be done today with CSS. You can have an HTML structure that is machine readable, but with CSS you can ‘trim the tree’
  Garth Conboy: My -1 is that i’m happy to close issue 350, but I think we want to have the concept of doing what we want to do here. This visual TOC is one of a handful of landmarks - not as a resource, but a pointer into another resource. Here’s my big long thing of HTML, here’s the TOC, etc. We shouldn’t lose the concept that the visual TOC is a pointer to a resource.
  Wendy Reid: A better proposal might be that we do not drop the notion - but close 350, then a champion should make a better proposal for landmarks. and we can discuss.
  Deborah Kaplan: Wendy++
  Garth Conboy: +1
  Wendy Reid: NickRuffilo: I like the concept of landmarks, the more I think about it the less a visual TOC make sense for MVP, less restricted is best
  Proposed resolution: close issue #350, possibly replace it with a more general notion of landmarks (Ivan Herman)
  Garth Conboy: +1
  Ivan Herman: A point: we are not talking exclusively MVP - but here’s the 2.0 proposal as proposed closer of this.
  Avneesh Singh: +1
  Nick Ruffilo: +1
  Brady Duga: +1
  Zheng Xu (Jeff): +1
  Ivan Herman: +1
  Tim Cole: +1
  Wolfgang Schindler: +1
  Matt Garrish: +1
  Tzviya Siegman: 0
  Charles LaPierre: +1
  Deborah Kaplan: +0
  Laurent Le Meur: 0
  Jeff Buehler: +1
  Juan Corona: 0.5
  Marisa DeMeglio: +1
  Tzviya Siegman: +1
  George Kerscher: +1
  Deborah Kaplan: in that case, +1
  Resolution #3: close issue #350, possibly replace it with a more general notion of landmarks
  Ric Wright: +0.5
  Dave Cramer: +1
  Romain Deltour: +1
  Joshua Pyle: +1
  Wendy Reid: the 3rd possible option was the JSON TOC - but I’m happy to close these two issues, then log a new issue with my proposal and the remaining items…
  Brady Duga: +1
  Ivan Herman: +1
  

[iherman]

Per resolution above, closing.