Skip to content
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.

Sign up for GitHub

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

Clarify where remote resources can be referenced #1859

Merged
merged 4 commits into from
Oct 25, 2021
Merged

Clarify where remote resources can be referenced #1859

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ff3d476
clarify where remote resources can be referenced:
mattgarrish Oct 18, 2021
96ca2cf
minor wording consistency fix
mattgarrish Oct 18, 2021
44da591
add media overlays to remote audio exemption and fix curly braces typo
mattgarrish Oct 19, 2021
2532c2f
allow remote fonts from @import and html link elements
mattgarrish Oct 19, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 78 additions & 52 deletions epub33/core/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -988,16 +988,33 @@ <h4>Resource Locations</h4>

<ul class="conformance-list">
<li>
<p id="sec-resource-locations-audio"><a href="#cmt-grp-audio">Audio resources</a></p>
<p id="sec-resource-locations-audio"><a href="#cmt-grp-audio">Audio resources</a> referenced
from the [[HTML]] <a
href="https://html.spec.whatwg.org/multipage/media.html#the-audio-element"
><code>audio</code> element</a> (either from its <code>src</code> attribute or a
child <a href="https://html.spec.whatwg.org/multipage/media.html#the-track-element"
><code>track</code> element</a>) and from the Media Overlays <a
href="#sec-smil-audio-elem"><code>audio</code> element</a>.</p>
</li>
<li>
<p id="sec-resource-locations-video"><a href="#cmt-grp-video">Video resources</a></p>
<p id="sec-resource-locations-video"><a href="#cmt-grp-video">Video resources</a> referenced
from the [[HTML]] <a
href="https://html.spec.whatwg.org/multipage/media.html#the-video-element"
><code>video</code> element</a> (either from its <code>src</code> attribute or a
child <a href="https://html.spec.whatwg.org/multipage/media.html#the-track-element"
><code>track</code> element</a>).</p>
</li>
<li>
<p id="sec-resource-locations-script">Resources that scripts retrieve</p>
<p id="sec-resource-locations-script">Resources retrieved via scripting APIs (e.g.,
XmlHttpRequest [[?XHR]] and Fetch [[?FETCH]]).</p>
</li>
<li>
<p id="sec-resource-locations-fonts"><a href="#cmt-grp-font">Font resources</a></p>
<p id="sec-resource-locations-fonts"><a href="#cmt-grp-font">Font resources</a> referenced
from <a href="https://www.w3.org/TR/css-fonts-5/#font-face-rule"><code>@font-face</code>
rules</a> [[CSS-FONTS-5]], <a href="https://www.w3.org/TR/css-cascade-4/#at-import"
><code>@import</code> rules</a> [[CSS-CASCADE-4]], and the [[HTML]] <a
href="https://html.spec.whatwg.org/multipage/semantics.html#the-link-element"
><code>link</code> element</a>.</p>
</li>
</ul>

