Publishing Working Group Telco — Minutes

Date: 2018-11-26

See also the Agenda and the IRC Log


Present: Yu-Wei Chang (Yanni), Luc Audrain, Evan Owens, Deborah Kaplan, Wendy Reid, Rachel Comerford, Teenya Franklin, Nick Ruffilo, Wolfgang Schindler, Jeff Buehler, Franco Alvarado, Chris Maden, Jun Gamou, Ivan Herman, Romain Deltour, Benjamin Young, George Kerscher, Avneesh Singh, Jasmine Mulliken, Dave Cramer, Joshua Pyle, Ben Schroeter, Tzviya Siegman, Ric Wright, Marisa DeMeglio, Mustapha Lazrek, Matt Garrish, Brady Duga, Garth Conboy, Laurent Le Meur, Charles LaPierre, Juan Corona, Zheng Xu (Jeff)

Regrets: Ivan Herman


Chair: Wendy Reid

Scribe(s): Nick Ruffilo


Wendy Reid:

Wendy Reid: Welcome everyone - First, lets approve last week’s minutes.
… Silence is approval. Minutes approved.

Resolution #1: last week’s minutes approved

1. TOC

Wendy Reid:

Wendy Reid:

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:

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

2. F2F

Wendy Reid: We don’t have any F2F updates, it will be in Boston/Cambridge may 6-7 2019. Monday/Tuesday.

3. Resolutions