Expand and fix resource explanations

[mattgarrish]

With this PR, I've tried to rationalize all the categories of resources and exemptions we've layered onto the spec.

Probably the biggest addition is to add formal terms for things we've left unnamed:

• I've added Linked Resource as a formal term for anything that isn't a Publication Resource to cover everything you can find in the container (at the highest level). We were already informally using this term in the link element definition, so it's more a standardization effort.
• I've added Foreign Content Document to cover anything in the spine that isn't an EPUB Content Document. We slipped into a bad habit of calling these Foreign Resources in places, when that's only a subset. Most of the Core Media Type Resources are Foreign Content Documents when used in the spine.

I've also tried to explain how all these resources come together in a new introduction to the Publication Resources section. The groupings generally break down like this:

• EPUB Container = Publication Resources + Linked Resources
• Spine = EPUB Content Documents + Foreign Content Documents
• EPUB/Foreign Content Documents contain Core Media Type Resources and Foreign Resources

But there are overlaps and exemptions that make not quite so simple.

I've also gone through and tried to clean up all the inconsistencies that have arisen because we've tended to drop into using the wrong terminology in various places.

From a structural standpoint, this PR gets rid of the "Core Media Types" section and renames the section "Supported Formats" to "Core Media Types", as this is really where we define them. It also moves the Manifest Fallbacks section up into Publication Resources, although I'm still not sure if this is the best location given how heavy it is on explaining the item element.

At any rate, hopefully this helps improve the ambiguities about why core media types are not always fallback exempt, why foreign resources are not the only foreign things in the spine, etc.

It's also a starting point, so if there are other improvements we can make here please feel free to comment.

(The changes so far should not normatively change anything.)

Also fixes #2083
Also fixes #2160

---

Preview | Diff

[iherman]

I must admit that I originally had a slightly different mental model for the resources than this "axes" view. I have tried to make a diagram for a categorization of resources in

https://docs.google.com/drawings/d/1HFke3nLDSOmZZtjwV38SFrNbA_omRtTgafK51PmEsWA/edit

where the issues around manifest storage or fallbacks appear as "characterizations" of the various resource types. I am just throwing this into the discussion, because I am still not 100% convinced that this "axes" view is the more readable...

[mattgarrish]

I am just throwing this into the discussion, because I am still not 100% convinced that this "axes" view is the more readable...

There a few problems with your view:

1. EPUB and Foreign Content Documents are inverted. They are not instances of core media type resources, but are, from a container perspective (or all publication resource perspective), a separate class of resources.
2. We could disallow all CMTs and you'd still have EPUB Content Documents allowed in the spine because they are the central building blocks of EPUB. They don't get their legitimacy from CMTs.
3. Core Media Type Resources and Foreign Resources are only used in rendering EPUB Content Documents (and Foreign Content Documents but we tend to care less about these uses).
4. EPUB Content Documents are only considered a Core Media Type because it allows their embedding in other EPUB Content Documents. Technically, what we allow as CMTs are XHTML and SVG documents that are also required to conform to the XHTML and SVG Content Document definitions.
5. Foreign Content Documents are everything in the spine minus EPUB Content Documents. They don't flow from Core Media Type Resources or even from Foreign Resources.

I understand what you're trying to achieve by coaxing the core media types and foreign resources beyond their defined uses, but it doesn't work. There aren't neat lines because a single resource can, for example, be both a Foreign Content Document and Core Media Type depending on the context in which it is used.

[mattgarrish]

There a few problems...

I guess this comment is kind of moot if we agree about axes. Maybe I should have read the full review first...

[iherman]

There a few problems...

I guess this comment is kind of moot if we agree about axes. Maybe I should have read the full review first...

I think we agree on those. Not sure whether to use the term "facet" or "axis", though. I leave that choice to you.

[mattgarrish]

You're jumping in before I'm done rewriting... ;)

I'm actually still pondering some things, like the names of the axes.

I had trouble making "manifest axis" work because listing in the manifest is more a byproduct of the type of resource. You could equally call it a "container axis" because the type of resource also gets reflected in whether it is in the container or not. I opted to go with "publication axis" to cover that these are all the possible resources.

