Draft Specification 14 November 2014
This version:
http://www.idpf.org/epub/previews/epub-previews-20141114.html
Latest version:
http://www.idpf.org/epub/previews/
Previous version:
http://www.idpf.org/epub/previews/epub-previews-20140827.html
Copyright © 2012-2014 International Digital Publishing Forum™
All rights reserved. This work is protected under Title 17 of the United States Code. Reproduction and dissemination of this work with changes is prohibited except with the written permission of the International Digital Publishing Forum (IDPF).
EPUB is a registered trademark of the International Digital Publishing Forum.
Editors
Hadrien Gardeur (Feedbooks), Matt Garrish (Invited Expert), Yasuki Ikeuchi (ACCESS)
Authors
Hadrien Gardeur (Feedbooks), Matt Garrish (Invited Expert)
Status of this Document
This specification is a work in progress and subject to change.
All comments on this specification should be submitted via the EPUB 3 Working Group Issue Tracker, hosted on Google Code. NOTE: you must login via a Google Account in order to submit an issue. Please submit spec comments with the labels "Type-ReviewComment" and "Spec-AHL". Members of the EPUB Working Group may submit questions via the mailing list.
Table of contents
2.3 Reading System Conformance
3.3 Reading System Conformance
3.5 Fragment identifiers in Preview Collections
3.6 Generating a Preview Publication from an Embedded Preview
Appendix A. Acknowledgements and Contributors
This section is informative
This specification, EPUB Previews, describes how preview content can be included in EPUB® Publications. This document outlines two key models for defining such content:
Best practices for metadata and links related to previews (e.g., to acquire the full Publication) are also covered.
Refer to the EPUB Specifications for definitions of EPUB-specific terminology used in this document.
Embedded Preview
A preview derived from a subset of resources of its containing EPUB Publication.
Preview Publication
An EPUB Publication whose content represents a preview of another Publication.
The keywords must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be interpreted as described in [RFC2119].
All sections of this specification are normative except where identified by the informative status label "This section is informative". The application of informative status to sections and appendices applies to all child content and subsections they may contain.
All examples in this specification are informative.
This section is informative
There are many reasons why a preview might be distributed as a separate EPUB file: to begin marketing a book before the full manuscript is complete, to limit the content available when not using DRM schemes, to minimize download sizes for media-rich works, and so on.
When distributing such a preview, it is necessary both to identify to the User that they do not have the complete publication, and also provide the means for them to obtain that work.
This section details how to create standalone Preview Publications, including the required labelling in the Package Document metadata, how to create an identifier for the preview, and how to link the preview to its parent work (how to acquire the parent work is outlined in 4. Acquiring Publications).
In addition to being a valid EPUB Publication, a Preview Publication must meet all of the following criteria:
› It must be identified as a preview, as defined in 2.4 Preview Identification.
In addition to processing the Preview Publication according to the version of the EPUB specification it conforms to, an EPUB Reading System must meet all of the following additional criteria:
› It should provide a means to access the Publication the preview is derived from, as defined in 4. Acquiring Publications.
In order to indicate that a Publication represents a preview, its Package Document metadata section [Publications301] must include a dc:type element with the value "preview".
The following example shows how a Preview Publication is defined in the Package Document metadata.
<package …>
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
<dc:type>preview</dc:type>
…
</metadata>
</package>
A Preview Publication MUST NOT use the same package identifier as its source Publication.
Since a Preview Publication is rarely a product, this specification recommends using something else than an ISBN as the package identifier.
A Preview Publication SHOULD link back to its source Publication using a dc:source element, with the source Publication's package identifier as the value.
The following example shows how a Preview Publication links back to its source publication.
<package … unique-identifier="pub-id">
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
<dc:type>preview</dc:type>
<dc:identifier id="pub-id">urn:uuid:13b92c40-3f6b-11e3-aa6e-0800200c9a66</dc:identifier>
<meta
property="dcterms:modified">2013-08-01T12:00:00Z</meta>
<dc:source>urn:isbn:9782367932095</dc:source>
…
</metadata>
</package>
The following example shows a minimally complete metadata section, where the Publication is identified as a preview, metadata links back to the source publication and a link to acquire it has also been included.
<package …
unique-identifier="pub-id">
…
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
<dc:title>Norwegian Wood</dc:title>
<dc:language>en</dc:language>
<dc:type>preview</dc:type>
<dc:identifier
id="pub-id">urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809</dc:identifier>
<meta
property="dcterms:modified">2011-01-01T12:00:00Z</meta>
<dc:source>urn:isbn:9781448103706</dc:source>
<link href="http://example.org/book/9781448103706"
rel="acquire"
type="text/html" />
<link href="http://example.org/book/9781448103706.atom"
rel="acquire"
type="application/atom+xml;type=entry;profile=opds-catalog" />
</metadata>
…
</package>
This section is informative
Preview content does not have to be packaged as a separate Publication. In many cases, the subset of resources that constitute the preview can be identified within the context of the complete Publication, and directly extracted to present a preview for the User.
These Embedded Previews provide Authors control over how preview content is generated from the source Publication, instead of third-party vendors selecting which part(s) of the Publication to extract. Embedded Previews also provide an advantage over Preview Publications in that a new Publication does not have to be downloaded, and the Preview Publication replaced, when the User purchases the full version ‒ the full content simply has to be unlocked.
This section explains how to use the Package Document collection element to create such previews: from defining the necessary role to the requirements for a manifest of resources, as well as which (parts of) Content Documents can be viewed.
An Embedded Preview must meet all of the following criteria:
› It must conform to the requirements defined in 3.4 Preview Collections.
An EPUB Reading System must meet all of the following criteria for processing Embedded Previews:
› It must provide access to the preview content identified in the preview collection.
› It may provide a means to acquire the Publication the preview is derived from, as defined in 4. Acquiring Publications.
An embedded Preview is defined in a Package Document collection element [Publications301] with the role attribute value "preview".
The preview collection must include a child manifest collection that identifies all of the EPUB Content Documents in the preview, as well as all the associated resources required to render them.
Each link element’s href attribute must point to an EPUB Content Document. The IRI expressed in the href attribute may include a fragment identifier but must not include EPUB canonical fragment identifiers [EPUBCFI].
The order of child link elements in a preview collection represents the order in which the documents are to be rendered.
The following example shows how a publication can provide a collection that indicates which EPUB Ccontent Documents should be included in a preview (including only part of chapter 3), as well as a manifest of the resources necessary for this preview.
<collection role="preview">
<collection role="manifest">
<link href="chapter1.xhtml"
media-type="application/xhtml+xml" />
<link href="chapter2.xhtml"
media-type="application/xhtml+xml" />
<link href="chapter3.xhtml"
media-type="application/xhtml+xml" />
<link href="stylesheet.css"
media-type="text/css" />
<link href="image1.jpg"
media-type="image/jpeg" />
</collection>
<link href="chapter1.xhtml"/>
<link href="chapter2.xhtml"/>
<link href="chapter3.xhtml#preview"/>
</collection>
While fragment identifiers usually reference a specific location in a document, in the context of a Preview Collection, such fragment identifiers actually reference a range:
› The start position is always the start of the document (body).
› The end position is exclusive of the element referenced in the fragment identifier, and points to the position right before that element.
Instead of creating a separate Preview Publication, the master file containing the Embedded Preview may be used to generate automatically the Preview Publication.
Software generating automatically a Preview Publication from an Embedded Preview must respect the following processing rules:
› It must generate a valid EPUB publication.
› It must generate a Preview Publication that complies with 2. Preview Publications.
› It must generate the spine of the Preview Publication using resources in the same order as listed in the Embedded Preview.
› It must follow the processing rules for URI fragments as defined in 3.5 Fragment identifiers in Preview Collections and only include the fragment of the resource in the Preview Publication.
› It must only contain resources from the original Publication listed in the Embedded Preview along with the Navigation Document.
› It SHOULD adapt the Navigation Document in order to strictly reference resources that are included in the Preview Publication.
› It SHOULD adapt or remove references in preview content to other resources that are not contained in the Embedded Preview.
NOTE
This specification does not mandate how to adapt content for rendering in a preview. Reading Systems might direct links outside the preview content to a generic placeholder page that indicates the content is not available in the preview, might make such links inactive by removing their href attributes, or might employ other mechanisms to handle references to non-preview content.
It is strongly encouraged, however, that all link labels be retained when adapting the preview ‒ including in the table of contents ‒ to give a complete picture of the content available in the full EPUB Publication.
Both Preview Publications and Publications containing Embedded Previews MAY provide a link to allow a User to acquire the full source Publication. To do so, one or more acquire link elements SHOULD be included in the Package Document metadata section.
The following example shows links to an HTML vendor page and an OPDS catalog entry for acquiring the full Publication.
<package …>
…
<metadata
xmlns:dc="http://purl.org/dc/elements/1.1/">
<dc:type>preview</dc:type>
…
<link href="http://example.org/book/9781448103706"
rel="acquire"
type="text/html" />
<link href="http://example.org/book/9781448103706.atom"
rel="acquire"
type="application/atom+xml;type=entry;profile=opds-catalog" />
</metadata>
…
</package>
This specification does not define how Reading Systems and vendors are to negotiate access to the acquired Publication.
While this relationship value may be used with any potential media type, this specification recommends using either "text/html" for publications that can be acquired in a browser, or "application/atom+xml;type=entry;profile=opds-catalog" for an [OPDS] entry.
This section is informative
Active members of the working group included:
IDPF Members
Invited Experts/Observers
[EPUBCFI] EPUB Canonical Fragment Identifier (epubcfi) Specification
[OPDS] Open Publication Distribution System 1.1
[Publications301] EPUB Publications 3.0.1.
[RFC2119] Key words for use in RFCs to Indicate Requirement Levels (RFC 2119) . March 1997.