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

primary entry page issues #335

Merged
merged 2 commits into from
Sep 24, 2018
Merged

primary entry page issues #335

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
aad3445
create primary entry page section and clean up requirements
mattgarrish Sep 19, 2018
f7056b7
add statement about adding primary entry page to default reading order
mattgarrish Sep 19, 2018
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
65 changes: 51 additions & 14 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -556,11 +556,10 @@ <h4>Relative URLs</h4>
<section id="manifest-embedding">
<h3>Embedding a Manifest</h3>

<p>A manifest can be embedded within an HTML document using the <a
<p>When opting to embed the manifest, it MUST be included in the <a href="#wp-primary-entry-page"
>primary entry page</a> using the <a
href="https://www.w3.org/TR/html5/semantics-scripting.html#the-script-element"
><code>script</code> element</a>&#160;[[!html]].</p>

<p>When embedding a manifest, the <code>type</code> attribute of the containing <code>script</code>
><code>script</code> element</a>&#160;[[!html]]. The <code>type</code> attribute of this
element MUST be set to <code>application/ld+json</code>.</p>

<p>Additionally, the <code>script</code> element MUST include a unique identifier in an <code>id</code>
Expand Down Expand Up @@ -626,8 +625,8 @@ <h2>Linking to a Manifest</h2>
<h2>Resources</h2>

<p>A <a>Web Publication</a> MUST include at least one <abbr title="Hypertext Markup Language"
>HTML</abbr> document&#160;[[!html]] that <a href="#wp-linking">links to the manifest</a>. This
page is referred to as the <dfn>primary entry page</dfn> of the Web Publication.</p>
>HTML</abbr> document&#160;[[!html]] &#8212; the <a href="#wp-entry-page">primary entry
page</a>.</p>

<p>There are no restrictions on a Web Publication beyond this requirement. The Web Publication MAY
include references to resources of any media type, both in the <a>default reading order</a> and as
Expand All @@ -638,21 +637,59 @@ <h2>Resources</h2>
ensure a more consistent reading experience for users regardless of their preferred user agent.</p>
</section>

<section id="wp-primary-entry-page">
<h3>Primary Entry Page</h3>

<p>The <dfn>primary entry page</dfn> is a key [[!HTML]] document required of every Web Publication. It
represents the preferred starting <a href="#wp-resource">resource</a> for discovery of the Web
Publication and enables discovery of the <a>manifest</a>.</p>

<p>Although any resource can link to the Web Publication manifest, the primary entry page typically
introduces the publication and provides access to the content. It might contain all the content, in
the case of a single-page Web Publication, or provide navigational aids to begin reading a
multi-document Web Publication. To facilitate the user ease of consumption, the primary entry page
SHOULD contain the <a href="#wp-table-of-contents">table of contents</a>.</p>

<p>It is not required that the primary entry page be included in the <a href="default-reading-order"
>default reading order</a>, nor that it be the first document listed when it is included. This
specification leaves the exact nature of the document intentionally underspecified to provide
flexibility for different approaches (e.g., the primary entry page could be a marketing document for
the Web Publication instead of a specific page of content). If a default reading order is not
provided, however, the primary entry page will be used as the default entry.</p>

<p>To ensure discovery of the manifest, the primary entry page MUST either:</p>

<ul>
<li><a href="#wp-linking">link to the manifest</a>; or</li>
<li><a href="#manifest-embedding">embed the manifest</a>.</li>
</ul>

<p>Note that the primary entry page is the only resource that can contain the Web Publication's manifest
when it is embedded.</p>

<p>The address of the primary entry page is also the <a>canonical identifier</a> for the Web Publication
(i.e., it serves as the unique identifier for the Web Publication).</p>

<p>In certain cases where information has been omitted from the manifest, user agents will sometimes use
the primary entry page as a fallback source of information (see <a href="#language-and-dir">language
and base direction</a> and <a href="#title">title</a>).</p>
</section>

<section id="wp-table-of-contents">
<h3>Table of Contents</h3>

<p>The table of contents provides a hierarchical list of links that reflects the structural outline of
the major sections of the Web Publication.</p>

<p>The table of contents is expressed via an HTML element in one of the <a href="#wp-resources"
>resources</a> (typically a <code>nav</code> element&#160;[[!html]]). This element MUST be
<p>The table of contents is expressed via an HTML element (typically a <code>nav</code>
element&#160;[[!html]]) in one of the <a href="#wp-resources">resources</a>. This element MUST be
identified by the <code>role</code> attribute&#160;[[!html]] value
"<code>doc-toc</code>"&#160;[[!dpub-aria-1.0]], and MUST be the first element in the document so
designated.</p>

<p>The table of contents SHOULD be located in the <a>primary entry page</a> of the Web Publication. If
not, the manifest SHOULD <a href="#table-of-contents-manifest">identify the resource</a> that
contains the structure.</p>
<p>If the table of contents is not located in the <a href="#wp-primary-entry-page">primary entry
page</a>, the manifest SHOULD <a href="#table-of-contents-manifest">identify the resource</a>
that contains the structure.</p>

<p>There are no requirements on the table of contents itself, except that, when specified, it MUST
include a link to at least one <a href="#wp-resources">resource</a>.</p>
Expand Down Expand Up @@ -1827,9 +1864,9 @@ <h5>Infoset Requirements</h5>

<p>The default reading order MUST include at least one resource.</p>

<p>The default reading order is specified directly in the manifest. However, if the reading
order consists of only a single resource, namely the <a>primary entry page</a> of the Web
Publication, the default reading order need not be specified.</p>
<p>The default reading order is specified directly in the manifest, but MAY be omitted when it
only consists of the <a>primary entry page</a>. When the default reading order is absent,
user agents MUST include an entry for the primary entry page when compiling the infoset.</p>
</section>

<section id="default-reading-order-manifest">
Expand Down