I also had trouble with "rendering axis" because the spine is also a rendering axis. CMTs and Foreign Resources sort of fall into the subrendering axis of the spine rendering axis. That's why I have it as content document axis right now.

These may still change.

I'll have a look at the comments you've made, though.

[mattgarrish]

Not critical to this PR, but it might be good to rearrange the sections of the RS to match the core. For some reason, it has Foreign Resources, Remote Resources, and Data URLs before Core Media Types.

Also, what still bugs me about manifest fallbacks in section 2 is that all the reading system requirements on their processing are combined into the Manifest section under Package Document Processing. I guess we don't have to exactly parallel the core specification, but that exemplifies the disconnect I have with it. It's all about the mechanism in the package document moreso than about resources themselves. I can live with it if no one else finds it problematic, though.

[mattgarrish]

To help anyone who wants to review this PR (which would be helpful for a change this size!), here's a recap of what has been updated, with links into the preview.

Of note is that this PR does not change the way that you include or use resources in a publication, the manifest, or the spine. It's all about better explaining why we have all the classes and what their uses are.

• There are three new terms to fill in the logic gaps: Exempt Resource, Foreign Content Document, and Linked Resource
• There is an extensive new introduction to the Publication Resources section, this includes the definitions of the manifest plane, spine plane, and content plane. (These "planes" are purely informative and only exist within the intro for descriptive purposes.)
• The "Core Media Types" parent section is removed, which puts Foreign Resources as a sibling section of the new Core Media Types section (this used to be called "Supported Types").
• The specific details we had for HTML fallbacks are now defined in two new subsections of Foreign Resources: HTML audio Fallbacks and HTML img Fallbacks
• There is a new Exempt Resources section. This section collects the various exemptions we've defined (for HTML elements, Fonts, and resources in the container but not used in the direct rendering).
• Manifest Fallbacks is moved up to section 2 from where it was under the Manifest section of the Package Document.
• There is a new detailed example of publication resources explaining how resources in an example epub fit into the different planes depending on their uses.

Everything else is just linking cleanup, rewordings to use the new terminology, and various minor fixes where we were using the wrong terms to explain concepts.

[iherman]

@dauwhe @wareid @shiestyle we would really need extra eyes on this PR. It may be worth adding it on the agenda of this week's call, too.

[murata2makoto]

When will this issue be closed? I think that this issue deserves discussion in a WG meeting and 1-week review.

[iherman]

The issue was discussed in a meeting on 2022-03-31

List of resolutions:

• Resolution No. 1: Merge Pull Request Expand and fix resource explanations #2101.

View the transcript

