Web Publications

Abstract

This specification defines a collection of information that describes the structure of Web Publications so that user agents can provide user experiences tailored 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.

1. Introduction

1.1 Why Web Publications

This section is non-normative.

The Web is a lonely place. It is unbounded: resources live out their lives on remote servers scattered across the globe, only reachable by addresses sometimes known to only a few people. But life on the Web 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.

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 need.

The traditional publishing model, sometimes called the print model, differs from the Web model in that the publisher packages all the information together and thereby establishes the common pathway through it. The user can passively follow the content page-by-page, or actively find other pathways via a table of contents or index. It is a model that has worked to bind information in a cohesive way for millennia, and continues to be an important model alongside the Web. The publication as a bounded edition, made public, is used to carry intellectual and artistic works of innumerable form: novels, plays, poetry, journals, magazines, newspapers, articles, laws, treatises, pamphlets, atlases, comics, manga, notebooks, memos, manuals, and albums of all sorts.

Attempts to reproduce this model on the Web have had to work around its loose coupling of information: sometimes publications are compressed into a single page; sometimes they are broken across multiple pages and hyperlinked together. These models both have flaws, however: single-page publications are often so large they render slowly, especially on low-power devices; multi-page publications cannot be easily taken offline because their common thread cannot be established.

As a result, users have had trouble accessing, compiling and downloading Web content for curation and personal use. That, in turn, has fed the continuing development of non-Web digital formats to redress these problems, and made it necessary to create both Web-ready content and alternative renditions for offline use.

This specification aims to reduce these barriers and reinvigorate publishing by combining the best aspects of both models—the persistent availability and portability of bounded publications with the pervasive accessibility, addressability, and interconnectedness of the Open Web Platform. To do so, it adds an unobtrusive definition of interrelation to the Web model: the Web Publication.

1.2 What is a Web Publication

This section is non-normative.

A Web Publication is a discoverable and identifiable collection of resources. Information about the Web Publication 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 describe 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 a 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 [html]), or the manifest can be loaded directly by a compatible user agent.

With the establishment of Web Publications, user agents can build new experiences tailored specifically for their unique reading needs.

Flowchart depicts the resources of a Web Publication, their attachment to a manifest, and its relationship to the infoset. — Figure 1 Simplified Diagram of the Structure of Web Publications.
A description of the structure diagram is available in the Appendix. Image available in SVG and PNG formats.

1.3 Scope

This section is non-normative.

This specification only defines requirements for the production and rendering of valid Web Publications. As much as possible, it leverages existing Open Web Platform technologies to achieve its goal—that being to allow for a measure of boundedness on the Web without changing the way that the Web itself operates.

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 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.

The specification is also intended to facilitate different user agent architectures for the consumption of Web Publications. While a primary goal is that traditional Web user agents (browsers) will be able to consume Web Publications, this should not limit the capabilities of any other possible type of user agent (e.g., applications, whether standalone or running within a user agent, or even Web Publications that include their own user interface). As a result, the specification does not attempt to architect required solutions for situations whose expected outcome will vary depending on the nature of the user agent and the expectations of the user (e.g., how to prompt to initiate a Web Publication, or at what point or how much of a Web Publication to cache for offline use).

1.4 Relationship to Other Specifications

1.4.1 Web App Manifest

Editor's note

