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

Consolidation of the draft #33

Merged
merged 6 commits into from
Aug 16, 2017
Merged

Consolidation of the draft #33

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
165a619
Consolidation of the draft
iherman Aug 15, 2017
6f47335
Forget to reproduce the section on fallbacks...
iherman Aug 15, 2017
816fee6
Taking care of @rdeltour's comments
iherman Aug 15, 2017
3c919a0
minor edits
TzviyaSiegman Aug 15, 2017
0b6dac9
minor typo corrections
llemeurfr Aug 16, 2017
6001a76
Merge pull request #34 from llemeurfr/patch-1
iherman Aug 16, 2017
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
5 changes: 3 additions & 2 deletions common/html/acknowledgements.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ <h2>Acknowledgements</h2>
<li>Marisa DeMeglio (DAISY Consortium)</li>
<li>Vagner Diniz (NIC.br - Brazilian Network Information Center)</li>
<li>Brady Duga (Google, Inc.)</li>
<li>Ben Dugas (Rakuten,Inc.)</li>
<li>Roger Espinosa (University of Michigan Library)</li>
<li>Reinaldo Ferraz (NIC.br - Brazilian Network Information Center)</li>
<li>Heather Flanagan (Invited Experts without Member Access)</li>
Expand Down Expand Up @@ -67,6 +68,7 @@ <h2>Acknowledgements</h2>
<li>Tzviya Siegman (Wiley)</li>
<li>Avneesh Singh (DAISY Consortium)</li>
<li>Susanna Skinner (HarperCollins Publishers)</li>
<li>David Stroup (Pearson plc)</li>
<li>Mateus Teixeira (W. W. Norton)</li>
<li>Jonathan Thurston (Pearson plc)</li>
<li>Daniel Weck (DAISY Consortium)</li>
Expand All @@ -80,7 +82,6 @@ <h2>Acknowledgements</h2>
</ul>

<p>The Working Group would also like to thank the members of the
<a href="https://www.w3.org/dpub/IG/"Digital Publishing Interest Group</a> for all the hard work
<a href="https://www.w3.org/dpub/IG/">Digital Publishing Interest Group</a> for all the hard work
they did paving the road for this specification.</p>
</section>

25 changes: 19 additions & 6 deletions common/js/biblio.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
/*
* WARNING: Use this file sparingly!
*
/*
* WARNING: Use this file sparingly!
*
* Check http://www.specref.org/ first
*
*
*/

/* general entry template
Expand All @@ -17,15 +17,28 @@
*/

