Draft Specification 9 December 2013
Copyright © 2012-2013 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
Matt Garrish (Invited Expert), Hadrien Gardeur (Feedbooks), 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, Previews in EPUB, 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[a]:
› 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 [b]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[c].
› It SHOULD adapt or remove references in the HTML resources to other resources that are not contained in the Embedded Preview.
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[d] 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.
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.
[a]Makoto MURATA:
I am not sure if we have to formally define the processing rules for the conversion. We define embedded previews and preview publications. Somebody might want to intentionally deviate from the rules shown here for some reason. As long as the output is a valid EPUB publication (or even a valid preview publication), there is nothing wrong.
hadrien.gardeur:
I disagree here, since these processing rules are fairly basic.
Some of them are also very good to have: for example we want to make sure that the order of the links is respected since it is meaningful. Same thing with fragments, we want to make sure that only the proper fragment is included.
[b]Makoto MURATA:
SHOULD?
hadrien.gardeur:
This was changed from "resources" to "resources from the original Publication".
[c]Tzviya Siegman:
there is a lot room for interpretation, and I think this will lead to cutting parts of the nav that do not ref the preview. The TOC is an important part of a preview from a publisher/user perspective. Is intent is to change the <a>s to <span>s so it is still a valid nav without links? Perhaps "should adapt the nav doc to reference resources in the preview and list but not reference the other resources in complete publication".
hadrien.gardeur:
First of all, this is a SHOULD, not a MUST.
I'm in favor of keeping the entire TOC, but I don't think that we should keep links to resources that are no longer in the file.
I'm sure that this would at least generate a warning in epubcheck, and I've seen many reading system crash when the link points to nowhere.
[email protected] proposed removing href from the a element in today's call.
While this would be valid from a spec perspective, I'm not sure how the RS would behave.
The other option would be to add an empty element at the end of the preview and replace all links to documents that are not embedded in a preview with a link to that element.
This should work with any RS.
The second option is what we currently do at Feedbooks using https://github.com/Feedbooks/epub_preview_factory
[d]Matt Garrish:
Temporary link until the vocab is published.
Matt Garrish:
The acquire property def should link back here when this spec is published, too.