The working group is investigating integration with the work done on the Web App Manifest [appmanifest] specification to avoid duplication of concerns both in the expression and serialization of a manifest and in the processing and compilation of the infoset. It is expected, however, that there will be differences in the processing models of each (e.g., the initiation of the reading experience for 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 themselves.

The initial stage of evaluating this assumption involves:

the continuing analysis of necessary metadata and publication structure requirements;
the comparison and harmonization of web publication requirements with those already defined in Web App Manifest.

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 web app manifest. Wherever semantically possible, the terms used and defined for web app manifests 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 Web App Manifest specification 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.

This section will be updated as appropriate to reflect the current status of this work, and describe the evolving relationship.

See also issue #32 in the GitHub tracker for more discussion about integration.

1.5 Terminology

This document uses terminology defined by the W3C Note "Publishing and Linking on the Web" [publishing-linking], including, in particular, user, user agent, browser, and address.

Identifier: An identifier is metadata that can be used to refer to Web Content in a persistent and unambiguous manner. URLs, URNs, DOIs, ISBNs, and PURLs are all examples of persistent identifiers frequently used in publishing.
Manifest: A manifest represents structured information about a Web Publication, such as informative metadata, a list of all resources, and a default reading order.
Non-empty: For the purposes of this specification, non-empty is used to refer to an element, attribute or property whose text content or value consists of one or more characters after whitespace normalization, where whitespace normalization rules are defined per the host format.
URL: 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 specification for further details.
Web Publication: A Web Publication is a collection of one or more resources, organized together through a manifest into a single logical work with a default reading order. The Web Publication is uniquely identifiable and presentable using Open Web Platform technologies.

3. Information Set

Editor's note

As the serialization of the manifest remains an open issue, specifics about how properties are compiled into the infoset remain under-specified. 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.

Issue 63: Replace the "infoset" term?

The name "infoset" might 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 of the collected information.

3.1 Explanation

This section is non-normative.

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 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.

The infoset is primarily compiled from a Web Publication's manifest, whose serialization requirements are defined in 4.4 Serialization. Some information can be obtained outside the manifest—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, for example.

3.2 Requirements

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

Descriptive Properties

REQUIRED: address

RECOMMENDED:

accessibility
base direction
canonical identifier
cover
creator
language
modification date
privacy policy
publication date
title

Structural Properties

REQUIRED: default reading order, resource list, and reading progression.

RECOMMENDED: table of contents

Editor's note

These requirements reflect the current minimum consensus, though a number of issues remain open that could change whether an item is required or recommended. Refer to the property descriptions for more information.

3.3 Descriptive Properties

3.3.2 Address

A Web Publication's address is a URL [url] that represents the primary entry point for the Web Publication. If this URL does not resolve to an HTML document [html], user agents SHOULD NOT provide access to it to users.

The referenced document SHOULD be a resource of the Web Publication. It can be any resource, including one that is not listed in the default reading order. This document MUST include a link to the manifest to ensure a bidirectional linking relationship (i.e., that user agents can also locate the manifest from the document at the address.

If the document is not a Web Publication resource, user agents SHOULD load the first document in the default reading order when initiating the Web Publication.

Note

To improve the usability of Web Publications, particularly in user agents that do not support Web Publications, include navigation aids in the referenced document that facilitate consumption of the content, (e.g., provide a table of contents or a link to one).

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

Note

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

3.3.3 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 MUST be an address or a value that allows a one-to-one mapping to an address (e.g., a DOI [doi] can be resolved to a URL [url] via a DOI resolver). If a user agent cannot resolve the canonical identifier to an address, it SHOULD ignore the property.

If a Web Publication is hosted at more than one address, the canonical 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.

Note

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

Issue 58: is a canonical identifier necessary

Is a canonical identifier necessary to call out explicitly in the infoset, or can it be handled by other metadata.

3.3.4 Cover

The infoset SHOULD include a reference to a cover image. This image can be used by user agents to present the Web Publication to users (e.g., in a library or bookshelf, or when initially loading the Web Publication).

User agents SHOULD NOT use the cover image as the sole means of selecting or accessing Web Publications. A user agent SHOULD use the Web Publication's title and creators as text alternatives for such interfaces.

More than one cover image MAY be referenced from the infoset to provide alternative sizes and resolutions for different device screens.

A user agent MAY create a cover for a Web Publication if one is not present. This specification does not define requirements for the creation of such cover images (e.g., the user agent could use a placeholder image, generate an image dynamically, or incorporate properties of the infoset into a graphic, such as the title or creators).

3.3.5 Creators

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

The creator property SHOULD include the role the creator played in the creation of the Web Publication (e.g., 'author', 'illustrator', 'translator').

3.3.6 Language and Base Direction

Each textual property in the Web Publication's infoset (e.g., title, creators) is Localizable [string-meta]. This means it is possible to assign:

the natural language, which MUST be a tag that conforms to [bcp47];
the base direction, which identifies the display direction for the property using one of the following possible values:
- ltr: left-to-right;
- rtl: right-to-left;
- auto: direction is determined from the value of the property.

The Web Publication's infoset MAY contain global language and the base direction declarations using the same conventions (i.e., [bcp47] tags for language, and the values ltr/rtl/auto for base direction). These are used as defaults for textual properties in the infoset, unless overwritten by the properties themselves.

Note

These features make it possible to add the title of a publication in different languages, or repeat the creators’ names using different scripts.

User agents MUST NOT use the language and base direction outside the context of the manifest (e.g., in the processing or rendering of the Web Publication content). These values are not a replacement for such declarations in each resource as defined by its format.

If a user agent requires the language and one is not available in the infoset (globally or specifically for the property), or the obtained value is invalid, the user agent MAY attempt to determine the language. This specification does not mandate how such a language tag is created. The user agent might:

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.

If a language tag cannot be determined, user agents MUST use the value "und" (undetermined). If the base direction cannot be determined, user agents MUST assume the value auto.

Issue 53: Language of web publication v. language of manifest/resources

Is the language declared for the manifest content the same as the language of the publication? If it is, how to deal with multilingual publications?

3.3.7 Last Modification Date

The last modification date is the date when the Web Publication was last updated (i.e., whenever changes were last made to any of the resources of the Web Publication, including the manifest).

This date does not necessarily reflect all changes to the Web Publication (e.g., third-party content could change without the author being aware). User agents SHOULD check the last modification date of individual resources to determine if they have changed and need updating.

3.3.8 Publication Date

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 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.

3.3.9 Privacy Policy

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 in the content.

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

It is RECOMMENDED that the privacy policy be provided in a human-readable format, such as HTML [html].

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

3.3.10 Reading Progression Direction

The reading progression establishes the reading direction from one resource to the next within a Web Publication. The value of this property may be:

ltr: left-to-right;
rtl: right-to-left;
auto: the user agent chooses the direction.

The default value is auto.

This information item has no effect on the rendering of the individual primary resources; it is only relevant for the progression direction from one resource to the other.

Note

The reading progression of a Web Publication is used to adapt such publication level interactions as menu position, swap direction, defining tap zones to lead the user to the next and previous pages, touch gestures, etc.

3.3.11 Title

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

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

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

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.

Note

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

3.4 Structural Properties

3.4.1 Default Reading Order

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

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.

The default reading order MUST include at least one resource.

The default reading order is either specified directly in the manifest or in a nav element [html]. In the latter case, the manifest MUST provide a link to the Web Publication resource that contains the nav element, with a fragment identifier that specifically identifies it.

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

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

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:

use only the resource the user accessed to reach the manifest;
search the resource list for a nav element to use;
calculate the default reading order using its own algorithm.

3.4.2 Resource List

The resource list enumerates all resources that are used in the processing and rendering of a Web Publication (i.e., that are within its bounds). This list is the definitive source that user agents have in determining which referenced resources belong to the Web Publication and which are external to it.

The completeness of the resource list will affect the usability of the Web Publication in certain reading scenarios (e.g., the ability to read the Web Publication offline). For this reason, it is strongly RECOMMENDED to provide a comprehensive list of all of the Web Publication's constituent resources. At a minimum, the resource list MUST include a list of all resources in the default reading order.

In some cases, a comprehensive list of these resources might not be easily achieved (e.g., third-party scripts that reference resources from deep within their source), but a user agent SHOULD still be able to render a Web Publication even if some of these resources are not identified as belonging to the Web Publication (e.g., when it is taken offline without them).

If a user agent encounters a resource that it cannot locate in the resource list, it MUST treat the resource as external to the Web Publication (e.g., it might alert the user before loading, open the resource in a new window, or unload the current Web Publication and resume normal Web browsing).

Issue 59: avoiding resource declaration duplication

Must the manifest list resources in the default reading order or can these can be inferred?

3.4.3 Table of Contents

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 include a link to at least one resource.

The table of contents is either specified directly in the manifest or in a nav element [html]. In the latter case, the manifest MUST provide a link to the Web Publication resource that contains the nav element, with a fragment identifier that specifically identifies it.

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:

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);
use the titles of the resources in the default reading order;
calculate a table of contents using its own algorithms.

Issue

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

Issue

The issue of using the HTML nav element as a possible encoding of the table of contents was mentioned or explicitly addressed in the following (now closed) issues:

Issue #35: Define the resources in the default reading order of a Web Publication to be the resources referenced from the table of contents.
Issue #39: There is a consensus that a Web Publication must have a default reading order and must/should have a table of contents (the main navigation entry point).

3.5 Extensibility

The infoset is designed to provide a basic set of properties for use by user agents in presenting and rendering a Web Publication, but MAY be extended in the following ways:

through the inclusion of additional properties in the manifest;
by the provision of linked metadata records.

User Agents MAY support additional properties but MUST NOT include unrecognized properties in the infoset. The use of linked records is RECOMMENDED whenever possible, as the use of native formats standardizes and simplifies processing by user agents.

6. Web Publication Lifecycle

Editor's note

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 at and what issues are under consideration.

The development of Web Publications is not viewed as a separate forking of the Web, but an enhancement layer that can be supported by user agents. To that end, the primary constraints on any solution for Web Publications are that:

the rendering of Web Publications must not interfere with the underlying Web model and APIs — all functionality and enhancements must be layered on top;
a Web Publication should not have to carry its own implementation code — functionality is ideally provided by the user agent and/or polyfill.

While this specification will provide implementation flexibility for user agents, there are still a number of areas that have been identified as potentially needing to be detailed. These include:

initialization expectations for a Web Publication:
- automatic initiation v. user prompts;
- linked v. directly loaded manifests;
- resources that belong to more than one Web Publication.
the creation of a "publication state":
- persistence of publication information across page loads;
- location and persistence of UI;
- indications of supported features;
- DOM issues such as persistence of numbering schemes.
tracking the extent of a Web Publication:
- taking an entire publication offline;
- enabling search across documents.
establishing the bounds of a Web Publication:
- when to end the publication state;
- document history traversal;
- how to handle links outside the publication.
updating of the manifest.

The working group intends to flesh out the lifecycle in later revisions once it is clearer what models are viable and what solutions can be standardized. Input on the feasibility and challenges of these approaches is welcome at any time.

6.1 Obtaining a manifest

Editor's note

Discovery of a manifest is currently dependent on the presence of an HTTP Link header or an HTML link element with the rel attribute value publication. This approach might change in the future depending on whether Web Publications align with Web App Manifest [appmanifest] or another manifest format.

The steps for obtaining a manifest are given by the following algorithm. The algorithm, if successful, returns a processed manifest and the manifest URL; otherwise, it terminates prematurely and returns nothing. In the case of nothing being returned, the user agent MUST ignore the manifest declaration.

From the Document of the top-level browsing context, let origin be the Document's origin, and manifest link be the first link element in tree order whose rel attribute contains the token publication.
If origin is an [html] opaque origin, terminate this algorithm.
If manifest link is null, terminate this algorithm.
If manifest link's href attribute's value is the empty string, then abort these steps.
Let manifest URL be the result of parsing the value of the href attribute, relative to the element's base URL. If parsing fails, then abort these steps.
Let request be a new [fetch] request, whose URL is manifest URL, and whose context is "publication".
If the manifest link's crossOrigin attribute's value is 'use-credentials', then set request's credentials to 'include'.
Await the result of performing a fetch with request, letting response be the result.
If response is a network error, terminate this algorithm.
Let text be the result of UTF-8 decoding response's body.
Let manifest be the result of running processing a manifest given text, manifest URL, and the URL that represents the address of the top-level browsing context.
Return manifest and manifest URL.

Note

See the diagram in the appendix for a visual representation of the algorithm.

Editor's note

The publication value for context doesn't exist yet. The working group will need to define and register this context value.

6.2 Processing the manifest

Editor's note

The manifest could be processed differently depending on future alignment with Web App Manifest [appmanifest] or another format (e.g., as an extension point for another algorithm.

The steps for processing a manifest are given by the following algorithm. The algorithm takes a text string as an argument, which represents a manifest, and a manifest URL [url], which represents the location of the manifest, and a document URL [url]. The output from inputting a JSON document into this algorithm is a processed manifest.

Let json be the result of parsing text. If parsing throws an error:
1. Issue a developer warning with any details pertaining to the JSON parsing error.
2. Set json to be the result of parsing the string "{}".
If Type(json) is not Object:
1. Issue a developer warning that the manifest needs to be an object.
2. Set json to be the result of parsing the string "{}".
Extension point: process any proprietary and/or other supported members at this point in the algorithm.
Let manifest be the result of converting [WEBIDL] json to a WebPublicationManifest dictionary.
Set manifest["reading_order"] to the result of processing the default reading order given manifest["reading_order"], manifest["resources"], manifest URL, and document URL.
Return manifest.

Note

See the diagram in the appendix for a visual representation of the algorithm.

6.3 Processing the default reading order

The steps for processing the default reading order are given by the following algorithm.

If manifest["reading_order"] is not empty, return it and terminate this algorithm.
If manifest["resources"] is not empty, let navigation document link be the first PublicationLink whose rel member contains the token contents.
If navigation document link is not null and its href member is not empty, let navigation document URL be the result of parsing the value of the href attribute, relative to the manifest URL.
If navigation document URL is empty, set navigation document URL to document URL.
Let request be a new [fetch] request, whose URL is navigation document URL, and whose context is "publication".
Await the result of performing a fetch with request, letting response be the result.
If response is a network error, terminate this algorithm.
Let document be the result of UTF-8 decoding response's body.
If document is not an HTML document [html], terminate this algorithm.
Let default reading order be the result of processing document:
1. If document contains a nav element:
  1. Extract a list of resource paths referenced from the href attribute of all a elements.
  2. Strip any fragment identifiers from the references.
  3. Resolve all relative paths to full URLs.
  4. Remove all consecutive references to the same resource, leaving only the first.
2. Otherwise terminate this algorithm.
Return default reading order.

Note

See the diagram in the appendix for visual representation of the core of the algorithm and the separate diagram on handling the nav element.

7. Affordances

Editor's note

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

Issue 143: What should be in the spec for affordances?

7.1 Switch to publication mode

When a user agent obtains a manifest it SHOULD display an affordance for switching the display to publication mode.

This affordance has the following requirements:

it MUST inform the user that the current resource is part of a Web Publication
it SHOULD display the title of the Web Publication
it MAY display additional metadata from the infoset

Publication mode is a display mode implemented by the user agent that follows the conventions listed in presentation and navigation.

7.2 Add to the list of publications

User agents SHOULD provide a list of publications where the user can browse, search, add and remove their publications.

When a user agent obtains a manifest for a Web Publication that is not currently included in the list of publications, it MAY provide an affordance to add it to the list.

This affordance has the following requirements:

it SHOULD display the title of the Web Publication
it MAY display additional metadata from the infoset

7.3 Presentation

7.3.1 Layout

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 documents are rendered as defined by that format, etc. 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.

Editor's note

This specification intentionally avoids 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 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 (e.g., CSS floats or absolutely positioned elements from one resource cannot intrude or overlap with content from an other resource).

Note

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.

One instance is the definition of 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.

Another related would be to allow counters to accumulate across multiple resources of a single Web Publication (e.g., so that figures in multiple sections may be numbered in a single sequence).

7.3.2 User Settings

When a user agent renders a Web Publication, it SHOULD provide user settings to customize the experience.

User settings MAY include:

text size;
font family;
display mode (night, high contrast, etc.);
playback speed (for audio and video resources).

This specification does not cover how user agents override author styles to offer user settings.

Editor's note

To provide user settings in their reader mode, browsers usually get rid of most of the author styles. There is always a tension in reading environments between author styles and the user's preference, which is very hard to balance.

Issue 138: WP affords personalization

Issue 136: WP affords treatment of the publication as a logical whole

7.3.3 Scrolling or Paginating

This section is non-normative.

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.

Editor's note

It might 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 @page (see [css-page-3]). This should be discussed with the relevant working groups (CSSWG, WebPlatformWG, WHATWG).

Issue 137: WP affords "paging" through a publication

7.3.4 Paginated Layout

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.

Editor's note

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.

Editor's note

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.

Editor's note

[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.

Issue 137: WP affords "paging" through a publication

Issue 86: Accessibility requirements for navigation

7.4.1 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 swipe across the screen. It is similar conceptually and functionally to the link element's next and prev relationships [html].

User agents MUST provide an affordance for moving forward and backward in the default reading order of a Web Publication.

Issue 144: WP affords moving forward and backward

Issue 38: What does "Reading Order" mean in the context of a Web Publication?

Issue 136: WP affords treatment of the publication as a logical whole

7.4.2 Progression

While reading a Web Publication, the user follows a natural progression within a resource as well as between resources (following the default reading order).

User agents SHOULD provide an affordance that saves this progression in the publication and returns the user to their last location the next time they open the publication.

When the user agent obtains a manifest for the first time, it MAY also prompt the user whether they would like to:

continue reading the publication from their current location; or
start reading the publication from the first resource in the default reading order.

Issue 145: WP affords saving and retrieve progression

Issue 136: WP affords treatment of the publication as a logical whole

7.4.3 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 SHOULD provide an affordance for accessing the table of contents without requiring the user to leave the resource they are currently viewing.

Issue 145: WP affords saving and retrieve progression

7.5 Offline Access

Issue 141: WP affords offline reading capabilities.

7.6 Search

Editor's note

Detail on inter-publication search across multiple resources will be included in a future draft.

Issue 136: WP affords treatment of the publication as a logical whole

A. WebIDL

A.1 `WebPublicationManifest` dictionary

dictionary WebPublicationManifest {
    required USVString                   address;
             DOMString                   lang;
             TextDirection               dir = "auto";
             sequence<LocalizableString> title;
             USVString                   identifier;
             sequence<Contributor>       author;
             DOMString                   modified;
             DOMString                   publication_date;
             sequence<PublicationLink>   links;
             sequence<PublicationLink>   reading_order;
             sequence<PublicationLink>   resources;
};

The WebPublicationManifest has the following members:

address: Contains the address. Required.
lang: Contains the default value language.
dir: Contains the default value for base direction.
title: Contains the title.
identifier: Contains the canonical identifier.
author: Contains one or more creators.
modified: Contains the last modification date.
publication_date: Contains the publication date.
links: Contains links to external resources.
reading_order: Contains the default reading order.
resources: Contains the resource list.

A.2 `dir` member

enum TextDirection {
    "ltr",
    "rtl",
    "auto"
};

The dir member's value are defined by TextDirection as:

ltr: Left-to-right text.
rtl: Right-to-left text.
auto: Determined by the Unicode Bidirectional Algorithm [uax9] algorithm.

A.3 `author` member

Editor's note

The current infoset for creators is not fully defined; this dictionary might be further improved once there is agreement on how they should be handled.

dictionary Contributor {
    required LocalizableString name;
             USVString         identifier;
};

The author member is a sequence of Contributor dictionaries where each dictionary has the following members:

name: Contains one or more localizable string for the contributor's name.
identifier: Contains a canonical identifier for the contributor.

A.4 `LocalizableString` dictionary

Editor's note

This definition includes a slightly tweaked version of the i18n recommendation that also includes a string value in addition to a language and a direction.

Some metadata in te infoset have strong requirements for internationalization. For those members, this specification relies on the best practices established by the i18n WG and on the LocalizableString dictionary.

dictionary LocalizableString {
    required USVString     value;
             DOMString     lang;
             TextDirection dir = "auto";
};

When lang or dir are specified in LocalizableString, these values override the default language and base direction specificed in WebPublicationManifest.

LocalizableString has the following members:

value: Contains the localized string.
lang: Contains the language.
dir: Contains the base direction.

A.5 `PublicationLink` dictionary

dictionary PublicationLink {
    required USVString           href;
             DOMString           type;
             USVString           title;
             sequence<DOMString> rel;
             DOMString           height;
             DOMString           width;
             boolean             templated;
};

Editor's note

This definition is based on a simplifed model of RWPM, where the link does not contain properties. In the context of EPUB 4, the working group might also need to re-introduce these properties.

The PublicationLink dictionary contains the following members:

href: Contains the URL of the linked resource. [url]
type: Contains the MIME media type of the linked resource. [rfc2046]
title: Text label for the linked resource.
rel: Contains one or more relations based on the IANA link registry. [iana-link-relations]
height: Height of the linked resource, expressed in CSS pixels. [css]
width: Width of the linked resource, expressed in CSS pixels. [css]
templated: Indicates that the href is a URI template. [rfc6570]

Web Publications

W3C Working Draft 15 March 2018

Abstract

Status of This Document

1. Introduction

1.1 Why Web Publications

1.2 What is a Web Publication

1.3 Scope

1.4 Relationship to Other Specifications

1.4.1 Web App Manifest

1.5 Terminology

2. Conformance

2.1 Conformance Classes

3. Information Set

3.1 Explanation

3.2 Requirements

3.3 Descriptive Properties

3.3.1 Accessibility

3.3.2 Address

3.3.3 Canonical Identifier

3.3.4 Cover

3.3.5 Creators

3.3.6 Language and Base Direction

3.3.7 Last Modification Date

3.3.8 Publication Date

3.3.9 Privacy Policy

3.3.10 Reading Progression Direction

3.3.11 Title

3.4 Structural Properties

3.4.1 Default Reading Order

3.4.2 Resource List

3.4.3 Table of Contents

3.5 Extensibility

4. Manifest

4.1 Overview

4.2 Requirements

4.3 Declaration

4.4 Serialization

5. Web Publication Construction

5.1 Resources

5.2 Linking to a Manifest

6. Web Publication Lifecycle

6.1 Obtaining a manifest

6.2 Processing the manifest

6.3 Processing the default reading order

7. Affordances

7.1 Switch to publication mode

7.2 Add to the list of publications

7.3 Presentation

7.3.1 Layout

7.3.2 User Settings

7.3.3 Scrolling or Paginating

7.3.4 Paginated Layout

7.4 Navigation

7.4.1 Reading Order

7.4.2 Progression

7.4.3 Table of Contents

7.5 Offline Access

7.6 Search

8. Web Publication Locators

9. Security

10. Privacy

A. WebIDL

A.1 WebPublicationManifest dictionary

A.2 dir member

A.3 author member

A.4 LocalizableString dictionary

A.5 PublicationLink dictionary

B. Lifecycle diagrams

C. Image Descriptions

D. Acknowledgements

E. References

E.1 Normative references

E.2 Informative references

A.1 `WebPublicationManifest` dictionary

A.2 `dir` member

A.3 `author` member

A.4 `LocalizableString` dictionary

A.5 `PublicationLink` dictionary