Foreign content document is not mentioned for fallback processing in the RS spec

[iherman]

Section

https://w3c.github.io/epub-specs/epub34/rs/#sec-epub-rs-conf-foreign-res

Describe the problem

The section describes the fact that a RS MUST process fallbacks for foreign resources if they are rendered. However, that statement does not apply to foreign content documents, e.g., to images (with fallbacks) appearing in the spine. In fact, there is no reference to such documents in the RS.

Describe the fix or new feature you propose

We could (a) duplicate the section to describe the behavior for foreign content documents, or (b) try to reformulate the section to handle both cases.

[iherman]

If the text is changed and/or added, it should have the following test references:

data-tests="#lay-roll-images-mixed,#lay-roll-images-in-spine,#pp-roll-images-mixed,#pp-roll-images-in-spine"

[mattgarrish]

Manifest fallbacks are described in https://w3c.github.io/epub-specs/epub34/rs/#sec-pkg-doc-manifest

When manifest fallbacks [epub-34] are provided for top-level content documents, reading systems MAY choose from the available options to find the optimal version to render in a given context (e.g., by inspecting the properties attribute for each).

A top-level content document is either an epub content document or a foreign resource referenced from the spine, so that already captures your issue, no?

MUST process fallbacks as defined in foreign resources [epub-34].

This link should go to the above section, though, not to 3.4 as it doesn't describe any processing.

[iherman]

The term "foreign resource" was a bit misleading. Not to reopen the naming issue, foreign content element is clear to me, but somehow the fact that a foreign content document is also a foreign resources (in the case of an image, which is of an accepted mime type) is still messing up with my head.

Anyway. I have added some references to #2885 and w3c/epub-tests#310. If those look o.k. to you, we can close this issue (and we should probably merge those two PR-s soon).

[mattgarrish]

The term "foreign resource" was a bit misleading.

There are only foreign resources, core media type resources, and exempt resources. Everything else is a name for how they are used.

The technical name for a foreign resource in the spine or a manifest fallback chain is already defined as a "foreign content document". A "foreign content element" sounds like an xml grammar you'd embed in html or svg.

But the section you cited is well before we get into content documents, and package documents, and manifest fallbacks, and all that fun stuff. You're in the "Publication resources" section of the spec, which comes first because it's setting up those first principles for reading what comes later.

[iherman]

I believe the adjective "foreign" is bothering me. A png image is not a foreign resource, but a core media type resource. And it is o.k. like that as long as it is not added to the spine, when it suddenly becomes "foreign" in terms of a foreign content document (yes, I messed up the term in the issue naming, I have changed it). I would expect a somewhat different adjective here, though I am not sure which one. "Exceptional"? "Special"?

As for the RS system, yes, §5.4 talks about manifest chains, but the sentence says:

"A reading system that does not support the MIME media type [rfc2046] of a given publication resource MUST traverse the manifest fallback chain [epub-34] until it identifies a supported publication resource to use in place of the unsupported resource."

But, strictly speaking, this does not apply to that PNG image, because a RS must support the relevant MIME type (it is core media type resource). At the minimum the sentence should say something like

…does not support the MIME media type of a given publication resource, or that resources is also used as a foreign content document…

That makes it clear that an image in the spine ought to work properly with manifest fallbacks...

[mattgarrish]

because a RS must support the relevant MIME type (it is core media type resource)

Well, this a bit too broad an interpretation. Whether a reading system supports the format depends both on its capabilities and how it is used.

So, yes, a PNG can be both a core media type and supported when embedded in html and also foreign and unsupported when used in the spine. PNG is not an EPUB content document so as described in the "spine plane" that makes it a foreign content document.

[iherman]

because a RS must support the relevant MIME type (it is core media type resource)

Well, this a bit too broad an interpretation. Whether a reading system supports the format depends both on its capabilities and how it is used.

You are right.

So, yes, a PNG can be both a core media type and supported when embedded in html and also foreign and unsupported when used in the spine. PNG is not an EPUB content document so as described in the "spine plane" that makes it a foreign content document.

I understand that, and let us put aside whether the term "foreign" is optimal for that case. But my statement still holds: If a RS can handle PNG, the MUST statement on traversal of the manifest callback chain does not apply for that RS and therefore there is no real obligation to do so for that image appearing as a foreign content document. Or, at least, I do not really see where that comes from. (And even if there is, it might be convoluted, and adding it to that statement might be a good thing.)

[mattgarrish]

If a RS can handle PNG, the MUST statement on traversal of the manifest callback chain does not apply for that RS and therefore there is no real obligation to do so for that image appearing as a foreign content document.

Right, I'm just not sure I'm following your concern. Reading systems aren't required to support anything but xhtml and svg in the spine. Full stop.

So, if they encounter a PNG referenced from a spine item and they support PNG in the spine, there's no need to search for a fallback. That's the way it's supposed to work. The "must" to find a fallback resource only applies if the media type is unsupported in the spine by that reading system.

Reading systems can support anything else they want in the spine, but by spec definition all those other media types are foreign resources.

Would it help to make this more explicit in that "spine plane" section? Maybe change the start of paragraph that introduces foreign content documents to:

The use of any other type of resource in the spine, including core media type resources, is called a foreign content document. Foreign content documents require a manifest fallback to an EPUB content document.

[iherman]

In any case +1 to the last (new) statement.

But I still have to fully grasp what you say. In the case where

• the RS does not support image in the spine
• it hits an image in the spine which (because it is a valid EPUB...) has a fallback as an xhtml

the RS still has the choice of simply ignoring the image or, worst, get into an error? Is this what we are saying?

If this is really the case (and I wouldn't dispute that if you say so) I believe we should somehow make this more explicit, probably in a note somewhere. With the roll layout coming to the fore, RS-s may hit this situation more often than before...

[mattgarrish]

the RS still has the choice of simply ignoring the image or, worst, get into an error?

Are you asking about invalid epubs where there isn't an epub content document in the fallback chain? I recall from past discussions that reading systems that have nothing to show would either give a blank page or simply skip to the next spine item they can display. That led to adding the requirement that they display a message that the content could not be displayed. (There's also the likelihood that you simply won't be able to sell publications with images in spine in some stores, and some reading systems will reject such publications even if you try to side load them, regardless of whether there are fallbacks, but nothing the spec says is likely to change that.)

The authoring requirement to have at least one epub content document in the fallback chain is to prevent the problem of a reading system not supporting the foreign content document and then not having anything to display. The reading system spec sets the requirement to traverse the chain until it finds an appropriate resource to render:

A reading system that does not support the MIME media type [rfc2046] of a given publication resource MUST traverse the manifest fallback chain [epub-34] until it identifies a supported publication resource to use in place of the unsupported resource. If the reading system supports multiple publication resources in the fallback chain, it MAY select the resource to use based on the resource's properties attribute [epub-34] values, otherwise it SHOULD honor the preferred fallback order [epub-34]. If a reading system does not support any resource in the fallback chain, it MUST alert the user that it could not display the content.

The problem we've always had is that you can't say that the fallback isn't the same as what the spine item expects (fxl image with reflowable html as fallback), but that doesn't affect the ability to display something in some way.