Expand Down Expand Up @@ -1191,7 +1208,9 @@ <h5>Shared Attributes</h5>
<code>dir</code>
</dt>
<dd>
<p data-tests="#confreq-rs-pkg-dir_rtl-001,#confreq-rs-pkg-dir_rtl-002,#confreq-rs-pkg-dir_rtl-004,#confreq-rs-pkg-dir_rtl-005,#confreq-rs-pkg-dir_rtl-006">Specifies the <a href="https://www.unicode.org/reports/tr9/tr9-42.html#BD5">base
<p
data-tests="#confreq-rs-pkg-dir_rtl-001,#confreq-rs-pkg-dir_rtl-002,#confreq-rs-pkg-dir_rtl-004,#confreq-rs-pkg-dir_rtl-005,#confreq-rs-pkg-dir_rtl-006"
>Specifies the <a href="https://www.unicode.org/reports/tr9/tr9-42.html#BD5">base
direction</a> [[BIDI]] of the textual content and attribute values of the
carrying element and its descendants</p>
<p>Allowed values are:</p>
Expand All @@ -1201,8 +1220,9 @@ <h5>Shared Attributes</h5>
<li><code>auto</code> &#8212; base direction is determined using the Unicode Bidi
Algorithm [[BIDI]].</li>
</ul>
<p data-tests="#confreq-rs-pkg-dir_rtl-003,#confreq-rs-pkg-dir_rtl-005">Reading Systems will assume the value <code>auto</code> when EPUB Creators omit the
attribute or use an invalid value.</p>
<p data-tests="#confreq-rs-pkg-dir_rtl-003,#confreq-rs-pkg-dir_rtl-005">Reading Systems
will assume the value <code>auto</code> when EPUB Creators omit the attribute or use
an invalid value.</p>
<div class="note">
<p>The base direction specified in the <code>dir</code> attribute does not affect
the ordering of characters within directional runs, only the relative ordering
Expand Down Expand Up @@ -2805,14 +2825,14 @@ <h6>The <code>item</code> Element</h6>
significant. The <a class="codelink" href="#sec-spine-elem"><code>spine</code>
element</a> provides the presentation sequence of content documents.</p>
</div>

<section id="sec-item-elem-examples">
<h6>Examples</h6>

<aside class="example" id="example-manifest-cmt">
<p>The following example shows a <code>manifest</code> that contains only <a>Core Media
Type Resources</a>.</p>

<p>The following example shows a <code>manifest</code> that contains only <a>Core
Media Type Resources</a>.</p>
<pre>&lt;manifest&gt;
&lt;item id="nav"
href="nav.xhtml"
Expand Down Expand Up @@ -2858,13 +2878,13 @@ <h6>Examples</h6>
&lt;/manifest&gt;
</pre>
</aside>

<aside class="example" id="example-manifest-flbk">
<p>The following example shows a <code>manifest</code> that references two <a>Foreign
Resources</a> and therefore uses the <a
href="#sec-foreign-restrictions-manifest">fallback chain mechanism</a> to supply
content alternatives. The fallback chain terminates with a <a>Core Media Type
Resource</a>.</p>
<p>The following example shows a <code>manifest</code> that references two
<a>Foreign Resources</a> and therefore uses the <a
href="#sec-foreign-restrictions-manifest">fallback chain mechanism</a> to
supply content alternatives. The fallback chain terminates with a <a>Core Media
Type Resource</a>.</p>
<pre>&lt;manifest&gt;
&lt;item id="item1"
href="chap1_docbook.xml"
Expand All @@ -2881,11 +2901,11 @@ <h6>Examples</h6>
&lt;/manifest&gt;
</pre>
</aside>

<aside class="example">
<p>The following example shows a reference to a remote audio file that EPUB Creators
must reference from the manifest (Reading Systems will render the audio inline in
the XHTML Content Document, so the file is a Publication Resource).</p>
must reference from the manifest (Reading Systems will render the audio inline
in the XHTML Content Document, so the file is a Publication Resource).</p>
<pre>XHTML:
&lt;audio src="http://www.example.com/book/audio/ch01.mp4" controls="controls"/&gt;

Expand All @@ -2894,20 +2914,21 @@ <h6>Examples</h6>
href="http://www.example.com/book/audio/ch01.mp4"
media-type="audio/mp4"/&gt;</pre>
</aside>

<aside class="example">
<p>The following example shows a link to the same audio file, but in this case the EPUB
Creator does not list the file in the manifest (hyperlinked Remote Resources are not
Publication Resources). The EPUB Creator would only list the audio file in the
manifest if it is also referenced it from an [[?HTML]] embedded content element, as
above (i.e., in a context where it is used as a Publication Resource).</p>
<p>The following example shows a link to the same audio file, but in this case the
EPUB Creator does not list the file in the manifest (hyperlinked Remote
Resources are not Publication Resources). The EPUB Creator would only list the
audio file in the manifest if it is also referenced it from an [[?HTML]]
embedded content element, as above (i.e., in a context where it is used as a
Publication Resource).</p>
<pre>XHTML:
&lt;a href="http://www.example.com/book/audio/ch01.mp4"&gt;Go to audio file&lt;/a&gt;

