Status of "EPUB 3 Overview"

[murata2makoto]

I am not sure if this document deserves to exist. First, EPUB 3.3 already has a section "Overview". Second, some descriptions (most notably, the accessibility section) in "EPUB 3 Overview" are outdated.

We might want to simply cancel this document. Or, we might want to eliminate outdated sections and change the title of this document to "EPUB revision history".

[mattgarrish]

Ya, I argued earlier against republishing the overview, as it's more of a marketing document, but there's still a desire to keep it for a more general audience than reads specifications.

And as a note, it's already technically published. Does W3C even have a process for obsoleting notes, @iherman, or are they just expected to be ignored once they have no value?

Regardless, though, it's a bit late for taking this up now, so I'm fine just living with it. It's harmless.

I think I said a long time back I was going to give it a re-read and haven't found the time. I'll try to get to that and propose some fixes.

[murata2makoto]

Regardless, though, it's a bit late for taking this up now, so I'm fine just living with it. It's harmless.

I'm not sure. Text-to-speech features described in this document are no longer in EPUB 3.3. Accessibility features described here do not cover accessibility metadata. Is it possible to mark this document as "Obsolete"?

[iherman]

Ya, I argued earlier against republishing the overview, as it's more of a marketing document, but there's still a desire to keep it for a more general audience than reads specifications.

I do believe there is a need for it. EPUB is not one document, it is many, if I also consider the number of WG Notes that has been published additionally to the three Recommendation track ones. And the Rec-track documents are also multi-faceted. I do believe there is a need for such a document to help people find their way through these. Obviously, its audience is not people like us.

I think I said a long time back I was going to give it a re-read and haven't found the time. I'll try to get to that and propose some fixes.

I am sure it needs refresh.

Text-to-speech features described in this document are no longer in EPUB 3.3. Accessibility features described here do not cover accessibility metadata.

The document is not final, and can/should evolve like all the others. If there are specific changes, please let us concentrate on those.

Is it possible to mark this document as "Obsolete"?

Process-wise, I believe there is a way to rescind a document, but I would be opposed doing so.

[murata2makoto]

I do believe there is a need for it. EPUB is not one document, it is many, if I also consider the number of WG Notes that has been published additionally to the three Recommendation track ones. And the Rec-track documents are also multi-faceted. I do believe there is a need for such a document to help people find their way through these. Obviously, its audience is not people like us.

Then, should we mimic CSS Snapshot? Here is a list of relevant specifications.

• EPUB 3.3
• EPUB 3.3. Reading Systems
• EPUB Multiple-Rendition Publications 1.1
• EPUB 3 Text-to-Speech Enhancements 1.0
• EPUB 3 Structural Semantics Vocabulary 1.1
• EPUB Accessibility 1.1
• EPUB Accessibility Techniques 1.1
• EPUB Accessibility EU Accessibility Act Mapping
• EPUB Fixed Layout Accessibility
• Alternate Style Tags 1.2
• Display Techniques for EPUB Accessibility Metadata 1.0
• Display Techniques for ONIX Accessibility Metadata 1.0
• Publishing Guide to Audio Playback and Text-To-Speech
• Accessibility Summary Authoring Guidelines for EPUB Publications