var biblio = {
"PWPUB": {
"link-relation": {
"title": "Identifier: A Link Relation to Convey a Preferred URI for Referencing",
"authors": [
"H. Van de Sompel",
"M. Nelson",
"G. Bilder",
"J. Kunze",
"S. Warner"
],
"rawDate": "2017-08",
"publisher": "IETF",
"href": "https://tools.ietf.org/html/draft-vandesompel-identifier-00",
},
"pwpub": {
"title": "Packaged Web Publications",
"href": "https://w3.org/TR/pwpub/",
"authors": [
"..."
],
"date": "..."
},
"WPUB": {
"wpub": {
"title": "Web Publications",
"href": "https://w3.org/TR/wpub/",
"authors": [
Expand Down
243 changes: 185 additions & 58 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,54 +143,82 @@ <h3>Web Publications</h3>
<section id="terminology">
<h3>Terminology</h3>

<p>Wherever appropriate, this document relies on the terminology defined by the note on “Publishing and Linking on the Web”[[publishing-linking]]. In particular, the terms that are very important for this document include <a class="externalDFN" href="https://www.w3.org/TR/publishing-linking/#dfn-user">user</a>, <a class="externalDFN" href="https://www.w3.org/TR/publishing-linking/#dfn-user-agent">user agent</a>, <a class="externalDFN" href="https://www.w3.org/TR/publishing-linking/#dfn-browser">browser</a>, or <a class="externalDFN" href="https://www.w3.org/TR/publishing-linking/#dfn-address">address</a>.</p>

<dl>
<dt><dfn>Default Reading Order</dfn></dt>
<dd><p>The default reading order is a specific progression through the <a>primary resources</a> defined in
the <a>manifest</a> by the creator of a <a>Web Publication</a>.</p>
<p>A user might follow alternative pathways through the content, but in the absence of such interaction
the default reading order defines the expected progression from one primary resource to the
next.</p></dd>
<dt><dfn>URL</dfn></dt>
<dd>
<p>
In this specification, the general term URL is used as defined and used in other W3C specification like HTML&nbsp;[[html51]], and is defined by the relevant WhatWG document&nbsp;[[url]].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • editorial comments:
    • s/is used as defined and used/is used as/
    • s/in other W3C specification/in other W3C specifications/
    • s/the relevant WhatWG document/the URL Standard from WhatWG/
  • the ref to the URL standard is normative, so it should be [[!URL]], no?
  • shouldn't we use an unversionned reference to the HTML spec? (https://www.w3.org/TR/html/).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. Comments on comments:

  • I have changed to "Standard from WhatWG", we shall see what the W3C publishing rules will say about this.
  • The reference to URL is in a non-normative section, hence the reference itself cannot be normative (per pubrules...)

Otherwise done.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The reference to URL is in a non-normative section, hence the reference itself cannot be normative (per pubrules...)

ah, of course :) thanks!

In particular, such a URL allows for the usage of characters from Unicode following&nbsp;[[rfc3987]].
See <a href="https://www.w3.org/TR/html51/references.html#biblio-url">the note in the HTML5 document</a> for further details.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same question about using an unversionned reference

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

</p>
</dd>

<dt><dfn data-lt="IRI">IRI</dfn></dt>
<dd><p>An IRI, or Internationalized Resource Identifier, is an extension to the URI specification to allow
characters from Unicode. There is a mapping algorithm for translating between IRIs and the equivalent
encoded URI form. IRIs are defined by [[!rfc3987]].</p></dd>
<dt><dfn>Default Reading Order</dfn></dt>
<dd>
<p>
The default reading order is a specific progression through the <a>primary resources</a> defined in the <a>manifest</a> by the creator of a <a>Web Publication</a>.
</p>

<dt><dfn data-lt="Manifests">Manifest</dfn></dt>
<dd><p>A manifest represents structured information about a <a>Web Publication</a>, such as informative
metadata, a list of all <a data-lt="primary resource">primary</a> and <a>secondary resources</a>, and
the <a>default reading order</a>.</p></dd>
<p>
A user might follow alternative pathways through the content, but in the absence of such interaction the default reading order defines the expected progression from one primary resource to the next.
</p>
</dd>

<dt><dfn data-lt="Primary Resources">Primary Resource</dfn></dt>
<dd><p>A primary resource is one that is listed in the <a>default reading order</a> of a <a>Web
Publication</a>.</p></dd>
<dd>
<p>
A primary resource is one that is listed in the <a>default reading order</a> of a <a>Web Publication</a>.
</p>
</dd>

<dt><dfn data-lt="Secondary Resources">Secondary Resource</dfn></dt>
<dd><p>A secondary resource is one that is required for the processing or rendering of a <a>primary
resource</a>.</p></dd>

<dt><dfn data-lt="Web Publications">Web Publication</dfn></dt>
<dd><p>A Web Publication is a collection of one or more <a>primary resources</a>, organized together through
a <a>manifest</a> into a single logical work with a <a>default reading order</a>. The Web Publication
is uniquely identifiable and presentable using Open Web Platform technologies.</p></dd>

<dt><dfn data-lt="Web Publication Canonical Identifier">Web Publication Canonical Identifier</dfn></dt>
<dd><p>A Web Publication canonical identifier is assigned to a Web Publication by the publisher.
It SHOULD be a dereferenceable IRI and the Web Publication Address. If not, it MUST be possible to
make a 1-to-1 mapping to the Web Publication Address. If a dereferenceable IRI it MAY be used as the
value of the href attribute of a canonical link element (i.e., a link element with a
rel='canonical' attribute).</p></dd>

<dt><dfn data-lt="Web Publication Identifier">Web Publication Identifier</dfn></dt>
<dd><p>A Web Publication identifier is metadata that is intended to be used to refer to a Web Publication
in a persistent and unambiguous manner. IRIs, URIs, DOIs, ISBNs, PURLs are all examples of
identifiers frequently used in publishing.</p></dd>

<dt><dfn data-lt="Web Publication Address">Web Publication Address</dfn></dt>
<dd><p>A Web Publication Address is a URL or other dereferenceable IRI which refers to the location of a
Web Publication and enables the retrieval of a representation of the manifest of the Web
Publication.</p></dd>

<dd>
<p>
A secondary resource is one that is required for the processing or rendering of a <a>primary resource</a>.
</p>
</dd>

<dt><dfn data-lt="Manifests">Manifest</dfn></dt>
<dd>
<p>
A manifest represents structured information about a <a>Web Publication</a>, such as informative metadata, a list of all <a data-lt="primary resource">primary</a> and <a>secondary resources</a>, and the <a>default reading order</a>.
</p>
</dd>

<dt><dfn data-lt="WP|Web Publications">Web Publication</dfn></dt>
<dd>
<p>
A Web Publication is a collection of one or more <a>primary resources</a>, organized together through a <a>manifest</a> into a single logical work with a <a>default reading order</a>.
The Web Publication is uniquely identifiable and presentable using Open Web Platform technologies.
</p>
</dd>

<dt><dfn data-lt="Identifier|WP Identifier">(Persistent) Identifier</dfn></dt>
<dd>
<p>
An identifier is a metadata that can be used to refer to a <a class="externalDFN" href="https://www.w3.org/TR/publishing-linking/#dfn-web-content">Web Content</a> in a persistent and unambiguous manner.
URLs, URNs, DOIs, ISBNs, or PURLs are all examples of identifiers frequently used in publishing.
</p>
</dd>

<dt><dfn data-lt="WP Address">Web Publication Address</dfn></dt>
<dd>
<p>
A Web Publication Address is a <a>URL</a> that refers to a <a>Web Publication</a> and enables the retrieval of a representation of the <a>manifest</a> of the <a>Web Publication</a>.
</p>
</dd>

<dt><dfn data-lt="WP Canonical Identifier|canonical identifier">Web Publication Canonical Identifier</dfn></dt>
<dd>
<p>
A Web Publication canonical identifier is an <a>identifier</a> assigned to a <a>Web Publication</a> by the publisher.
It SHOULD either be a <a>Web Publication Address</a>, or it MUST be possible to make a 1-to-1 mapping to a <a>Web Publication Address</a>.
If it is URL, it MAY be used as the value of the <code>href</code> attribute of a canonical link element (i.e., a <code>link</code> element with a <code>rel='canonical'</code> attribute&nbsp;[[rfc6596]]).
</p>
</dd>

</dl>
</section>
</section>
Expand Down Expand Up @@ -223,26 +251,125 @@ <h3>Introduction</h3>
<div class="ednote"> Placeholder for introduction to manifests. </div>
</section>

<section id="manifest-metadata">
<section>
<h2>Abstract versus Concrete Manifest</h2>

<p>This specification defines the content of a <a>manifest</a> on two levels.</p>

<ul>
<p>
An <dfn>abstract manifest</dfn> is defined to identify what type of information is necessary at the <a>Web Publication</a> level (as opposed to individual resource level) for a user agent to process the publication properly.
</p>

<p>
The <dfn>concrete manifest</dfn> defines the file format(s), encodings, etc., used to represent the <a>abstract manifest</a>, and how those file(s) can be accessed. The same <a>abstract manifest</a> MAY be expressable via different concrete manifest formats.
</p>
</ul>

<p class="ednote">As discussed on the <a href="https://www.w3.org/publishing/groups/publ-wg/Meetings/Minutes/2017/2017-08-14-minutes">group teleconference on the 2017-08-14</a>, the separation of these two terms may be temporary, and subsequent editorial passes may merge the two notions.</p>
</section>
<section>
<h2 id="abstractmanifest">The abstract manifest</h2>

<p>An <a>abstract manifest</a> should contain the following information.</p>

<ol>
<li>It MUST assert WP-ness.</li>
<li>It MUST list the <a>Primary Resources</a> of the WP.</li>
<li>It SHOULD list <a>Secondary Resources</a>, although that list is not necessarily exhaustive.</li>
<li>
It MUST include a <a>WP Address</a>.
Availability of this address does not preclude the creation and use of other identifiers and/or addresses to retrieve a representation of a <a>Web Publication</a> in whole or part.
</li>
<li>
It SHOULD include a <a>Canonical Identifier</a>.
If assigned, this <a>Canonical Identifier</a> MUST be unique to the <a>Web Publication</a>.
</li>
<li>It SHOULD include a title (or “name”).</li>
<li>It SHOULD indicate the default (natural) language.</li>
<li>It MUST indicate a <a>default reading order</a>.</li>
</ol>

<div class="note">The <a>Web Publication Address</a> can also be used as value for an identifier link relation[[link-relation]].</div>

<p class="enote">These requirements reflect the current minimum consensus, though a number of issues remain open. The issues may usually lead to a “MUST” instead of a “SHOULD” in the list above.</p>

<p class="issue" data-number="15">Ignoring issues such as location, serialization, etc. What is the minimum viable manifest?</p>

<div class="issue" data-number="20">
<p></p>(See also <a href="https://github.com/w3c/wpub/issues/24">issue #24</a>.) The question is whether the WP MUST include a title or not.</p>

<p>Note that this is the question for the <a>abstract manifest</a>. How that information is acquired may also depend on the <a href="#fallback">fallback mechanism</a>. </p>
</div>

<p class="issue" data-number="21">
Whether the minimum manifest must include any metadata, or a specific slot to handle metadata
</p>

<p class="issue" data-number="22">The discussion led to the question whether the manifest MUST list all <a>Secondary resources</a> or not. In this sense, this became a duplicate of <a href="https://github.com/w3c/wpub/issues/23">issue #23</a> ended up at the same question. </p>

<p class="issue" data-number="23">The question is whether the manifest MUST list all <a>Secondary resources</a> or not.</p>

<p class = "issue" data-number="29">Should Natural Langauge be Required for the Publication for WCAG 2 Compliance?</p>

<!-- <p class = "issue" data-number="30">Should Title be Required for the Publication for WCAG 2 Compliance? </p> -->
</section>

<section>
<h2>The Concrete Manifest</h2>

<p class="issue" data-number="7">Format of the Manifest (JSON, XML, embedded into HTML, etc.).</p>
<p class="issue" data-number="13">If we have a collection of information about a web publication as a whole ("manifest") that exists separately from most of the publication's resources, we need to find a way to associate the manifest with the other publication resources.</p>
<p class="issue" data-number="25"></p>
<p class="issue" data-number="26">Should the TOC be a separate HTML file or is the listing of primary resources in the manifest an implicit TOC?</p>
<p class="issue" data-number="32"></p>
</section>

<section id="fallback">
<h3>Fallback mechanisms</h3>

<p>In some cases, some manifest items, even if required for an <a>abstract manifest</a>, are not necessarily expressed in a <a>concrete manifest</a> explicitly. For some of these cases “fallback mechanisms” are defined, i.e., simple algorithms whereby a <a class="externalDFN" href="https://www.w3.org/TR/publishing-linking/#dfn-user-agent">user agent</a> can reconstruct the manifest item. These are:</p>

<dl>
<dt>title</dt>
<dd>If the title is not specified in the concrete manifest, a user agent MUST:
<ul>
<li>
if a WP contains a single primary resource with a <code>title</code> element appropriate for its type (e.g., SVG or HTML titles), then that becomes the WP’s title;
</li>
<li>
otherwise, if a WP contains several primary resources with title elements appropriate for their types, the user agent uses the title of the first resource in the <a>default reading order</a>;
</li>
<li>
otherwise, the UA uses its own heuristics.
Note that a URL or a filename is not considered to be a valid title.
</li>
</ul>
</dd>
<dt>(natural) language</dt>
<dd>If the language is not specified in the concrete manifest, a user agent MUST:
<ul>
<li>
if a WP contains a single primary resource with a language element appropriate for its type (e.g., SVG or HTML language tags), then that becomes the WP’s language;
</li>
<li>
otherwise, if a WP contains several primary resources with a language element appropriate for their types, the user agent uses the language of the first resource in the default reading order;
</li>
<li>
otherwise, the language is English.
</li>
</ul>
</dd>
</dl>
</section>




<section id="metadata">
<h3>Metadata</h3>

<div class="ednote"> Placeholder for explanation of metadata requirements for publications. </div>

<section>
<h4>Identifier Metadata</h4>
<p>When published, a Web Publication SHOULD be assigned a canonical identifier. This canonical identifier MUST be unique
to the Web Publication and, if assigned, MUST be included in the Web Publication manifest. The Identifying IRI
(i.e., the canonical identifier if it is an IRI or the locator mapped from the canonical identifier) MUST enable
the retrieval of a representation of the manifest of the Web Publication. The Identifying IRI does not preclude
the creation and use of other identifiers and / or locators to retrieve a representation of a Web Publication
in whole or part.</p>
<div class="note">The Identifying IRI can also be used as value for an identifier link relation
[[https://tools.ietf.org/html/draft-vandesompel-identifier-00#section-3.1]].</div>

<div class="ednote"> Placeholder for further explanation of additional publication identifier metadata,
e.g., identifier and locator metadata associated with secondary (and primary?) resources. </div>
</section>
</section>

<section id="manifest-resources">
<h3>Resources</h3>
Expand Down