Manifest:
No Entry</pre>
</aside>

<aside class="example">
<p>The following example shows a link to a local version of the audio file. For this
link to be valid, EPUB Creators must list the audio file in the <a
Expand Down Expand Up @@ -3208,23 +3229,23 @@ <h6>The <code>itemref</code> Element</h6>
the value "<code>yes</code>" for <code>itemref</code> elements without a
<code>linear</code> attribute.</p>

<p id="confreq-spine-nonlinear" data-tests="#confreq-spine-nonlinear">EPUB Creators MUST provide
a means of accessing all non-linear content (e.g., hyperlinks in the content or from the
<a href="#sec-nav">EPUB Navigation Document</a>).</p>
<p id="confreq-spine-nonlinear" data-tests="#confreq-spine-nonlinear">EPUB Creators MUST
provide a means of accessing all non-linear content (e.g., hyperlinks in the content or
from the <a href="#sec-nav">EPUB Navigation Document</a>).</p>

<p id="attrdef-itemref-properties">The <a href="#app-itemref-properties-vocab">Spine
Properties Vocabulary</a> is the <a href="#sec-default-vocab">default vocabulary</a>
for the <code>properties</code> attribute.</p>

<p>EPUB Creators MAY add terms from other vocabularies as defined in <a
href="#sec-vocab-assoc"></a>.</p>

<section id="sec-itemref-elem-examples">
<h6>Examples</h6>

<aside class="example">
<p>The following example shows a <code>spine</code> element corresponding to <a
href="#example-manifest-cmt">the manifest example above</a>.</p>
href="#example-manifest-cmt">the manifest example above</a>.</p>
<pre>&lt;spine page-progression-direction="ltr"&gt;
&lt;itemref idref="intro"/&gt;
&lt;itemref idref="c1"/&gt;
Expand Down Expand Up @@ -4554,7 +4575,8 @@ <h5>The <code>page-list nav</code> Element </h5>
nested sublists).</p>

<p>EPUB Creators MAY identify the destinations of the <code>page-list</code> references in their
respective EPUB Content Documents using the <a href="https://w3c.github.io/epub-specs/epub33/ssv/#pagebreak"><code>pagebreak</code>
respective EPUB Content Documents using the <a
href="https://w3c.github.io/epub-specs/epub33/ssv/#pagebreak"><code>pagebreak</code>
term</a>.</p>
</section>

Expand Down Expand Up @@ -4600,9 +4622,12 @@ <h5>The <code>landmarks nav</code> Element </h5>
<p>The following landmarks are recommended to include when available:</p>

<ul>
<li><a href="https://w3c.github.io/epub-specs/epub33/ssv/#bodymatter"><code>bodymatter</code></a> [[?EPUB-SSV-11]] &#8212; Reading Systems often use this
landmark to automatically jump users past the front matter when they begin reading.</li>
<li><a href="https://w3c.github.io/epub-specs/epub33/ssv/#toc-1"><code>toc</code></a> [[?EPUB-SSV-11]] &#8212; If the table of contents is available in
<li><a href="https://w3c.github.io/epub-specs/epub33/ssv/#bodymatter"
><code>bodymatter</code></a> [[?EPUB-SSV-11]] &#8212; Reading Systems often use
this landmark to automatically jump users past the front matter when they begin
reading.</li>
<li><a href="https://w3c.github.io/epub-specs/epub33/ssv/#toc-1"
><code>toc</code></a> [[?EPUB-SSV-11]] &#8212; If the table of contents is available in
the spine, Reading Systems may use this landmark to take users to the document
containing it.</li>
</ul>
Expand Down Expand Up @@ -7307,9 +7332,9 @@ <h5>Text-to-Speech Rendering</h5>
EPUB Content Document element or has a text fallback).</p>

