Skip to content

Latest commit

 

History

History
191 lines (125 loc) · 7.94 KB

epub.md

File metadata and controls

191 lines (125 loc) · 7.94 KB
Raw

EPUB Profile

Editors:

  • Hadrien Gardeur

Participate:

Introduction

While EPUB publications can mostly be converted directly to the Readium Web Publication Manifest, a number of collection roles and properties remain specific to EPUB.

This profile is meant to facilitate backward compatibility with EPUB and ensure that these specialized elements are not lost when converting to the Readium Web Publication Manifest.

1. Declaring conformance with the EPUB Profile

In order to declare that it conforms to the EPUB Profile, a Readium Web Publication Manifest must include a conformsTo element that contains https://readium.org/webpub-manifest/profiles/epub as one of its values.

2. Restrictions on resources in the readingOrder

A Readium Web Publication Manifest that conforms to the EPUB Profile must strictly reference XHTML documents (application/xhtml+xml) in its readingOrder.

While EPUB itself allows SVG and other formats as long as an XHTML fallback is provided, this is not the case for this profile, which requires to reverse the fallback chain.

3. Layout

The layout of a publication that conforms to the EPUB profile defaults to reflowable.

This profile also supports fixed layout publications where the layout property is set to fixed for the entire publication.

This behaviour can be overriden by specific resources in the reading order using the layout property, as defined in this document.

4. Collection Roles

Role Semantics Compact? Required?
landmarks Identifies the collection that contains a list of points of interest. Yes No
loa Identifies the collection that contains a list of audio resources. Yes No
loi Identifies the collection that contains a list of illustrations. Yes No
lot Identifies the collection that contains a list of tables. Yes No
lov Identifies the collection that contains a list of videos. Yes No
pageList Identifies the collection that contains a list of pages. Yes No

5. Metadata

Key Semantics Type
mediaOverlay Contains optional Media Overlay specific metadata. Media Overlay Object

mediaOverlay

Key Semantics Type
activeClass Author-defined CSS class name to apply to the currently-playing EPUB Content Document element. CSS Class Name
playbackActiveClass Author-defined CSS class name to apply to the EPUB Content Document's document element when playback is active. CSS Class Name

The EPUB specification provides dedicated elements for Media Overlay with:

  • the total duration of a Media Overlay publication
  • the duration of specific SMIL files
  • and an optional narrator

In the context of the Readium Web Publication Manifest, these dedicated elements are superseded by:

  • the use of duration in metadata for the total duration of a publication
  • the use of duration in Link Objects for the duration of specific resources (SMIL, SMIL-equivalent or media resources)
  • and a dedicated element for narrator

6. Link Properties

This profile defines additional Link properties:

Key Semantics Type Values
contains Identifies content contained in the linked resource, that cannot be strictly identified using a media type. Array mathml, onix, remote-resources, js, svg or xmp
layout Hint about the nature of the layout for the linked resources. String fixed or reflowable

contains

While the media type is the main way to identify the nature of a resource in a Link Object, in certain cases it isn't sufficient because:

  • a number of metadata standards either rely on XML and JSON without defining a specific media type (ONIX, XMP);
  • the media type doesn't indicate if an HTML/XHTML resource contains MathML, SVG or Javascript, or if some of its resources are not available in the package.

contains is meant to convey that information in the Properties Object using an array of string values.

{
  "href": "record.xml", "rel": "record", "type": "application/xml",
  "properties": {
    "contains": ["onix"]
  }
}

{
  "href": "chapter1.html", "type": "text/html",
  "properties": {
    "contains": ["svg", "remote-resources"]
  }
}

layout

By default, each item in the readingOrder follows the layout specified in metadata but the EPUB profile allow content creators to override this behaviour using the layout property on specific resources.

{
  "href": "page1.html", "type": "text/html",
  "properties": {
    "layout": "fixed"
  }
}

Appendix A - JSON Schema

The following JSON Schema resources for this profile are available under version control:

For the purpose of validating a Readium Web Publication Manifest, use the following JSON Schema resources:

Appendix B - Deprecated properties

layout in a presentation object

This specification was initially responsible for documenting the layout of an entire publication using either: reflowable or fixed.

This was handled using a layout property in a presentation object.

"metadata": {
  "title": "Bella the dragon",
  "presentation": {
    "layout": "fixed"
  }
}

This is no longer supported by this profile because layout became a first-class metadata defined in the default context.

"metadata": {
  "title": "Bella the dragon",
  "layout": "fixed"
}

Orientation

The EPUB specification allow content creators to specify the intended orientation of:

This was originally supported in this EPUB profile through:

  • an orientation property for the presentation object in metadata (for the entire publication)
  • and an orientation property in the properties of a Link Object (for a specific resource)

This is no longer supported in Readium because forcing an orientation goes against the principles that we're trying to follow, where the user is always free to decide what feels best for them.

Spreads

The EPUB specification allow content creators to specify when synthetic spreads should be presented to the user for a fixed layout document either for:

This was originally supported in this EPUB profile through:

  • a spread property for the presentation object in metadata (for the entire publication)
  • and a spread property in the properties of a Link Object (for a specific resource)

This is no longer supported in Readium because forcing spreads goes against the principles that we're trying to follow, where the user is always free to decide what feels best for them.