We might want to mention LCP at ISO/IEC and DAISY　specifications (such as Navigable Audio-only EPUB3 Guidelines Guidelines for Navigable Audio Only EPUB 3 Publications .

[iherman]

If what you mean is to extend https://w3c.github.io/epub-specs/epub33/overview/#sec-documents by adding, e.g., the ONIX guide, I am happy to do this. Referring to LCP is too risky, politically, due to the three-letter-word, so I would not go there; I am neutral about the DAISY specifications.

The CSS Snapshot comparison is, however, misleading. There are tons of blogs and books that give a quick overview of CSS, so the CSS snapshot is really "just" a reference list. The situation is different for EPUB, so I believe sections 2, 3, and 4 are still necessary (with fixes and refresh, if necessary).

[murata2makoto]

If what you mean is to extend https://w3c.github.io/epub-specs/epub33/overview/#sec-documents by adding, e.g., the ONIX guide,

No, this is not what I mean. I think that an overview document at this point of history should provide a big picture of the entire EPUB family. At present, "EPUB 3 Overview" gives a misleading overview of EPUB 3.3 and nothing else.

[iherman]

the entire EPUB family

Although I do not disagree with what you say, I would modulate it a bit. For me, RS implementers are not necessarily in the audience, ie, I would not dwell into the details of the RS spec here. I would agree that the A11y section should also touch upon the techniques document and the EU A11y act mapping (at the minimum to say what it is for), and maybe refer to the display techniques, although I do not know whether those two documents reflect a consensus (I really do not know, if they do, all the better!). Same holds for some of the notes (e.g., SSV). I do not know whether the alternate style tags are implemented anywhere; if not, I would not include those here either.

But yes, additional text is needed, that is for sure. Any specific text in, e.g., a PR would be welcome...

[murata2makoto]

But yes, additional text is needed, that is for sure. Any specific text in, e.g., a PR would be welcome...

I'll give it a try in August.

[mattgarrish]

the entire EPUB family

Although I do not disagree with what you say, I would modulate it a bit.

Yes, we shouldn't be spending time on notes.

The "Documents" section already gives the big-picture view of what is in scope of EPUB 3 now, including all the documents and notes listed above, so probably all we need to do is expand this sentence at the end with something like:

This overview document concentrates on the authoring format of EPUB 3.3 defined at W3C. In general, it does not cover information contained in notes, as these technologies are not considered stable.

And maybe give the section a more descriptive title like: "EPUB 3 family of documents".

(Edit: added "defined at W3C" to explain away listing LCP, old IDPF specs, that ISO archiving doc, etc., but let's leave it to PRs to figure this out.)

[mattgarrish]

and maybe refer to the display techniques, although I do not know whether those two documents reflect a consensus

Do we really want to start listing all the documents the CG produces? Perhaps there's somewhere else in the publishing space at W3C where we can provide a complete list of all the EPUB documents produced by the WG, CG, and BG? (i.e., resurrect something like https://idpf.org/epub/dir/)

[murata2makoto]

@mattgarrish

If this document concentrates on EPUB 3.3, I do not understand why this document is needed.

At least, it should be made very clear that this document does NOT give a big picture of the EPUB technology. Non-technical guys in the publishing industry and governments might want to read this document but shouldn't think that they have a big picture.

[mattgarrish]

At least, it should be made very clear that this document does NOT give a big picture of the EPUB technology.

When and where has it ever claimed to? It's the generic overview of the features the EPUB 3 format offers and has only ever covered the core specs. It was created to influence people to move from EPUB 2, not to cover every document that IDPF or anyone else has ever produced.

[murata2makoto]

When and where has it ever claimed to? It's the generic overview of the features the EPUB 3 format offers and has only ever covered the core specs. It was created to influence people to move from EPUB 2, not to cover every document that IDPF or anyone else has ever produced.

Those people who should migrate from EPUB 2 to EPUB 3 have already migrated. If this document is needed now, it is not for promoting this migration. I can think of two purposes: (A) It is for selling EPUB 3 to more W3C people, or (B) selling EPUB 3 to non-technical guys who care about accessibility. Although I am still not sure if this marketing document is useful for these purposes, I will try to propose minor changes for addressing obvious problems.

[mattgarrish]

(A) It is for selling EPUB 3 to more W3C people

That's why it's been retained, although not strictly for W3C people. It's for any publishers who aren't producing EPUB 3 at this point. It may have started off with the intention of selling people on upgrading, but I doubt everyone who could has, or that everyone who could be using EPUB 3 is. Will this document push them to change... ?

Keeping it as a non-technical entry point for management level folks is fine with me, though, even if I think the benefit of it has waned. I wouldn't spend a lot of time trying to make it into something else. We have lots of other issues to deal with.

[iherman]

(A) It is for selling EPUB 3 to more W3C people

That's why it's been retained, although not strictly for W3C people. It's for any publishers who aren't producing EPUB 3 at this point. It may have started off with the intention of selling people on upgrading, but I doubt everyone who could has, or that everyone who could be using EPUB 3 is. Will this document push them to change... ?

Keeping it as a non-technical entry point for management level folks is fine with me, though, even if I think the benefit of it has waned. I wouldn't spend a lot of time trying to make it into something else. We have lots of other issues to deal with.

👍 to me.

We may want to discuss this question on a WG call, and make a decision about it once and for all. The WG may decide

1. rescind the document altogether and forget about it
2. keep it as is, with possible bugs handled
3. turn it into something very different

cc @dauwhe @wareid @shiestyle

[murata2makoto]

I would be grateful if this topic will be discussed in a WG call next week or later. I hope to think more about this.

[mattgarrish]

2. keep it as is, with possible bugs handled

Last comment from me is that we may want to rename it. It doesn't give an overview of how EPUB 3 files are put together, like the spec section does.

We might want to call this document something like the "EPUB 3 Feature Overview" or even just "EPUB 3 Features"

[iherman]

The issue was discussed in a meeting on 2022-08-04

• no resolutions were taken

View the transcript

1. Status of EPUB 3 Overview.

See github issue epub-specs#2368.

Dave Cramer: See Overview document.

Dave Cramer: makoto-san is wondering about the value of the Epub 3 overview document and what we should do about it.
… this has historically been an entry point into the epub 3 family of specs.
… it is somewhat out of date, there are things in it which would require some work.
… the landing page argument is somewhat reduced from the past (we are cut down the number of specs in the family).
… the individual specs have intro sections.

Brady Duga: mgarrish, ivan, and makoto are most involved, and they are not here.
… my opinion are that we need to keep it, and that we need to fix the existing issues with it.
… based on what the thread seems to reflect.

Dave Cramer: there is some value to having something like this.
… I wish the links took you to the actual other specs rather than the reference section (which then has another outgoing link).
… but given that the people most involved are not here, I am comfortable postponing this to a future meeting.

Shinya Takami (高見真也): yes, agreed.
… we cannot discuss with without makoto.

Dave Cramer: keeping it and fixing it seems like a reasonable task.
… we'll come back to this in another meeting.