<div class="note">
<p>See <a href="https://www.w3.org/TR/epub-tts-10/">EPUB 3 Text-to-Speech
Support</a> [[EPUB-TTS-10]] for more information about using TTS technologies in
EPUB Publications.</p>
<p>See <a href="https://www.w3.org/TR/epub-tts-10/">EPUB 3 Text-to-Speech Support</a>
[[EPUB-TTS-10]] for more information about using TTS technologies in EPUB
Publications.</p>
</div>
</section>
</section>
Expand Down Expand Up @@ -7575,8 +7600,8 @@ <h4>Skippability</h4>
&lt;/html&gt;</pre>
</aside>

<p>The following non-exhaustive list represents terms from the Structural Semantics Vocabulary [[?EPUB-SSV-11]]
for which Reading Systems may offer the option of skippability:</p>
<p>The following non-exhaustive list represents terms from the Structural Semantics
Vocabulary [[?EPUB-SSV-11]] for which Reading Systems may offer the option of skippability:</p>

<ul>
<li>
Expand Down Expand Up @@ -7677,8 +7702,8 @@ <h4>Escapability</h4>
&lt;/smil&gt;</pre>
</aside>

<p>The following non-exhaustive list represents terms from the Structural
Semantics Vocabulary [[?EPUB-SSV-11]] for which Reading Systems may offer the option of escapability:</p>
<p>The following non-exhaustive list represents terms from the Structural Semantics
Vocabulary [[?EPUB-SSV-11]] for which Reading Systems may offer the option of escapability:</p>

<ul>
<li>
Expand Down Expand Up @@ -8007,10 +8032,10 @@ <h3>The <code>epub:type</code> Attribute</h3>
section).</p>

<p>The <a href="#sec-default-vocab">default vocabulary</a> for the <code>epub:type</code> attribute is
the EPUB 3 Structural Semantics Vocabulary [[?EPUB-SSV-11]]. EPUB Creators MAY include
unprefixed terms that are not part of this vocabulary, but the preferred method for adding custom
semantics is to use <a href="#sec-prefix-attr">prefixes</a> for them. Refer to <a
href="#sec-vocab-assoc"></a> for more information.</p>
the EPUB 3 Structural Semantics Vocabulary [[?EPUB-SSV-11]]. EPUB Creators MAY include unprefixed
terms that are not part of this vocabulary, but the preferred method for adding custom semantics is
to use <a href="#sec-prefix-attr">prefixes</a> for them. Refer to <a href="#sec-vocab-assoc"></a>
for more information.</p>

<aside class="example" id="ex.epubtype.note">
<p>The following example shows how a preamble could be marked up with the <code>epub:type</code>
Expand Down Expand Up @@ -9409,9 +9434,10 @@ <h2>Change Log</h2>
>Working Group's issue tracker</a>.</p>

<ul>
<li>12-Oct-2021: The Structure Semantics Vocabulary has been moved into a separate Working Group Note.
See <a href="https://github.com/w3c/epub-specs/issues/1761">issue 1763</a>
</li>
<li>18-Oct-2021: Clarified the contexts from which remote resources may be referenced. See <a
href="https://github.com/w3c/epub-specs/issues/1857">issue 1857</a>.</li>
<li>12-Oct-2021: The Structure Semantics Vocabulary has been moved into a separate Working Group Note.
See <a href="https://github.com/w3c/epub-specs/issues/1763">issue 1763</a>.</li>
<li>27-Aug-2021: Add clarifications for including landmarks, such as limiting the number, recommending
known semantics, and ensuring the labels are human readable. Also added recommendation to not
include nested lists to match the page list. See <a
Expand Down