From f324dc38d9434247adee53ca7f4a82b5ae37b552 Mon Sep 17 00:00:00 2001 From: Matt Garrish Date: Mon, 13 Nov 2017 21:03:00 -0500 Subject: [PATCH] various editorial and structural changes --- common/js/biblio.js | 15 +- index.html | 975 ++++++++++++++++++++------------------------ 2 files changed, 464 insertions(+), 526 deletions(-) diff --git a/common/js/biblio.js b/common/js/biblio.js index c5dc4e0..4ab38c6 100644 --- a/common/js/biblio.js +++ b/common/js/biblio.js @@ -41,7 +41,7 @@ var biblio = { ], "rawDate": "2017-08", "publisher": "IETF", - "href": "https://tools.ietf.org/html/draft-vandesompel-identifier-00", + "href": "https://tools.ietf.org/html/draft-vandesompel-identifier-00" }, "cfi": { "authors" : [ @@ -60,6 +60,15 @@ var biblio = { rawDate: "2017-01-05", status: "Recommended Specification" }, + "pub-loc": { + "title": "Locators for Web Publications", + "href": "https://w3.org/TR/pub-loc/", + "authors": [ + "Timothy W. Cole", + "Ivan Herman" + ], + "date": "..." + }, "pwpub": { "title": "Packaged Web Publications", "href": "https://w3.org/TR/pwpub/", @@ -72,8 +81,8 @@ var biblio = { "title": "Web Publications", "href": "https://w3.org/TR/wpub/", "authors": [ - "Dave Cramer", - "Matt Garrish" + "Matt Garrish", + "Ivan Herman" ], "date": "..." } diff --git a/index.html b/index.html index 78cd8ff..b39e2e0 100644 --- a/index.html +++ b/index.html @@ -107,9 +107,9 @@

This specification defines a collection of information that describes the structure of Web Publications, so - that user agents or developers may create user experiences well-suited to reading publications, such as - sequential navigation and offline reading. This information includes the default reading order, a list of - resources, and publication-wide metadata.

+ that user agents can provide user experiences well-suited to reading publications, such as sequential + navigation and offline reading. This information includes the default reading order, a list of resources, and + publication-wide metadata.

This first public working draft provides a preliminary outline of a Web Publication. Many details are under @@ -132,9 +132,9 @@

Why Web Publications

is not all doom and gloom. Through the power of Web pages, these resources can be brought together to create amazing experiences.

-

Web sites add another layer of relationship — this time between pages — but the relationship is a tenuous - one that typically depends on hyperlinks to add cohesion. Without a user that understands how to follow - the connections, a Web site is still no more than a loose coupling of information.

+

Web sites add another layer of relationship—this time between pages—but the relationship is a tenuous one + that typically depends on hyperlinks to add cohesion. Without a user that understands how to follow the + connections, a Web site is still no more than a loose coupling of information.

The preceding is not a critique of the Web, but meant to highlight that the modern Web is very much an active, event-driven experience. Users follow the necessary paths to obtain the information they @@ -169,15 +169,15 @@

Why Web Publications

What is a Web Publication

-

A Web Publication is a discoverable and identifiable collection of information about a publication and its - resources. This information is expressed in a machine-readable document called a manifest, which - is what enables user agents to understand the bounds of the Web Publication and connection between its - resources.

+

A Web Publication is a discoverable and identifiable collection of information about a publication + and its resources. This information is expressed in a machine-readable document called a manifest, + which is what enables user agents to understand the bounds of the Web Publication and the connection + between its resources.

-

The manifest includes metadata that describes the Web Publication, as it has an identity and nature beyond - its constituent resources. The manifest also provides a list of all the resources that belong to the Web - Publication and the default reading order, which is how it connects resources into a single contiguous - work.

+

The manifest includes metadata that describes the Web Publication, as a publication has an identity and + nature beyond its constituent resources. The manifest also provides a list of all the resources that + belong to the Web Publication and the default reading order, which is how it connects resources into a + single contiguous work.

A Web Publication is discoverable in one of two ways: resources either include a link to the manifest (via an HTTP Link header or an [[!html]] link element), or the manifest can be loaded directly by @@ -197,7 +197,7 @@

Scope

Moreover, the specification is designed to adapt automatically to updates to Open Web Platform technologies in order to ensure that Web Publications continue to interoperate seamlessly as the Web - evolves (e.g., by referencing the latest published versions instead of specific versions).

+ evolves (e.g., by referencing the latest published versions instead of specific dated versions).

Further, this specification does not attempt to constrain the nature of a Web Publication: any type of work that can be represented on the Web constitutes a potential Web Publication.

@@ -226,7 +226,7 @@

Web App Manifest

web publications versus installation for applications).

The working assumption is that both applications and publications can use the same manifest and - serialization to express the information necessary to initiate both.

+ serialization to express the information necessary to initiate themselves.

The initial stage of evaluating this assumption involves:

@@ -236,13 +236,13 @@

Web App Manifest

in [[appmanifest]]. -

The next stage will involve the serialization of the infoset in JSON, and see how this expression - of the manifest can be aligned with the expression of the [[appmanifest]]. Wherever semantically - possible, the terms used and defined for [[appmanifest]] should be reused, and, conversely, some - of the members defined for Web Publications may be generally useful for applications and may be - added to the [[appmanifest]] as a common pool of information. To avoid possible future conflicts, - care should be taken to use a naming schemes that clearly separates terms to be used for Web - Publications only.

+

The next stage will involve the serialization of the infoset in JSON to see how this + expression of the manifest can be aligned with the expression of the [[appmanifest]]. Wherever + semantically possible, the terms used and defined for [[appmanifest]] will be reused, and, + conversely, some of the members defined for Web Publications may be generally useful for + applications and may be added to the [[appmanifest]] as a common pool of information. To avoid + possible future conflicts, care will be taken to use a naming scheme that clearly separates terms + to be used for Web Publications only.

This specification consequently should be read and understood in this context of an ongoing investigation, and that significant changes may occur in the future.

@@ -267,7 +267,7 @@

Terminology

class="externalDFN" href="https://www.w3.org/TR/publishing-linking/#dfn-address">address.

-
Identifier
+
Identifier

An identifier is metadata that can be used to refer to Web Content in a @@ -289,11 +289,11 @@

Terminology

normalization, where whitespace normalization rules are defined per the host format.

-
URL
+
URL
-

In this specification, the general term URL is used as in other W3C specifications like - HTML [[!html]], and is defined by URL Standard of the WhatWG [[!url]]. In particular, - such a URL allows for the usage of characters from Unicode following [[!rfc3987]]. See The general term URL is defined by the URL Standard [[!url]]. It is used as in other W3C + specifications, like HTML [[!html]]. In particular, a URL allows for the usage of characters + from Unicode following [[!rfc3987]]. See the note in the HTML5 document for further details.

@@ -318,15 +318,15 @@

Conformance Classes

criteria:

    -
  • It MUST have a manifest that conforms to .
    • +
  • it has a manifest that conforms to ;
    • +
  • ot adheres to the construction requirements defined in .

A user agent is conformant to this specification if it meets the following criteria:

    -
  • It MUST be capable of generating a conforming infoset for a Web - Publication.
    • +
  • it is capable of generating a conforming infoset for a Web Publication.
@@ -335,57 +335,64 @@

Information Set

The name "infoset" may change depending on feedback. Although this term has a different meaning for individuals familiar with XML, alternatives such as "properties" and "metadata" do not fully capture the - nature or purpose. See issue #63 for discussion.

+ nature or purpose of the collected information. See issue + #63 for discussion.

As the serialization of the manifest remains an open issue, specifics about how properties are compiled into the infoset remain unspecified. This includes, but is not limited to, what specific names the properties will have in the infoset, whether the names in the manifest will be the same as those in the infoset and/or whether mappings to properties from known vocabularies will be used.

-
+

Explanation

-

A Web Publication is defined by a set of properties known as its information - set (infoset). The infoset is both abstract and concrete. It is abstract in the sense that it - represents a set of information that a user agent has to be able to compile about the Web Publication, - but it also becomes concrete when the user agent creates an internal representation of the - information.

+

A Web Publication is defined by a set of properties known as its information + set (infoset). The infoset is logically divided into two sets of properties: those that + describe the publication and those that express key structures. These classifications only exist for the + purposes of understanding the function of the properties, however.

-

The infoset does not require a specific serialization. It is primarily compiled from a Web Publication's - manifest, whose serialization requirements are defined in . It is therefore possible to express the same infoset via different manifests, although a Web - Publication will only have one manifest.

+

The infoset is both abstract and concrete. It is abstract in the sense that it represents a set of + information that a user agent has to compile about the Web Publication, but it also becomes concrete when + the user agent creates an internal representation of that information.

-

Although the manifest is the primary source of the infoset, some information may be obtained independent - of it. For example, fallback rules for properties defined in the following subsections allow a user agent - to compile information that the author has not provided in the manifest, whether as an intentional - optimization or by accidental omission.

+

The infoset is primarily compiled from a Web Publication's manifest, whose serialization + requirements are defined in . Some information can be obtained in + outside the manifest, however. For example, fallback rules for properties defined in the following + subsections allow a user agent to compile information that the author has not provided in the manifest, + whether as an intentional optimization or by accidental omission.

Requirements

-

The Web Publication infoset MUST include the following information:

- - - -

In addition, the infoset SHOULD include the following information:

+

The requirements for the expression of infoset properties are as follows:

- +
+
Descriptive Properties
+
+

REQUIRED: address

+ +
+
Structural Properties
+
+

REQUIRED: default reading order and resource list

+

RECOMMENDED: table of contents

+
+

These requirements reflect the current minimum consensus, though a number of issues remain open that could change whether an item is required or recommended. See the following sections for more @@ -395,261 +402,301 @@

Requirements

to handle metadata. (Note: this is now more specifically related to the infoset.)

-
-

Title

- -

The title provides the human-readable name of the Web Publication.

+
+

Descriptive Properties

-

When specified in the manifest, the title MUST be non-empty.

+
+

Accessibility

-

If a user agent requires a title and one is not available in the infoset, it MAY create one. This - specification does not mandate how such a title is created. The user agent might:

+

Accessibility metadata allows the discovery of features and affordances of the Web Publication + that enable its use by users with different reading requirements and needs.

-
    -
  • use the first non-empty - title element found in the default reading order;
    • -
  • provide a language-specific placeholder title (e.g., 'Untitled Publication');
    • -
  • use the URL of the manifest;
    • -
  • calculate a title using its own algorithm.
    • -
+

How to express accessibility metadata remains to be determined. This could be a + grouping of properties from schema.org, for example, or could be split out into a list of individual + properties.

+
-
-

A user agent is not expected to produce a meaningful title [[wcag20]] - for a Web Publication when one is not specified.

-
-
+
+

Address

-
-

Creators

+

A Web Publication's + address is a URL that refers to the Web Publication. It dereferences to the landing page, which enables the retrieval of a representation of the + manifest.

-

Creators are the individuals or entities responsible for the creation of the Web Publication.

+

The availability of this address does not preclude the creation and use of other identifiers and/or + addresses to retrieve a representation of a Web Publication in whole or part.

-

The role the creator played in the creation of the Web Publication SHOULD also be specified (e.g., - 'author', 'illustrator', 'translator').

-
+
The Web Publication's address can also be used as value for an identifier link relation + [[link-relation]].
+
-
-

Language

+
+

Base Direction

-

The language specified in the Web Publication's infoset identifies the natural language(s) of its - content.

+

The base direction identifies the display direction for infoset properties.

-

This language is not used in the processing or rendering of the Web Publication (including the manifest), - and is not a replacement for identifying the language of each resource as defined by its - format. It instead allows a user agent to ability to provide supplementary enhancements, such as the - ability to download a custom dictionary or the preload a language-specific text-to-speech module.

+

The value of this property MUST be one of:

-

When specified, the language MUST be a tag that conforms to [[!bcp47]].

+
+
ltr
+
left-to-right
+
rtl
+
right-to-left
+
auto
+
direction is determined from the value of the property
+
-

If a user agent requires the language and one is not available in the infoset, it MAY attempt to determine - the language. This specification does not mandate how such a language tag is created. The user agent - might:

+

If not specified, the value ltr SHOULD be assumed.

-
    -
  • use the non-empty language declaration of the manifest;
    • -
  • use the first non-empty language declaration found in the default reading order;
    • -
  • calculate the language using its own algorithm.
    • -
+

If property values are harvested from another resource, such as the table of contents, + precedence SHOULD be given to the base direction specified in the resource, when provided.

+
-

If a language tag cannot be determined, the value "und" (undetermined) MUST be used.

+
+

Canonical Identifier

+ +

A Web Publication's + canonical identifier is a unique identifier that resolves to the preferred version of the + Web Publication. The canonical identifier SHOULD be an address, but, if not, it MUST be + possible to make a one-to-one mapping to an address (e.g., a DOI can be resolved to a URL via a DOI + resolver).

+ +

If a Web Publication is hosted at more than one address, this identifier allows a user agent to + identify the shared relationship between the versions and to determine which of the available + addresses is primary.

+ +

The canonical identifier is also intended to provide a measure of permanence above and beyond the Web + Publication's address. Even if a Web Publication is permanently relocated to a new address, for + example, the canonical identifier will provide a way of locating the new location (e.g., a DOI + registry could be updated with the new URL, or a redirect could be added to the URL of the canonical + identifier).

+ +

When assigned, the canonical identifier needs to be unique to one and only one Web Publication, + independent of its address(es). Ensuring uniqueness is outside the scope of this specification, + however. The actual uniqueness achievable depends on such factors as the conventions of the + identifier scheme used and the degree of control over assignment of identifiers.

+ +

If the canonical identifier is a URL, it can be used as the target of a "canonical" + link [[rfc6596]] (e.g., an [[html]] link element whose rel attribute + has the value canonical or a Link HTTP header field [[rfc5988]] similarly + identified).

+ +

The question is whether a canonical identifier is necessary to call out + explicitly in the infoset, or whether it is/can be handled by other metadata.

+
-
-

The question is whether the language declared for the manifest content is the same as the language of - the publication, and how to deal with multilingual publications.

-
-
+
+

Creators

-
-

Canonical Identifier

+

Creators are the individuals or entities responsible for the creation of the Web + Publication.

-

A Web Publication's - canonical identifier is a unique identifier that resolves to the preferred version of the Web - Publication. The canonical identifier SHOULD be an address, but, if not, it MUST be possible to - make a one-to-one mapping to an address (e.g., a DOI can be resolved to a URL via a DOI resolver).

+

The role the creator played in the creation of the Web Publication SHOULD also be specified (e.g., + 'author', 'illustrator', 'translator').

+
-

If a Web Publication is hosted at more than one address, this identifier allows a user agent to identify - the shared relationship between the versions and to determine which of the available addresses is - primary.

+
+

Language

-

The canonical identifier is also intended to provide a measure of permanence above and beyond the Web - Publication's address. Even if a Web Publication is permanently relocated to a new address, for example, - the canonical identifier will provide a way of locating the new location (e.g., a DOI registry could be - updated with the new URL, or a redirect could be added to the URL of the canonical identifier).

+

The language specified in the Web Publication's + infoset identifies the natural language of its properties.

-

When assigned, the canonical identifier needs to be unique to one and only one Web Publication, - independent of its address(es). Ensuring uniqueness is outside the scope of this specification, however. - The actual uniqueness achievable depends on such factors as the conventions of the identifier scheme used - and the degree of control over assignment of identifiers.

+

When specified, the language MUST be a tag that conforms to [[!bcp47]].

-

If the canonical identifier is a URL, it can be used as the target of a "canonical" - link [[rfc6596]] (e.g., an [[html]] link element whose rel attribute has - the value canonical or a Link HTTP header field [[rfc5988]] similarly identified).

+

This language is not used in the processing or rendering of the Web Publication, and is + not a replacement for identifying the language of each resource as defined by + its format.

-

The question is whether a canonical identifier is necessary to call out - explicitly in the infoset, or whether it is/can be handled by other metadata.

-
+

If a user agent requires the language and one is not available in the infoset, it MAY attempt to + determine the language. This specification does not mandate how such a language tag is created. The + user agent might:

-
-

Address

+
    +
  • use the non-empty language declaration of the manifest;
    • +
  • use the first non-empty language declaration found in a resource in the default reading + order;
    • +
  • calculate the language using its own algorithm.
    • +
-

A Web Publication's address is a URL that refers to a Web Publication and enables - the retrieval of a representation of the manifest of the Web Publication.

+

If a language tag cannot be determined, the value "und" (undetermined) MUST be used.

-

The availability of this address does not preclude the creation and use of other identifiers and/or - addresses to retrieve a representation of a Web Publication in whole or part.

+
+

The question is whether the language declared for the manifest content is the same as the language + of the publication, and how to deal with multilingual publications.

+
+
-
The Web Publication's address can also be used as value for an identifier link relation - [[link-relation]].
-
+
+

Last Modification Date

-
-

Resource List

+

The last modification date is the date when the Web Publication was last + updated.

-

The infoset MUST include a list of the Web Publication's resources, although the list is not - required to be exhaustive. Resources in the default reading order MUST be included in this - list.

+

The last modification date SHOULD be updated whenever changes are made to the resources of the Web + Publication, including the manifest. It does not necessarily reflect all changes to the Web + Publication, however, as, for example, it might not reflect changes to third-party content.

+
-

The discussion led to the question whether the manifest/infoset MUST list - all resources or not. In this sense, this became a duplicate of issue #23 ended up at the same question.

+
+

Publication Date

-

The question is whether the manifest/infoset MUST list all resources or - not.

+

The publication date is the date on which the Web Publication was originally + published. It represents a static event in the lifecycle of a Web Publication and allows subsequent + revisions to be identified and compared.

-

The question is whether the manifest MUST list resources in the default - reading order or whether this can be inferred.

-
+

The exact moment of publication is intentionally left open to interpretation: it could be when the Web + Publication is first made available online or could be a point in time before publication when the + Web Publication is considered final.

+
-
-

Default Reading Order

+
+

Privacy Policy

-

The default reading order is a specific progression through a set of Web Publication - resources.

+

Users often have the legal right to know and control what information is collected about them, how + such information is stored and for how long, whether it is personally identifiable, and how it can be + expunged. Including a statement that addresses all such privacy concerns is consequently an important + part of publishing Web Publications. Even if no information is collected, such a declaration + increases the trust users have with the content.

-

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 resource to the next.

+

To address this concern, the infoset allows a link to be provided to a privacy policy. The privacy + policy does not have to be a resource of the Web Publication, although including it as a resource is + RECOMMENDED.

-

The default reading order MUST include at least one resource.

+

Refer to for more information about privacy considerations in Web + Publications.

+
-

The default reading order is either specified directly in the manifest or a link is provided to an - [[!html]] nav element whose list of links are processed to create one.

+
+

Title

-

The process for extracting a default reading order from a nav element are as follows:

+

The title provides the human-readable name of the Web Publication.

-
    -
  1. extract a list of resource paths referenced from the href attribute of all - a elements;
    2. -
  2. strip any fragment identifiers from the references;
    3. -
  3. resolve all relative paths to full URLs;
    4. -
  4. remove all consecutive references to the same resource, leaving only the first.
    5. -
+

When specified in the manifest, the title MUST be non-empty.

-

If a user agent requires a default reading order and one is not provided in the infoset, it MAY - attempt to construct one. This specification does not mandate how such a default reading order is - created. The user agent might:

+

If a user agent requires a title and one is not available in the infoset, it MAY create one. + This specification does not mandate how such a title is created. The user agent might:

-
    -
  • use only the resource the user accessed to reach the manifest;
    • -
  • search the list of resources for a nav element to use;
    • -
  • calculate the default reading order using its own algorithm.
    • -
+
    +
  • use the first non-empty + title element found in a resource in the default reading order;
    • +
  • provide a language-specific placeholder title (e.g., 'Untitled Publication');
    • +
  • use the URL of the manifest;
    • +
  • calculate a title using its own algorithm.
    • +
-

Define the default reading order of a Web Publication to be the files - referenced in the first

-

There is a consensus that a Web Publication must have a reading order and - must/should have a table of contents (the main navigation entry point).

+
+

A user agent is not expected to produce a meaningful title + [[wcag20]] for a Web Publication when one is not specified.

+
+
-
-

Table of Contents

+
+

Structural Properties

-

The table of contents is a hierarchical list of links that reflects the structural outline of - the major sections of the Web Publication. There are no requirements on the completeness of the table of - contents, except that, when specified, it MUST link to at least one resource.

+
+

Default Reading Order

-

The table of contents is either specified directly in the manifest or a link is provided to an [[!html]] - nav element containing one.

+

The default reading order is a specific progression through a set of Web Publication + resources.

-

If a user agent requires a table of contents and one is not specified, it MAY construct one. This - specification does not mandate how such a table of contents is created. The user agent might:

+

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 resource to the next.

-
    -
  1. attempt to locate a table of contents in the default reading order (e.g., an HTML document with a - nav element that has the role attribute value - doc-toc);
    2. -
  2. use the titles of resources in the default reading order;
    3. -
  3. calculate a table of contents using its own algorithms.
    4. -
+

The default reading order MUST include at least one resource.

-

This section should be brought in sync with the section on landing page.

+

The default reading order is either specified directly in the manifest or a link is provided to an + [[!html]] nav element whose list of links are processed to create one.

-

The question is whether the manifest/infoset needs to provide navigation, or - whether such mechanisms belong in the content.

+

The process for extracting a default reading order from a nav element are as follows:

-

This question arises only if this mechanism is accepted: the question is whether a table of - contents navigation element can refer, via links, to any resource that is not listed in the - default reading order.

+
    +
  1. extract a list of resource paths referenced from the href attribute of all + a elements;
    2. +
  2. strip any fragment identifiers from the references;
    3. +
  3. resolve all relative paths to full URLs;
    4. +
  4. remove all consecutive references to the same resource, leaving only the first.
    5. +
-
-

The issue of using the HTML nav element as a possible encoding of the table of contents - is mentioned or explicitly addressed in the following issues:

+

If a user agent requires a default reading order and one is not provided in the infoset, it MAY + attempt to construct one. This specification does not mandate how such a default reading order is + created. The user agent might:

    -
  • Issue #35: Define the resources in the - default reading order of a Web Publication to be the files referenced in the first
    • -
  • Issue #39: There is a consensus that a Web - Publication must have a reading order and must/should have a table of contents (the main - navigation entry point).
    • +
  • use only the resource the user accessed to reach the manifest;
    • +
  • search the list of resources for a nav element to use;
    • +
  • calculate the default reading order using its own algorithm.
-
-
-
-

Publication Date

+

Define the default reading order of a Web Publication to be the files + referenced in the first

+

There is a consensus that a Web Publication must have a reading order + and must/should have a table of contents (the main navigation entry point).

+
-

The publication date is the date on which the Web Publication was originally published. It - represents a static event in the lifecycle of a Web Publication and allows subsequent revisions to be - identified and compared.

+
+

Resource List

-

The exact moment of publication is intentionally left open to interpretation: it could be when the Web - Publication is first made available online, or could be a point in time before publication when the Web - Publication is considered final.

-
+

The infoset MUST include a list of the Web Publication's resources, although the list is not + required to be exhaustive. Resources in the default reading order MUST be included in this + list.

-
-

Last Modification Date

+

The discussion led to the question whether the manifest/infoset MUST + list all resources or not. In this sense, this became a duplicate of issue #23 ended up at the same question.

-

The last modification date is the date when the Web Publication was last updated.

+

The question is whether the manifest/infoset MUST list all resources or + not.

-

The last modification date SHOULD be updated whenever changes are made to the resources of the Web - Publication, including the manifest. It does not necessarily reflect all changes to the Web Publication, - however, as, for example, it might not reflect changes to third-party content.

-
+

The question is whether the manifest MUST list resources in the default + reading order or whether this can be inferred.

+
+ +
+

Table of Contents

-
-

Accessibility Metadata

+

The table of contents is a hierarchical list of links that reflects the structural outline + of the major sections of the Web Publication. There are no requirements on the completeness of the + table of contents, except that, when specified, it MUST link to at least one resource.

-

Accessibility metadata allows discovery of features and affordances of the Web Publication that enable its - usability by users with specific reading requirements and needs.

-
+

The table of contents is either specified directly in the manifest or a link is provided to an + [[!html]] nav element containing one.

+ +

If a user agent requires a table of contents and one is not specified, it MAY construct one. This + specification does not mandate how such a table of contents is created. The user agent might:

-
-

Privacy Policy

+
    +
  1. attempt to locate a table of contents in the default reading order (e.g., an HTML document with a + nav element that has the role attribute value + doc-toc);
    2. +
  2. use the titles of resources in the default reading order;
    3. +
  3. calculate a table of contents using its own algorithms.
    4. +
-

Users often have the legal right to know and control what information is collected about them, how such - information is stored and for how long, whether it is personally identifiable, and how it can be - expunged. Including a statement that addresses all such privacy concerns is consequently an important - part of publishing Web Publications. Even if no information is collected, such a declaration increases - the trust users have with the content.

+

This section should be brought in sync with the section on landing page.

-

To address this concern, the infoset allows a link to be provided to a privacy policy. The privacy policy - does not have to be a resource of the Web Publication, although including it as a resource is - RECOMMENDED.

+

The question is whether the manifest/infoset needs to provide + navigation, or whether such mechanisms belong in the content.

-

Refer to for more information about privacy considerations in Web - Publications.

+

This question arises only if this mechanism is accepted: the question is whether a table + of contents navigation element can refer, via links, to any resource that is not listed in + the default reading order.

+ +
+

The issue of using the HTML nav element as a possible encoding of the table of + contents is mentioned or explicitly addressed in the following issues:

+
    +
  • Issue #35: Define the resources in the + default reading order of a Web Publication to be the files referenced in the first.
    • +
  • Issue #39: There is a consensus that a + Web Publication must have a reading order and must/should have a table of contents (the main + navigation entry point).
    • +
+
+
@@ -660,7 +707,7 @@

Extensibility

  1. through the inclusion of additional properties in the manifest;
    2. -
  2. by the provision of linked metadata records.
    3. +
  3. by the provision of linked metadata records.

User Agents MAY support additional properties but MUST NOT include unrecognized properties in the infoset. @@ -693,81 +740,45 @@

Requirements

Declaration

A description of how a manifest declares it describes a web publication will be included - in a future version, as such a mechanism will depend on integration with [[appmanifest]].
+ in a future draft, as such a mechanism will depend on integration with [[appmanifest]].

Serialization

+

The manifest is serialized as a JSON document [[!ecma-404]].

+ +
Additional serialization details will be included in a future draft, as these will depend + on integration with [[appmanifest]].
+

Should the table of contents be a separate HTML file or is the listing of resources in the default reading order an implicit table of contents?

- -
-

Linking from a Manifest

- -

The manifest serialization MUST provide a general linking mechanism for defining a relationship between - the Web Publication and other resources on the Web as well as the type of those relationships.

- -

This mechanism is used in to express many parts of the Web Publication's infoset, including but not - limited to:

- -
    -
  • Canonical identifier using the rel='canonical' - link relation. [[rfc6596]]
    • -
  • Table of Contents in the cases where the ToC is specified as a - link to an HTML nav element.
    • -
  • External metadata that may be expressed in established vocabularies such - as ONIX, MARC, schema.org, or Dublin Core.
    • -
- -

There are some overlaps between this list and, e.g., the separate section on canonical - identifiers.

- -

This linking mechanism may also be used to express other common link structures on the open Web. For - example:

- -
    -
  • Distribution feeds such as OPDS or Atom [[rfc4287]]
    • - -
  • Alternate versions of the publication
    • -
  • Web Mentions [[webmention]]
    • -
- -

Some of these link structures, such as dynamic search links, may require support for URI templates [[rfc6570]] to be meaningfully - useful in the context of a Web Publications. User agents should(?) support URI templates in order to make - it easier for publishers to integrate dynamic server-side features into their publications with minimal - coding and effort.

- -

-
-
+

Web Publication Construction

Resources

-

Web Publications MAY reference resources of any media type, both in the default reading order and as - dependencies of other resources.

+

Web Publications MAY reference resources of any media type, both in the default reading + order and as dependencies of other resources.

-

When adding resources to a Web Publication, consideration needs to be paid to support in user agents. - The use of progressive enhancement techniques and the provision of fallback content, as appropriate, - will ensure a more consistent reading experience for users regardless of their preferred user - agent.

+

When adding resources to a Web Publication, consider support in user agents. The use of progressive + enhancement techniques and the provision of fallback content, as appropriate, will ensure a more + consistent reading experience for users regardless of their preferred user agent.

Linking to a Manifest

-

Providing a link from a resource to its manifest allows a user agent to discover that a Web Publication is - available. Links MUST take one or both of the following forms:

+

Providing a link from a resource to the manifest of the Web Publication it belongs to allows + a user agent to discover that a Web Publication is available. Links MUST take one or both of the + following forms:

  • An HTTP Link header field [[!rfc5988]] with its rel parameter set to the value @@ -780,14 +791,15 @@

    Linking to a Manifest

-

A resource SHOULD link to one or more Web Publications to which it belongs.

+

A resource SHOULD link to the Web Publication(s) to which it belongs.

+ +

The following details might be moved to the lifecycle section in a future draft.

-

A resource may link to multiple parent manifests. User agents may choose to present one or - more alternatives to an end user, or choose a single alternative on its own. A user agent may choose to - present whichever manifest it wishes based upon information that it possesses, even one that is not - explicitly listed as a parent, e.g. based upon information it calculates or acquires out of band. In the - absence of a preference by user agent implementers, selection of the first manifest listed is suggested - as a default.

+

When a resource links to multiple manifests, a user agent MAY choose to present one or more alternatives + to the end user, or choose a single alternative on its own. The user agent MAY choose to present any + manifest based upon information that it possesses, even one that is not explicitly listed as a parent + (e.g., based upon information it calculates or acquires out of band). In the absence of a preference by + user agent implementers, selection of the first manifest listed is suggested as a default.

If there is a collection of information about a web publication as a whole ("manifest") that exists separately from most of the publication's resources, there needs to be a way to @@ -802,24 +814,28 @@

Linking to a Manifest

Landing Page

-

As described in , a Web Publication has an address that can be - dereferenced. That URL MUST resolve to an [[!HTML]] document that represents the primary entry point for - the Web Publication (referred to as the landing page).

+

As described in , a Web Publication has an address that can be + dereferenced. The address URL MUST resolve to the landing page, an [[!html]] document that + represents the primary entry point for the Web Publication.

Unlike other resources, the landing page MUST link to the manifest to ensure that user agents can discover the Web Publication.

To ensure that the Web Publication is consumable in different types of user agents, including those that - do not support Web Publications, the landing page SHOULD include an [[!HTML]] serialization of the table of contents (see for more information).

+ +

Additional questions about whether specifying HTML is necessary, whether + the resource has to be part of the web publication or not, and whether the table of contents is necessary + to specify at this location if provided in the content.

Web Publication Lifecycle

-

The publishing working group is currently evaluating the best approach for implementing web publications +

The publishing working group is currently evaluating the best approach for implementing Web Publications in user agents. This note is intended to provide an overview of where current thinking is and what issues are under consideration.

@@ -881,119 +897,64 @@

Web Publication Lifecycle

Reading Enhancements

-

This section contains placeholders for possible reading enhancements the UA may/should/must - provide. The list is subject to addition, modification and removal as the enhancements get discussed in more - detail.

- -
-

Navigation

- -

- -
-

Reading Order

- -

Hyperlinks are the means by which multiple resources are linked together on the Web. When users reach - the end of one resource, they have to activate a hyperlink to move to the next resource in the - sequence. While this model of navigation is effective, it is also disruptive for immersive reading - — it forces users to disengage from the content and perform the actions necessary to activate - the links. It is also limited to media types that support hyperlinks.

- -

The default reading order provides an enhancement to the hyperlink model, allowing the user - agent to automatically move the user to the next resource when a more natural action occurs, like a - general swipe across the screen. It is similar conceptually and functionally to the [[!html]] - link element's next and prev relationships.

- -

What is the interface for reading order navigation.

-
- -
-

Table of Contents

- -

The table of contents is one of the key aids to navigating a publication, as it enables users to - quickly move to the start of major sections. It is also a useful aid in understanding the overall - structure and purpose of a publication (e.g., what topics are covered, where the user currently is in - relation to the overall structure). Users often want quick access the table contents for these - reasons.

- -

User agents can use table of contents defined in the infoset to present an interface that allows users - to review and activate the links without leaving the resource they are currently viewing.

- -

Does the user agent need to provide access to the table of contents, or - do such mechanisms belong in the content.

-
-
- -
-

Offline Reading

- -

Detail on offline caching and reading will be included in a future version.

-
- - - -
+

Layout

-

Since web publications may consist of many HTML documents considered as a logical whole, this does - have implications for layout, as discussed below.

- - -

The layout and rendering of Web Publications is governed by the usual rules that apply to all web - content. [[!html]] documents are styled and laid out according to the rules of CSS, [[!svg]] files are rendered as normally expected of that - format, and so on. This specification requires no particular profile or subset of CSS, HTML, or SVG to be +

The layout and rendering of Web Publications is governed by the same rules that apply to all Web + content: [[!html]] documents are styled and laid out according to the rules of CSS, [[!svg]] files are rendered as expected of that format, + and so on. This specification requires no particular profile or subset of CSS, HTML, or SVG to be supported, other than the expectations set for these technologies by their respective specifications.

-

This specification intentionally refrains from introducing any new layout feature. Any shortcoming of - the web platform in terms of layout needs to be addressed for the whole web platform, which means via +

This specification intentionally refrains from introducing any new layout features. Any shortcoming of + the Web platform in terms of layout needs to be addressed for the whole Web platform, which means via CSS.

This working group will work with other relevant groups of the W3C to address platform-wide - limitations that negatively impacts Web Publications, and invites readers to do the same.

+ limitations that negatively impact Web Publications.

-

For the purposes of layout, each resource of a Web Publication is treated as a separate document. - User Agents must not mix content from multiple resources in the same rendering: For instance, For the purposes of layout, each resource of a Web Publication is treated as a separate document. User + agents MUST NOT mix content from multiple resources in the same rendering (e.g., CSS floats or Absolutely positioned - elements from one resource may not intrude or overlap with content from an other resource.

+ href="https://www.w3.org/TR/CSS21/visuren.html#absolutely-positioned">absolutely positioned + elements from one resource cannot intrude or overlap with content from an other resource).

Despite this general requirement that each resource should be treated as a separate document for the purpose of layout, there are some places where CSS specifications should be amended to be able to - deal more intelligently with collections of resources like Web Publications.

+ deal more intelligently with collections of resources like Web Publications.

One instance is the definition of cross references which are currently restricted to work only within a single document. This + >cross references, which are currently restricted to work only within a single document. This restriction should be relaxed to allow for cross references between separate resources of a single - Web Publication.

+ Web Publication.

Another related one would be to allow counters to accumulate across - multiple resources of a single Web Publication, for instance so that figures in multiple - sections may be numbered in a single sequence.

+ multiple resources of a single Web Publication (e.g., so that figures in multiple sections may + be numbered in a single sequence).

Scrolling or Paginating

-

Publications have historically been presented via paged media. Web pages almost always scroll. As the - preferences of individual readers vary, and as different types of publications may be better suited - for one or the other, this specification encourages User Agents to support both, and to offer a - choice to their users.

+ +

Publications have historically been presented via paged media, whereas Web pages almost always scroll. + As the preferences of individual readers vary, and as different types of publications are better + suited for one or the other, this specification encourages user agents to support both, and to offer + a choice to their users.

-

It may nonetheless be useful for authors to be able to specify a preference between scrolling and - pagination, even if a strict requirement is not possible. This should most likely be addressed - through an extension of It may be useful for authors to be able to specify a preference between scrolling and pagination, + even if a strict requirement is not possible. This should most likely be addressed through an + extension of @viewport or of the viewport meta tag(see [[css-device-adapt]]), or possibly through an extension of Scrolling or Paginating

Paginated Layout

-

When a User Agent renders a Web Publication in a paginated layout, it must lay out each +

When a User Agent renders a Web Publication in a paginated layout, it MUST lay out each document in the default reading order sequentially, with the last page of a resource being followed by the first page of the subsequent one.

-

To avoid having unstyleable blank pages in the middle of the document, if the preceding resource - ended on a left page (resp. right page), the subsequent one should start on a right page (resp. - left page) even if the page - progression (See [[!css-page-3]]) would otherwise lead to starting on the opposite page; - It should also be possible to use the break-before property (See [[!css-break-3]]) - to force the content to resume on the opposite side if that was desired by the author.

- -

[[css-page-3] needs to be amended to describe this exception to the general behavior when dealing +

To avoid blank pages, if a resource ends on a left page (resp. right page), the subsequent one + should start on a right page (resp. left page) even if the page progression (see + [[!css-page-3]]) would otherwise lead to it starting on the opposite page. It should also be + possible to use the break-before property (See [[!css-break-3]]) to force the + content to resume on the opposite side if that was desired by the author.

+ +

[[css-page-3]] needs to be amended to describe this exception to the general behavior when dealing with collections of documents instead of individual documents.

-

How is that supposed to work when subsequent resources have opposite page progression (See - [[!css-page-3]]) direction, for instance due to different a different writing mode? This is not - necessarily a problem from a layout point of view, as each page is independent, but from an UI - point of view, if swiping left means next page until the end of one chapter, and starts meaning - previous page in the next chapter because we've switched from English to Hebrew, this is going to - be horribly confusing.

+

How is pagination supposed to work when subsequent resources have opposite page progression directions (see + [[css-page-3]]). For example, due to different a different writing mode? This is not necessarily + a problem from a layout point of view, as each page is independent, but from an UI point of view. + If swiping left means next page until the end of one chapter, and starts meaning previous page in + the next chapter because the language is switched from English to Hebrew, this is going to be + confusing.

@@ -1040,132 +1001,100 @@

Paginated Layout

[[css-page-3]] needs to be amended so that page counters are not - automatically reset to at the beginning of each new resource belonging to the same Web - Publication.

+ automatically reset to at the beginning of each new resource belonging to the same Web + Publication.

-
-

Internal Locators

- -

In addition to a Web Publication's address(es), bookmarking, annotation, and other use cases require - internal locators which can be used to identify, locate, retrieve, and/or reference locations and content - fragments within a Web Publication (cf. Web Publications Use Cases and Requirements [[pwp-ucr]] and - Digital Publishing Annotation Use Cases [[dpub-annotation-uc]]).

- -
-

Publisher-Provided Locators

-

In choosing to organize a publication into multiple, individually addressable resources, each with its - own URL, the creator(s) of the publication provide locators for individual objects within the - publication. Thus Web Publication Resource URLs serve as Web Publication internal locators for - directly identifying, retrieving, and/or referencing each constituent resource of a Web Publication - in its entirety.

- -

Within an individual Web Publication Resource, the creator of the resource may further provide anchors - or other structures (e.g., the value of an id attribute of a <p> - element in an HTML constituent resource, the Document Object Model (DOM) of an XML constituent - resource) as a way to facilitate identifying, locating, retrieving, and/or referencing locations and - more granular content fragments within that individual constituent resource and thereby within the - Web Publication. Intra-resource, publisher-provided anchors and structures of this sort are often - used to mint fragment identifiers and Web Publication Locators, as described below.

-
+
+

Navigation

-
-

Fragment Identifiers

+

-

The generic syntax for fragment identifiers is defined in RFC 3986 [[!rfc3986]]. The fragment - identifier component of a URL comes at the end of the URL and is preceded by a # - character. The fragment identifier component of a URL is separated prior to dereferencing and is not - sent to the server. The identifying information within the fragment identifier component itself is - dereferenced solely by the user agent. Interpretation and resolution of a fragment identifier may be - dependent on the media-type of the resource retrieved when the preceding part of the URL is - dereferenced.

+
+

Reading Order

-

A broad range of fragment identifier formats, each specific to resources of one or more media-types, - have been defined in various IETF RFCs, W3C Recommendations, etc. These are typically included by - reference in IANA-registered media-type specifications [[iana-media-types]]. A fragment identifier of - a format appropriate for a Web Publication Resource's media type may be used to identify, retrieve, - and/or reference content fragments within that resource.

+

Hyperlinks are the means by which multiple resources are linked together on the Web. When users reach + the end of one resource, they have to activate a hyperlink to move to the next resource in the + sequence. While this model of navigation is effective, it is also disruptive for immersive reading + — it forces users to disengage from the content and perform the actions necessary to activate + the links. It is also limited to media types that support hyperlinks.

-
-

Could reference or duplicate here with modifications the second table from 4.2.1 of Web Anno Data - Model Rec. [[!annotation-model]].

-
+

The default reading order provides an enhancement to the hyperlink model, allowing the user + agent to automatically move the user to the next resource when a more natural action occurs, like a + general swipe across the screen. It is similar conceptually and functionally to the [[!html]] + link element's next and prev relationships.

-

User agents minting fragment identifiers often take advantage of publisher-provided anchors and - structures. For example, the value of the id attribute of a <p> - element in an HTML Web Publication Resource can be used to mint a fragment identifier linking to that - <p> element (i.e., a paragraph). This type of fragment identifier is - illustrated in the following example, which assumes the existence within the HTML resource of an - element with id p33, e.g., <p id="p33">.

- - - -

Using other fragment identifier formats, user agents may mint fragment identifiers to serve as Web - Publication internal locators even in the absence of any explicit publisher-provided anchor or - structure. For example, a media fragment identifier [[!media-frags]] for a still image embedded in a - Web Publication may be minted without reference to any publisher-provided anchor or structure, as - shown in the following example. In this example, the fragment is a rectangular image segment that is - 200x150 pixels with its upper left corner at 100 pixels in from the left edge and 500 pixels down - from the top edge of the full image.

- - +

What is the interface for reading order navigation.

-
-

Web Publication Locators

+
+

Table of Contents

-

For some use cases it is essential to identify and reference a Web Publication Resource or a location - in or a segment of a Web Publication Resource in the scope or context of a Web Publication which - includes this resource. The fragment identifier approaches described above do not satisfy this - requirement since only the URL of the constituent Web Publication Resource containing the location or - content fragment of interest is expressed. Web Publication Locators address this issue by providing - the means to express both the URL of the Web Publication Resource and the URL of the Web - Publication.

+

The table of contents is one of the key aids to navigating a publication, as it enables users to + quickly move to the start of major sections. It is also a useful aid in understanding the overall + structure and purpose of a publication (e.g., what topics are covered, where the user currently is in + relation to the overall structure). Users often want quick access the table contents for these + reasons.

-
-

TO DO: Need to update title and insert a reference here to this now separate document. Is an - informative reference also needed here to EBPU CFI document?

-
+

User agents can use table of contents defined in the infoset to present an interface that allows users + to review and activate the links without leaving the resource they are currently viewing.

-
-

TO DO: illustrate with example of simple, easy to understand Web Publication Locator such as might - be used in annotating a simple Web Publication. More complicated examples can be left to the - external "Locators for Web Publications" document.

-
+

Does the user agent need to provide access to the table of contents, or + do such mechanisms belong in the content.

+
+
-

The semantics of Web Publication Locators are a mapping and extension of the Web Annotation Data Model - [[!annotation-model]] and Vocabulary [[!annotation-vocab]] for describing and referencing a segment - of a web resource. As a result, Web Publication Locators provide the expressiveness needed for a - broad range of annotation and bookmarking use cases. Additionally, Web Publication Locators provide a - way to identify and reference a location within a Web Publication (i.e., as distinct from identifying - and referencing a content fragment consisting of a span of characters or bytes). A Web Publication - Locator can be used to identify, retrieve and/or reference a fragment of a Web Publication that spans - multiple Web Publication Resources.

+
+

Offline Reading

-
-

The separate document will need to illustrate these use cases - i.e., identifying a location as - distinct from a fragment and identifying a fragment that spans multiple Web Publication - Resources. If not, illustrations are needed here.

-
-
+

Detail on offline caching and reading will be included in a future draft.

+
-
-

In composing a Web Publication Locator, the canonical identifier of the Web Publication should be used - in preference to any alternative addresses. This facilitates the collation of Web Publication - Locators associated with a particular Web Publication. URLs of Web Publication Resources appearing in - a Web Publication Locator should match the URL for of the Web Publication Resource provided in the - Web Publication Infoset.

-
+
+
+

Web Publication Locators

+ +

Locators are used to identify, locate, retrieve, and/or reference locations and content fragments within + Web Publications (e.g., for address(es), bookmarks, and annotations). Locators traditionally take + the form of fragment identifiers [[rfc3986]], where the portion of a URL preceded by a number sign character + (#) identifies a specific position within the referenced resource.

+ +

For some use cases, it is essential to identify and reference a Web Publication resource—or a location + in or a segment of a resource—in the scope or context of the Web Publication to which it belongs. A + traditional fragment identifier cannot satisfy this requirement, since only the URL of the constituent + resource containing the location or content fragment of interest is expressed. Web Publication Locators + [[pub-loc]] address this issue by providing the means to express both the URL of the resource and the URL of + the Web Publication.

+ +
+

Illustrate with example of simple, easy to understand Web Publication Locator such as might be used in + annotating a simple Web Publication.

+
+ +

The semantics of Web Publication Locators are a mapping and extension of the Web Annotation Data Model + [[annotation-model]] and Vocabulary [[annotation-vocab]] for describing and referencing a segment of a Web + resource. As a result, Web Publication Locators provide the expressiveness needed for a broad range of + annotation and bookmarking use cases. Additionally, Web Publication Locators provide a way to identify and + reference a location within a Web Publication (i.e., as distinct from identifying and referencing a content + fragment consisting of a span of characters or bytes). A Web Publication Locator can be used to identify, + retrieve and/or reference a fragment of a Web Publication that spans multiple resources.

+ +
+

In composing a Web Publication Locator, use the canonical identifier of the Web Publication in preference + to any alternative addresses. Such use facilitates the collation of Web Publication Locators associated + with a particular Web Publication. URLs of Web Publication resources appearing in a Web Publication + Locator should match the URL of the resource provided in the infoset.

+
+

Security