how to determine when a table of contents is necessary? about audiobooks HOT 18 CLOSED

the necessary clarification on the format of the TOC will be treated as #99

from audiobooks.

The format and processing defined in pub manifest isn't referenced. (Not sure if this was a compromise decision or an oversight.)

Even if https://www.w3.org/TR/pub-manifest/#app-toc-html is not specifically referenced, doesn't the position of the Audiobook spec as a profile of the pub manifest spec implies that this is the standard way to do it?

Sure, an explicit reference would be much better than an implicit one.

Note: I also consider that the possibility to add a TOC to audiobooks is one of its main plus, the other being a core metadata set. I took for granted the the pub manifest.

from audiobooks.

I would have to go wayyy back in the minutes to find the exact reason why we went the way we did, but I do recall it was a compromise.

One reason why we didn't go for a MUST on the TOC in audiobooks is because it isn't a common practice today, so while it would indeed be a huge plus to have, if we were to force it, we'd more likely see invalid audiobooks than TOCs in some cases. Another case mentioned I believe was podcasts or really short form audio content, that might not even need a TOC, like a children's book.

At this point I think making any changes here threatens a substantive change, could we maybe explore this in the maintenance group, and leave it as is for now? I want to elaborate on TOCs, but I think we need to see some real-world usage and use cases before we get too involved with this.

As @mattgarrish suggests, it might be the easiest path now to remove the rule entirely. We can amend it with a revision in the maintenance group if we get the evidence we need.

from audiobooks.

So should we just remove the rule and not try to determine if/when a TOC should be present?

To be clear, I mean remove the manifest processing validation step, not the actual normative prose.

from audiobooks.

The spec only states that there SHOULD be a TOC if supplemental content is present.
But reading the manifest processing, step 1 is clear: the TOC is mandatory (if toc is not true, validation error). Therefore step1 item 3 has to be removed I think. Setting the toc variable is still useful.
Note: I didn't find in this manifest processing any mention of supplemental content.

from audiobooks.

And I'd be in favor of the the presence of the TOC being a SHOULD regardless of supplemental material -- adding a standard way to do a TOC is like the most important feature of our proposed standard.

from audiobooks.

I didn't find in this manifest processing any mention of supplemental content.

No, I suspect when I wrote the steps I missed that particular nuance and reacted only to the PEP section saying it should contain the table of contents and the TOC section saying if not then the manifest needs to identify where it is.

If I'd realized that was the condition, I would have raised the impossibility of testing it a lot earlier.

adding a standard way to do a TOC is like the most important feature of our proposed standard

Sadly, even if the table of contents is always recommended, there isn't a recommended format for it. The audiobooks specification only requires a table of contents be present in a nav element somewhere. The format and processing defined in pub manifest isn't referenced. (Not sure if this was a compromise decision or an oversight.)

from audiobooks.

doesn't the position of the Audiobook spec as a profile of the pub manifest spec implies that this is the standard way to do it

It's very confusing if it does, as the table of contents section introduces its own normative statements about the table of contents without reference to the appendix in pub manifest.

The table of contents is expressed via an [html] element (typically a nav element) in one of the resources. This element MUST be identified by the role attribute [html] value "doc-toc" [dpub-aria-1.0].

Publication manifest only recommends the method defined in the appendix, so profiles can define alternatives. Without a reference, I'd read audiobooks as having taken the approach of a looser toc structure.

But I missed the discussions on the table of contents, so if the expectation is that we're inheriting we should make it much clearer.

from audiobooks.

At this point I think making any changes here threatens a substantive change, could we maybe explore this in the maintenance group, and leave it as is for now?

I'm good with this approach. I'd rather not risk moving to PR, and I don't think there's a solution here that doesn't involve changing some normative aspect of the specification.

it might be the easiest path now to remove the rule entirely

I think this is justifiable, even at this late stage, as we're only harmonizing the rule with the normative requirements of the specification. I believe that's in keeping with the kinds of corrections we should make. @iherman?

Therefore step1 item 3 has to be removed I think. Setting the toc variable is still useful.

It's just a local variable to test the loop in item 2, not part of the internal representation, so without the final validation it doesn't do anything. I think we're okay dropping the whole rule.

from audiobooks.

I okay with leaving to the maintenance group. But, linking Audiobook TOC to Pub Manifest Spec seems like it should be done with some urgency (unless we think that could be done now [remaining SHOULD] as a non-substantive change).

from audiobooks.

unless we think that could be done now [remaining SHOULD] as a non-substantive change

Arguing only from a procedural perspective (I'd rather toc was a should and the format clarified), but if we introduce a reference to the format/processing defined in pub manifest, the problem is we don't currently test for implementations. We'd have to show two implementations of the toc algorithm and I don't know if we have those or could get them quickly.

from audiobooks.

Understood. From a testing perspective, I'd bet ours and EDRLabs would count. But, you should be the judge of "too late."

from audiobooks.

Should we label this issue as 'postponed' and leave at that for now?

from audiobooks.

From accessibility perspective we wanted to have table of content as a must, but we received push back on the basis of the reasoning of making the specifications dead simple. So, if we want to go to having it as must, I am in favor of it.

While writing reference implementation of audio books in Obi production tool, I assumed that I need to follow Publication Manifest TOC because audio book specs is a profile of Publication Manifest. So I did the same. Therefore I am also in favor of an explicit reference to Pub Manifest.

After stating all this, I also believe that meeting timeline is important. We should not make any changes which threatens the deadline of November 1. I am OK to see all this fixed in maintenance release of audio books specs.

from audiobooks.

Or can we close this issue off with the PR in #95, as it was originally only about the problematic step in the processing section.

We have two separate issues that look like they can be split out and deferred: 1) should the TOC always be required/recommended; and 2) should we require/recommend the format and processing of the TOC defined in pub manifest.

from audiobooks.

There are several discussion levels in this thread:

• the processing model is not consistent with the spec: I don't see how this issue can be postponed, and we have to focus on this (this is what Matt just did in #95).
• the expected format of the TOC is not clear in the audiobook spec. Implementers of reading systems will expect a TOC format consistent with the one detailed in the publication manifest; the audiobook spec can be made clearer during the maintenance process.
• Avneesh would like to have the TOC mandatory in the audiobook spec. This would make IMO more difficult the acceptation of the standard by audiobook publishers + moving from optional to mandatory would be a non backward compatible choice. Only the maintenance WG can discuss that, later.

from audiobooks.

For a better administration: @avneeshsingh, could you put your comments in #93 (comment) into a separate issue, clearly marked as 'postponed'? We all agree that this would be a longer-term issue/feature, and it is better to have it a separate issue.

from audiobooks.

@llemeurfr similarly to my request to @avneeshsingh : can you put your second statement, ie,

• the expected format of the TOC is not clear in the audiobook spec. Implementers of reading systems will expect a TOC format consistent with the one detailed in the publication manifest; the audiobook spec can be made clearer during the maintenance process.

into a separate issue, marked both editorial and postponed? If these two problems are separated, and in view of #95, we could close the current issue.

from audiobooks.