1. Expand and fix resource explanations (pr epub-specs#2101)

See github pull request epub-specs#2101.

Dave Cramer: https://pr-preview.s3.amazonaws.com/w3c/epub-specs/2101/017a47c...6a76ddc.html#sec-publication-resources.

Dave Cramer: this is a very comprehensive re-working of how we define and explain publication resources.

Matt Garrish: ivan had some diagrams in the PR, and this was also a useful exercise for identifying areas where terminology had gotten kind of wonky.
… it looks big, but the bulk of the PR is adding an introduction and some examples.
… ultimately we broke it down to 3 "planes".
… the top one is manifest plane: everything in the container.
… we had a term called publication resources, which described anything used in rendering, and then we had non-publication resources for everything else.
… what we've done is to formalize the term linked resource to describe these other resources.
… moving down from that we have the spine plane and epub content documents.
… it was kind of a mix, sometimes we called things in the spine publication resources, sometimes we referred to foreign resources.
… so we've made it either epub content document or foreign content document.
… finally the lowest level is the content plane: everything that gets rendered in an epub content document.
… this is where CMT and foreign resource live as concepts.
… and we created a 3rd category of exempt resources that collects together all these exemptions to CMT/fallback rules, e.g. fonts.
… this PR basically just sets up this understanding and these terminology.
… ivan went and did an extensive example in the appendix.
… and how each of the parts of the example would match up to the 3 planes.
… the rest is just clean-up, to make sure that our use of terminology is consistent, try to weed out places where we previously lacked defined terminology so meaning was muddier.

Dave Cramer: I wish I could wipe my memory of epub and start over with this.

Matt Garrish: yes, it was a really helpful exercise, and discussing without this was very convoluted.

Dave Cramer: yes, I've witnessed confusion because of the lack of terminology.
… about remote resources, does that concept stay the same as part of this picture?.

Matt Garrish: we described where remote resources exist in the planes, but they aren't a class unto themselves.
… i don't want to make it so complex in explaining it that we go back into the state of confusion where we were before.

Dave Cramer: right, both remote resources and manifest fallbacks need to serve these other roles.

Murata Makoto: i've been a bit skeptical about the publication resources. Now we have a class of linked resources and publication resources.
… so now SSML and PLS are publication resources, right?.

Matt Garrish: yes.

Murata Makoto: so rendering means not just visual rendering, but any sort of rendering.

Matt Garrish: publication resources are just the big giant bucket of everything used in rendering the epub, c.f. linked resources which are not directly part of the publication.

Dave Cramer: ancillary to the publication.

Murata Makoto: wondering if we really need the term publication resources, maybe just resource, or resources which are not linked.

Matt Garrish: yeah, but then aren't we just going back to not have a direct term for it? would it conflict with other contexts where people talk about resources?.

Murata Makoto: so you are saying resources within the zip file are one category, and that resources outside the zip file are something else.

Matt Garrish: resources is just a very general term, so i'm worried that it becomes too broad.
… and part of it is that publication resources is just always the term we've used.

Dave Cramer: resources as a term is so overloaded, i don't think it gains us clarity.

Murata Makoto: not happy with the definition of publication resources because it depends on rendering, which is not well defined in itself.
… can we say that it is all non-linked resources in the epub?.
… if some data is used for braille, are they publication resources? I guess so, but it is not so clear.

Dave Cramer: i think we're clear that rendering is anything presented to the user.

Murata Makoto: is that in the spec?.

Dave Cramer: i think it's a term of art in the web/graphics world.

Murata Makoto: before i got involved in a11y, i never thought of braille as rendering.

Matt Garrish: it's still presented to the user.
… to be honest, use of rendering was intentional, we specifically avoided use of display.
… not sure how we would define that beyond the common definition of rendering.

Murata Makoto: how about adding a note on the scope of rendering?.
… specifically referring to braille terminals.

Matt Garrish: that's fine with me, not sure where it would fit, but we could do this.

Dave Cramer: maybe in the terminology section?.

Matt Garrish: we could make a defined term out of it, like 'encompasses all the ways content may be presented, whether visual, tactile, or auditory'.
… we do define some common terms, so probably no harm in providing some basic definition.
… just worried about having to link it then (we are supposed to link each term the first time it is used).
… but we don't have to settle this now.

Dave Cramer: in general i think this is a massive improvement to the legibility of the spec.
… it's also one of these things that is hard to sort out all the issues before merging it.
… with big PRs there is always the possibility of typos sneaking in.
… given broad support for the goals and language here, I propose we merge, and then we can file issues and fix as necessary, as with the definition of rendering above.

Proposed resolution: Merge PR 2101. (Dave Cramer)

Matt Garrish: the bulk of this is informative, so likely nothing normative changes as a result of this.
… doesn't really block move to CR.

Dave Cramer: +1.

Murata Makoto: will we close this issue too?.

Shinya Takami (高見真也): +1.

Dave Cramer: yes, and then we can open more detailed issues on subsets of this.

Matt Garrish: there's no actual issue, the PR is based on discussions i had with ivan.

Murata Makoto: so nothing wrong with raising smaller issues related to this?.

Dave Cramer: yes.

Matt Garrish: and it's hard to raise issues off a PR.

Matt Garrish: +1.

Murata Makoto: +1.

Dave Cramer: anyone else, please vote now.

Matthew Chan: +1.

Toshiaki Koike: +1.

Masakazu Kitahara: +1.

Resolution #1: Merge Pull Request #2101.

Dave Cramer: mgarrish please merge at your convenience.