-
Notifications
You must be signed in to change notification settings - Fork 64
Clarify the types of resources exempt by not being used by reading systems #2686
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
epub34/authoring/index.html
Outdated
|
||
<dt id="exempt-script">Scripts</dt> | ||
<dd id="confreq-resources-cd-fallback-script"> | ||
<p>Any resource referenced from the [[html]] [^script^] element that is not a core media type |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I remain ambivalent here. This feels like we are encroaching on HTML by allowing non-Javascript scripts, which really should be up to that spec. It is also confusing, in that we are allowing things that are currently forbidden, so it would give me pause when reading - I would end up questioning my understanding of the text. The only reason I can think of for allowing this is to let things like WASM be referenced using a polyfill, which I guess is handy? But also seems somewhat niche. @iherman I think this is something you wanted - what do you think?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The html spec already mentions you can reference external css and json module scripts from the element, but the latter wouldn't currently be allowed. If we want to make sure we stay within the bounds of the html spec, could we just make that a qualifier:
Any resource [html] allows the
script
element to reference is an exempt resource.
(I think it might be helpful to rework the core media type references in all these definitions, like maybe putting a single note before the list that these exemptions are in addition to them.)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I like this a lot better - it defers everything to html. The old wording felt very much like "you could if you could, but you can't so you can't".
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I like the proposed text, but shouldn't it say
Any resource [html] allows the script element to reference that is nota core media type is an exempt resource.
But, in general, deferring to the HTML (or other spec) is a good idea...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
that is nota core media type
That was the parenthesis I had below the suggested text. I find stating this makes reading the exemptions more confusing than they need to be, since core media types are just explicit exemptions from fallbacks by media type. If you don't know the details, it can leave you wondering why core media types aren't exempt from fallbacks.
I think a general note before the list that these exemption are in addition to any core media type designations would serve the same purpose.
epub34/authoring/index.html
Outdated
><code>image</code></a> and <a | ||
href="https://www.w3.org/TR/SVG/embedded.html#ForeignObjectElement" | ||
><code>foreignObject</code></a> elements).</p> | ||
<p>it is not embedded content in an EPUB content document — refer to the [[html]] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is perhaps more clear, but I think it remains too broad. For instance, this means that all style content is an exempt resource, as is all content reference by style sheets (e.g. a background image referenced from CSS does not need to be a core media type, nor does it need a fallback). Is this really what the WG intended when we made this change? And if it is, I think we should be clear about that.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The original goal was to not flag resources harmlessly travelling in the container as having to meet core media type fallback requirements. It then morphed into also using these for scripts. The part of about exempting foreign resources was a convenient side effect when we were mapping out the resource types.
What if we go the rendering route instead of focusing on the methods? So something like:
it is not directly rendered in its native format in an EPUB content document
A data file used by a script to write to canvas, or an image added to the dom with a fallback, would be fine. As would wasm files.
But it wouldn't work for static content like images referenced from styles rules as they'd attempt to present the image in whatever format it's in.
It would also keep the foreign resource exemption stuff intact.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, this matches my intuitive feeling for embedded in this context, and feels like it captures the intent better. I would support this wording.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Although... someone may trick the system. Say I have an image in jpg and, for whatever reason, I want it to be treated as an exemption. I then include a jpg->png transformation somewhere, which is used to render the image. Ie, the jpg image is not rendered in its native format, therefore it is an exemption...
Maybe
It cannot be directly rendered in its native format in an EPUB content document
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Say I have an image in jpg and, for whatever reason, I want it to be treated as an exemption.
But a jpeg is already a core media type so it shouldn't need an exemption to travel in the container. It's not going to get flagged as a foreign resource without a fallback, which is what happens when you list these non-cmt data files in the manifest.
Epubcheck might warn you that you appear to have an unused publication resource, but that's only a usage message so it's not a problem for publishing.
It cannot be directly rendered in its native format in an EPUB content document
There's a lot of stuff that will render inside an iframe. Wouldn't this exclude json, xml, etc.?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There's a lot of stuff that will render inside an iframe. Wouldn't this exclude json, xml, etc.?
But those are not rendered "natively" but through a transformation process. It is not in the default rendering engine's capability to render them. So they would be covered as well.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
But those are not rendered "natively" but through a transformation process.
I'm not sure I follow. What do you mean by a transformation process? If I reference a json or xml file from the src attribute of an iframe, that's what is loaded into the iframe (with some differences between browsers).
Your exemption says it must not be possible for the format to display at all in xhtml. Or is "it cannot be" an instruction to the author and not a quality of the rendering engine?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
But those are not rendered "natively" but through a transformation process.
I'm not sure I follow. What do you mean by a transformation process? If I reference a json or xml file from the src attribute of an iframe, that's what is loaded into the iframe (with some differences between browsers).
Is that formally defined somewhere, or is it just "done" by browsers? Ie, is it an added functionality by browsers (or webviews)? If the former, then of course it is clearly 'inherited' by an RS. But if it is the latter, then we may be on a slippery ground: do we have to take it for granted that a RS would do that?
(The only exception is of course XHTML. That is "natively" rendered.)
All that being said, we are talking about something very minor here, so I won't object to do what you originally proposed to do. The fact that we are having this discussion shows that the line I was proposing raises more questions than what is worth...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is that formally defined somewhere, or is it just "done" by browsers?
This is what confuses me about making it dependent on what can render natively in an xhtml (or svg) document. Even reading systems don't have to render everything epub supports. (Would image data be illegal to use in a reading system without a viewport?) I think we're opening a can of worms that's open to all kinds of interpretation.
We're probably also getting a little picky over an edge case that we have little to no control over anyway. The bigger problem was, as Brady suggested, not opening a loophole for unintended cases, like images called from css. We can't check if scripts are behaving honestly, so any restriction we come up with will depend on the author being aware of the rule and adhering to it.
I just pushed some changes per the discussions. I added the text we discussed and also added a note after the examples of exempt resources to describe the css case of a non-exempt resource. Maybe not critical to have, but I think it's helpful to explain the limits of the exemption. I also took out the repeating "that is not already a core media type" references out and added a new second paragraph to the section to explain the overlap but how core media types are better supported. |
I am not sure I understand the remark
If I use css url to get a jpg file to set a bullet item marker, isn't that resource displayed? Or the same for a background? |
Exemptions are for what would otherwise be foreign resources. A jpeg is a core media type. |
But if it helps, I can change it to: "... a foreign image resource reference by ... " |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice, I like this version, just a few comments.
epub34/authoring/index.html
Outdated
data-cite="html#the-link-element"><code>link</code></a> element to include CSS style sheets, | ||
importing fonts into CSS, or using the [[html]] [^script^] element for JavaScripts). Although this | ||
superficially makes the resources similar in terms of not requiring fallbacks, core media types are | ||
differentiated by having stronger support expectations in reading systems.</p> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does this need a clarification about how such resources are defined? Something like "Resources of core media types that match an exemption remain core media types and are not reclassified as exempt resources." That is, a jpg referenced from a script is not an exempt resource, it remains a core media type. Or maybe that isn't true - I guess it depends if core media types can also be exempt, although we seem to consider these two distinct classes.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agree, the more we can clarify here the better. I've added a couple of additional sentences to make clear that CMTs do not become exempt resources because they share the same inclusion mechanisms and exempt resources without the exemption would be foreign resources. Hopefully, that improves it a bit.
epub34/authoring/index.html
Outdated
</ul> | ||
|
||
<div class="note"> | ||
<p>An example of resource not exempted by this rule would be a image referenced by a <a |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nit: "a resource" or perhaps "resources"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oops, thanks!
epub34/authoring/index.html
Outdated
<div class="note"> | ||
<p>An example of resource not exempted by this rule would be a image referenced by a <a | ||
data-cite="css-values#urls"><code>url</code> function</a> [[css-values]] in a CSS style | ||
sheet, as this would not result in core media type resource being displayed.</p> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I am having a little trouble with the double negatives ("not exempt"/"would not result"), but I have no specific suggestion to make it clearer.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've tweaked this a bit in the last commit and added the additional context of it being a foreign image resource.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice! As a previous manager used to say - "ship it!"
epub34/authoring/index.html
Outdated
differentiated by having stronger support expectations in reading systems.</p> | ||
differentiated by having stronger support expectations in reading systems. A core media type | ||
resource does not become an exempt resource just because they share the same inclusion mechanism. | ||
And without an exemption, an exempt resource would be [=foreign resource=].</p> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nit: "a [=foreign resource=]"?
For the records: WG Approval in https://w3c.github.io/pm-wg/minutes/2025-02-27.html#3fff |
This was discussed during the pmwg meeting on 01 March 2025. View the transcriptWASM resolution (w3c/epub-specs#2686)Wendy: We have a packed agenda today <wendyreid> w3c/epub-specs#2686 Wendy: We would like to have a resolution affirming 2686, which includes webassembly… <wendyreid> Proposed: Merge PR 2686. <Sueneu> +1 <wendyreid> +1 <gpellegrino> 0 duga: There were some changes from out discussion… something of a backdoor for fallbacks for embedded content. We’ve closed an open door and removed embedded content mgarrish: mostly it maps to what we talked about, added some clarifications and examples… <CharlesL> +1 there is a summary in the PR <shiestyle> +1 <duga> +1 <mgarrish> +1 <toshiakikoike> +1 <MasakazuKitahara> +1 <George> +1 RESOLUTION: Merge PR 2686. |
As discussed on the last WG call, this pull request expands on the types of resources that fall under the exemption of not being used by reading systems. I broke the existing paragraph out into a list and added script modules and made script inputs its own bullet rather folded into data sets for external apps.
I've also tried to better address the question about embedded resources so there isn't overlap with this exemption. I've promoted the references to the HTML and SVG concepts of embedded content so that they aren't just examples of embedding but the defining definitions.
Finally, I've added the exemption for resources referenced from the script element.
We started to consider these changes last year in #2655 and I've kept what I could from that pull request here. This one is different in that I didn't try to merge the script inputs and module exemptions with the exemption for the script element itself. It feels like overloading and it starts to duplicate the existing exemption when all we really needed to do was clarify it.
As always, feedback welcome.
Fixes #2649
Fixes #2656
Preview | Diff