This section is informative
The Package Document carries bibliographic and structural metadata about a Rendition of an EPUB Publication, and is thus the primary source of information about how to process and display that Rendition.
The Package Document is an XML document consisting of a set of container elements, each dedicated to housing information about a particular aspect of the Rendition. These containers effectively centralize metadata, detail the individual resources that compose the Rendition and provide reading order and other information for rendering the EPUB Publication is represents to a User.
The following list summarizes the information a Package Document contains:
Rendition metadata — mechanisms for including and/or referencing metadata applicable to the EPUB Publication and/or the specific Rendition of it, including for particular resources within the Rendition.
A manifest — identifies (via IRI) and describes (via MIME media type) the set of resources that collectively compose the given Rendition of the EPUB Publication.
A spine — an ordered sequence of ID references to top-level resources in the manifest from which all other resources in the set can be reached or utilized. The spine defines the default reading order of the given Rendition.
Fallback chains — an optional means for defining an ordered list of top-level resources that can be considered content equivalents that a Reading System can choose between for rendering.
Bindings — an optional means of associating script-based implementations with custom media types.
A Package Document must meet all of the following criteria:
Package Documents have the MIME media type application/oebps-package+xml [RFC4839].
All elements [XML] defined in this section are in the http://www.idpf.org/2007/opf namespace [XMLNS] unless otherwise specified.
package Element
The package element is the root container of the Package Document and encapsulates metadata and resource information for a Rendition.
package
The package element is the root element of the Package Document.
version [required]
Specifies the EPUB specification version to which the given Rendition conforms.
The attribute must have the value 3.0 to indicate compliance with this version of the specification.
unique-identifier [required]
An IDREF [XML] that identifies the dc:identifier element that provides the package's preferred, or primary, identifier.
Refer to Publication Identifiers for more information.
prefix [optional]
Declaration mechanism for prefixes not reserved by this specification.
Refer to The prefix Attribute for more information.
xml:lang [optional]
Specifies the language used in the contents and attribute values of the carrying element and its descendants, as defined in section 2.12 Language Identification of [XML].
dir [optional]
Specifies the base text direction of the content and attribute values of the carrying element and its descendants.
Inherent directionality specified using [Unicode] takes precedence over this attribute.
Allowed values are ltr (left-to-right) and rtl (right-to-left).
id [optional]
The ID [XML] of this element, which must be unique within the document scope.
In this order: metadata [required], manifest [required], spine [required], guide [optional/deprecated], bindings [optional], collection [0 or more]
identifier Element
The [DCMES] identifier element contains a single identifier associated with the given Rendition of the EPUB Publication, such as a UUID, DOI, ISBN or ISSN.
dc:identifier
http://purl.org/dc/elements/1.1/
Required child of metadata . Repeatable.
id [optional]
The ID [XML] of this element, which must be unique within the document scope.
The id attribute is required on the identifier element containing the unique identifier. See below.
Text
Every Rendition's metadata section must include at least one identifier element containing an unambiguous identifier for the EPUB Publication. Multiple identifier elements are permitted, but only one can be marked as the Unique Identifier via the package element unique-identifier attribute.
The following example shows the unique identifier element for an EPUB Publication.
<package … unique-identifier="pub-id">
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
<dc:identifier id="pub-id">urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809</dc:identifier>
…
</metadata>
</package>
This specification makes a distinction between the Unique Identifier for an EPUB Publication and the identifier that uniquely identifies a specific version of it (i.e., to be able to differentiate different versions of the same EPUB Publication). Whenever a Rendition is modified, it must include a new last modified date.
To identify a specific version of a packaged EPUB Publication, a Release Identifier can be constructed by combining the Unique Identifier with the last modified date of the Rendition. For more information on the semantics and requirements of the Release Identifier, refer to Release Identifier.
Identifiers may differ from Rendition to Rendition.
This specification imposes no additional restrictions or requirements on identifiers except that they must be at least one character in length. It is strongly recommended that all identifiers be fully qualified URIs, however.
Reading Systems must trim all leading and trailing whitespace from the element value, as defined by the XML specification [XML], before processing the value.
To determine whether an identifier conforms to an established system or has been granted by an issuing authority, Reading Systems should parse the value of the property. For additional precision (e.g., if the scheme cannot be determined from the value or could lead to an ambiguous result), Authors may attach an identifier-type property to assist in Reading System identification. When included, the identifier-type property should take precedence over value parsing the identifier.
The following example shows how an identifier can be additionally marked as a DOI using the identifier-type property.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
<dc:identifier id="pub-id">urn:doi:10.1016/j.iheduc.2008.03.001</dc:identifier>
<meta refines="#pub-id" property="identifier-type" scheme="onix:codelist5">06</meta>
…
</metadata>
This specification does not require or endorse the use of any specific scheme for identifiers, and imposes no restrictions or requirements on identifier-type identifiers beyond those specified in the property definition.
When an EPUB Publication is derived from another publication, the identifier for that source publication may be included in the EPUB Publication metadata, and must be represented using the DCMES source element.
title Element
The [DCMES] title element represents an instance of a name given to the EPUB Publication.
dc:title
http://purl.org/dc/elements/1.1/
Required child of metadata . Repeatable.
id [optional]
The ID [XML] of this element, which must be unique within the document scope.
xml:lang [optional]
Specifies the language used in the contents and attribute values of the carrying element and its descendants, as defined in section 2.12 Language Identification of [XML].
dir [optional]
Specifies the base text direction of the content and attribute values of the carrying element and its descendants.
Inherent directionality specified using [Unicode] takes precedence over this attribute.
Allowed values are ltr (left-to-right) and rtl (right-to-left).
Text
Every metadata section must include at least one title element containing the title for the EPUB Publication. Multiple title elements are permitted, but the title-type property should be attached to indicate the type of title (e.g., the main title of a work or a subtitle).
The following example shows how to indicate different title types.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
…
<dc:title id="t1">A Dictionary of Modern English Usage</dc:title>
<meta refines="#t1" property="title-type">main</meta>
<dc:title id="t2">First Edition</dc:title>
<meta refines="#t2" property="title-type">edition</meta>
<dc:title id="t3">Fowler's</dc:title>
<meta refines="#t3" property="title-type">short</meta>
…
</metadata>
When adding the title-type property, Authors should designate only one title element as containing the main title for the Publication. If no means of determining title types is provided, or understood, Reading Systems must treat the first title element in document order as the main title. This specification does not define how additional title elements should be processed in such situations.
The optional display-seq property may also be attached to each title to indicate their primacy for display and other rendering purposes.
The following example shows how to indicate display sequence.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
…
<dc:title id="t1">The Red and the Black</dc:title>
<meta refines="#t1" property="title-type">main</meta>
<meta refines="#t1" property="display-seq">1</meta>
<dc:title id="t2">A Chronicle of the Nineteenth Century</dc:title>
<meta refines="#t2" property="title-type">subtitle</meta>
<meta refines="#t2" property="display-seq">2</meta>
<dc:title id="t3">A Chronicle of 1830</dc:title>
<meta refines="#t3" property="title-type">subtitle</meta>
<meta refines="#t3" property="display-seq">3</meta>
…
</metadata>
Titles may differ from Rendition to Rendition.
This specification imposes no additional restrictions or requirements on titles except that they must be at least one character in length.
Reading Systems must trim all leading and trailing whitespace from the element value, as defined by the XML specification [XML], before processing the value.
› Examples
The following example shows how the title "THE LORD OF THE RINGS, Part One: The Fellowship of the Ring" could be classified.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
<dc:title id="t1">The Fellowship of the Ring</dc:title>
<meta refines="#t1" property="title-type">main</meta>
<dc:title id="t2">The Lord of the Rings</dc:title>
<meta refines="#t2" property="title-type">collection</meta>
<dc:title id="t3">THE LORD OF THE RINGS, Part One: The Fellowship of the Ring</dc:title>
<meta refines="#t3" property="title-type">expanded</meta>
…
</metadata>
The following example shows how the complex title "The Great Cookbooks of the World: Mon premier guide de cuisson, un Mémoire. The New French Cuisine Masters, Volume Two. Special Anniversary Edition" could be classified.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
<dc:title id="t1" xml:lang="fr">Mon premier guide de cuisson, un Mémoire</dc:title>
<meta refines="#t1" property="title-type">main</meta>
<meta refines="#t1" property="display-seq">2</meta>
<dc:title id="t2">The Great Cookbooks of the World</dc:title>
<meta refines="#t2" property="title-type">collection</meta>
<meta refines="#t2" property="display-seq">1</meta>
<dc:title id="t3">The New French Cuisine Masters</dc:title>
<meta refines="#t3" property="title-type">collection</meta>
<meta refines="#t3" property="display-seq">3</meta>
<dc:title id="t4">Special Anniversary Edition</dc:title>
<meta refines="#t4" property="title-type">edition</meta>
<meta refines="#t4" property="display-seq">4</meta>
<dc:title id="t5">The Great Cookbooks of the World:
Mon premier guide de cuisson, un Mémoire.
The New French Cuisine Masters, Volume Two.
Special Anniversary Edition</dc:title>
<meta refines="#t5" property="title-type">expanded</meta>
…
</metadata>
› 3.4.5 The DCMES language Element
The [DCMES] language element specifies the language of the content of the given Rendition.
dc:language
http://purl.org/dc/elements/1.1/
Required child of metadata .
id [optional]
The ID [XML] of this element, which must be unique within the document scope.
Text
Each Rendition's metadata section must include at least one language element with a value conforming to [RFC5646].
The following example shows an EPUB Publication is in U.S. English.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
…
<dc:language>en-US</dc:language>
…
</metadata>
Additional language elements may be included for multilingual Publications, but each element's value must conform to [RFC5646].
Languages may differ from Rendition to Rendition.
Reading Systems must trim all leading and trailing whitespace from the element value, as defined by the XML specification [XML], before processing the value.
› 3.4.6 The DCMES Optional ElementsAll elements from the [DCMES] element set — except for identifier , language and title , as defined above — are designated as optional. These elements all conform to the following generalized definition:
contributor | coverage | creator | date | description | format | publisher | relation | rights | source | subject | type
http://purl.org/dc/elements/1.1/
Optional child of metadata . Repeatable.
id [optional]
The ID [XML] of this element, which must be unique within the document scope.
xml:lang* [optional]
Specifies the language used in the contents and attribute values of the carrying element and its descendants, as defined in section 2.12 Language Identification of [XML].
dir* [optional]
Specifies the base text direction of the content and attribute values of the carrying element and its descendants.
Inherent directionality specified using [Unicode] takes precedence over this attribute.
Allowed values are ltr (left-to-right) and rtl (right-to-left).
Text
* The xml:lang and dir attributes are permitted only on the following elements: contributor, coverage, creator, description, publisher, relation, rights and subject.
Optional metadata may differ from Rendition to Rendition.
The value of all optional [DCMES] elements must be at least one character in length.
Reading Systems must trim all leading and trailing whitespace from the element value, as defined by the XML specification [XML], before processing the value.
Except as detailed below, this specification does not modify the [DCMES] definitions for these elements.
› The DCMES contributor Element
The contributor element is used to represent the name of a person, organization, etc. that played a secondary role in the creation of the content of an EPUB Publication.
The use of the contributor element is identical to the use of the creator element in all other respects, as detailed in the next section.
› The DCMES creator Element
The creator element represents the name of a person, organization, etc. responsible for the creation of the content of an EPUB Publication. The role property can be attached to the element to indicate the function the creator played in the creation of the content.
The following example shows how to represent a creator as an author using a MARC relators term.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
…
<dc:creator id="creator">Haruki Murakami</dc:creator>
<meta refines="#creator" property="role" scheme="marc:relators" id="role">aut</meta>
…
</metadata>
The creator element should contain the name of the creator as a Reading System will present it to a User. The file-as property may be attached to include a normalized form of the name, and the alternate-script property can be used to represent a creator's name in another language or script.
The following example shows the different ways a creator's name can be included to facilitate processing and rendering.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
…
<dc:creator id="creator">Haruki Murakami</dc:creator>
<meta refines="#creator" property="role" scheme="marc:relators" id="role">aut</meta>
<meta refines="#creator" property="alternate-script" xml:lang="ja">村上 春樹</meta>
<meta refines="#creator" property="file-as">Murakami, Haruki</meta>
…
</metadata>
If an EPUB Publication has more than one creator, each should be included in a separate creator element. The order in which to render the creator names should be specified using the display-seq property.
The following example shows how to indicate the display order for creator elements.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
…
<dc:creator id="creator01">Lewis Carroll</dc:creator>
<meta refines="#creator01" property="role" scheme="marc:relators">aut</meta>
<meta refines="#creator01" property="display-seq">1</meta>
<dc:creator id="creator02">John Tenniel</dc:creator>
<meta refines="#creator02" property="role" scheme="marc:relators">ill</meta>
<meta refines="#creator02" property="display-seq">2</meta>
…
</metadata>
If no means of establishing the primacy of creators for rendering is identifiable, Reading Systems must use the document order of creator elements in the metadata section (i.e., where the first creator element encountered is the primary creator). If a Reading System exposes creator metadata for the User, it should include all the creators listed in the metadata section whenever possible (e.g., when not constrained by display considerations).
Secondary contributors should be represented using DCMES contributor elements.
› The DCMES date Element
The date element must only be used to define the publication date of the EPUB Publication. The publication date is not the same as the last modified date (the last time the Rendition was changed), which must be included using the [DCTERMS] modified property.
It is recommended that the date string conform to [ISO8601], particularly the subset expressed in W3C Date and Time Formats [DateTime], as such strings are both human and machine readable.
The following example shows a publication date.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
…
<dc:date>2000-01-01T00:00:00Z</dc:date>
…
</metadata>
Additional dates should be expressed using the specialized date properties available in the [DCTERMS] vocabulary, or similar.
The publication date may be common to all instances of an EPUB Publication or may change from instance to instance (e.g., if the EPUB Publication gets generated on demand).
Only one date element is allowed.
› The DCMES source Element
The source element identifies the related resource(s) from which this EPUB Publication is derived.
When a Rendition includes page identifiers, using the pagebreak property from the EPUB Structural Semantics Vocabulary [StructureVocab], a source-of refinement property should be attached to the source element that identifies the source of the pagination.
The following example shows the ISBN identifier for an EPUB Publication together with the source ISBN identifier for the print work it was derived from.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
…
<dc:identifier id="isbn-id">urn:isbn:9780101010101</dc:identifier>
<meta refines="#isbn-id" property="identifier-type" scheme="onix:codelist5">15</meta>
<dc:source id="src-id">urn:isbn:9780375704024</dc:source>
<meta refines="#src-id" property="identifier-type" scheme="onix:codelist5">15</meta>
<meta refines="#src-id" property="source-of">pagination</meta>
…
</metadata>
› The DCMES type Element
The type element is used to indicate that the given EPUB Publication is of a specialized type (e.g., annotations packaged in EPUB format or a dictionary).
The IDPF maintains an informative registry of specialized EPUB Publication types for use with this element at http://www.idpf.org/epub/vocab/package/types .
link Element
The link element is used to associate resources with the given Rendition of the EPUB Publication, such as metadata records.
link
As a child of metadata . Repeatable.
href [required]
An absolute or relative IRI reference [RFC3987] to a resource.
rel [required]
A space-separated list of property values.
id [optional]
The ID [XML] of this element, which must be unique within the document scope.
refines [optional]
Identifies the expression or resource augmented by this element. The value of the attribute must be a relative IRI [RFC3987] referencing the resource or element it describes.
When the refines attribute is omitted, the expression applies to the EPUB Publication as a whole.
media-type [optional]
A media type [RFC2046] that specifies the type and format of the resource referenced by this link.
Empty
The metadata element may contain zero or more link elements.
The href attribute of the link element identifies the location of the resource — inclusion of which is optional in the container file — and the rel attribute defines the nature of the resource (i.e., its relation to the given Rensition of the EPUB Publication or property specified in the refines attribute). Reading Systems are not required to dereference these resources. Refer to Metadata link Properties for the list of resource types that are recognized by this specification.
Resources identified by the link element href attribute must not be listed in the manifest.
When the link element references a metadata record, precedence must be given to metadata defined inline in the Package Document metadata element in the case of conflicts.
The optional refines attribute can be attached when the referenced resource applies to another metadata item (e.g., to tie an XML Signature [XML DSIG Core] to a metadata authority). The resource applies to the Rendition when the attribute is not present.
If a Reading System does not recognize the relationship of the resource as defined in the rel attribute, it should ignore the link element.
› Examples
The following example shows the link element used to associate three metadata resources with the Rendition: an ONIX record, an XMP record, and a link to an informational web page. Note that as foaf is not a predefined prefix, the metadata extensibility mechanism is employed to associate the vocabulary.
<package … prefix="foaf: http://xmlns.com/foaf/spec/">
<metadata>
…
<link rel="onix-record" href="http://example.org/onix/12389347"/>
<link rel="xmp-record" href="http://example.org/xmp/12389347"/>
<link rel="foaf:homepage" href="http://example.org/book-info/12389347" />
…
</metadata>
…
</package>
› 3.4.10 The manifest Element
The manifest element provides an exhaustive list of the Publication Resources that constitute the given Rendition, each represented by an item element.
manifest
id [optional]
The ID [XML] of this element, which must be unique within the document scope.
One or more item elements [required]
This specification supports internationalized resource naming, so elements and attributes that reference Publication Resources accept IRIs as their value. For compatibility with older Reading Systems that only accept URIs, resource names should be restricted to the ASCII character set.
› 3.4.11 Theitem Element
The item element represents a Publication Resource.
item
As a child of manifest . Repeatable.
id [required]
The ID [XML] of this element, which must be unique within the document scope.
href [required]
An IRI [RFC3987] specifying the location of the Publication Resource described by this item.
media-type [required]
A media type [RFC2046] that specifies the type and format of the Publication Resource described by this item.
fallback [conditionally required]
An IDREF [XML] that identifies the fallback for a non-Core Media Type.
Refer to Manifest Fallbacks for more information.
properties [optional]
A space-separated list of property values.
Refer to Manifest item Properties for a set of properties defined by this specification.
media-overlay [optional]
An IDREF [XML] that identifies the Media Overlay Document for the resource described by this item.
Refer to Packaging [MediaOverlays301] for more information.
Empty
Each item element in the manifest identifies a Publication Resource by the IRI provided in its href attribute. The IRI may be absolute or relative. In the case of relative IRIs, Reading Systems must use the IRI of the Package Document as the base when resolving these to absolute IRIs. The resulting absolute IRI must be unique within the manifest scope.
All Publication Resources must be referenced from the manifest, regardless of whether they are included in the EPUB Container or made available remotely. Refer to Publication Resource Locations for media type-specific requirements regarding resource locations.
The Publication Resource identified by an item element must conform to the applicable specification(s) as inferred from the MIME media type provided in the media-type attribute. Core Media Type Resources must use the media type designated in EPUB Core Media Types.
All Foreign Resources must provide a fallback as defined in Restrictions and Fallbacks.
All Publication Resources must declare any applicable descriptive metadata properties as defined in Manifest item Properties via the item element properties attribute. Exactly one item must be declared as the EPUB Navigation Document using the nav property.
Reading Systems must ignore all descriptive metadata properties that they do not recognize.
The manifest is not self-referencing: it must not include an item element that refers to the Package Document itself.
The order of item elements in the manifest is not significant. The presentation sequence of content documents is provided in the spine .
› Examples
The following example shows a manifest that only contains Core Media Type Resources.
<manifest>
<item id="nav"
href="nav.xhtml"
properties="nav"
media-type="application/xhtml+xml"/>
<item id="intro"
href="intro.xhtml"
media-type="application/xhtml+xml"/>
<item id="c1"
href="chap1.xhtml"
media-type="application/xhtml+xml"/>
<item id="c1-answerkey"
href="chap1-answerkey.xhtml"
media-type="application/xhtml+xml"/>
<item id="c2"
href="chap2.xhtml"
media-type="application/xhtml+xml"/>
<item id="c2-answerkey"
href="chap2-answerkey.xhtml"
media-type="application/xhtml+xml"/>
<item id="c3"
href="chap3.xhtml"
media-type="application/xhtml+xml"/>
<item id="c3-answerkey"
href="chap3-answerkey.xhtml"
media-type="application/xhtml+xml"/>
<item id="notes"
href="notes.xhtml"
media-type="application/xhtml+xml"/>
<item id="cover"
href="./images/cover.svg"
properties="cover-image"
media-type="image/svg+xml"/>
<item id="f1"
href="./images/fig1.jpg"
media-type="image/jpeg"/>
<item id="f2"
href="./images/fig2.jpg"
media-type="image/jpeg"/>
<item id="css"
href="./style/book.css"
media-type="text/css"/>
<item id="pls"
href="./speech/dict.pls"
media-type="application/pls+xml"/>
</manifest>
The following example shows a manifest that references two Foreign Resources, and therefore uses the fallback chain mechanism to supply content alternatives. The fallback chain terminates with a Core Media Type.
<manifest>
<item id="item1"
href="chap1_docbook.xml"
media-type="application/docbook+xml"
fallback="fall1"/>
<item id="fall1"
href="chap1.xml"
media-type="application/z3986-auth+xml"
fallback="fall2" />
<item id="fall2"
href="chap1.xhtml"
media-type="application/xhtml+xml"/>
…
</manifest>
› 3.4.12 The spine Element
The spine element defines the default reading order of the given Rendition of the EPUB Publication content by defining an ordered list of manifest item references.
spine
id [optional]
The ID [XML] of this element, which must be unique within the document scope.
toc [optional]
An IDREF [XML] that identifies the manifest item that represents the superseded NCX.
Refer to NCX Superseded for more information.
page-progression-direction [optional]
The global direction in which the content flows.
Allowed values are ltr (left-to-right), rtl (right-to-left) and default.
When the default value is specified, the Author is expressing no preference and the Reading System may chose the rendering direction. This value must be assumed when the attribute is not specified.
One or more itemref elements [required]
The spine represents an ordered subset of the Publication Resources listed in the manifest, providing the default reading order for the given Rendition.
Reading Systems must provide a means of rendering the Rendition in the order defined in the spine, which includes: 1) recognizing the first primary itemref as the beginning of the default reading order; and, 2) rendering successive primary items in the order given in the spine.
All EPUB Content Documents that are linked to from EPUB Content Documents in the spine must themselves be listed in the spine. Linked documents include documents referenced from the href attribute of a and area elements and scripted links (e.g., using DOM Events and/or form elements). All EPUB Content Documents linked to from the EPUB Navigation Document must be listed in the spine, as well, regardless of whether the Navigation Document has been included in the spine. The requirement to list linked documents applies recursively (i.e., all Content Documents linked to from linked Content Documents also have to be listed, and so on.).
Although the page-progression-direction attribute sets the global flow direction, individual Content Documents and parts of Content Documents may override this setting (e.g., via the writing-mode CSS property). Reading Systems may also provide mechanisms to override the default direction (e.g., buttons or settings that allow the application of alternate style sheets).
Reading Systems must ignore the page progression direction defined in pre-paginated XHTML Content Documents. The page-progression-direction attribute defines the flow direction from one fixed-layout page to the next.
› NCX Superseded
The NCX feature defined in [OPF2] is superseded by the EPUB Navigation Document [ContentDocs301] . EPUB 3 Publications may include an NCX (as defined in OPF 2.0.1) for EPUB 2 Reading System forwards compatibility purposes, but EPUB 3 Reading Systems must ignore the NCX.
noteAs the EPUB 2 NCX and the EPUB 3 Navigation Document use different mechanisms for identification in the Package Document (the spine toc attribute and the nav property on the manifest item element, respectively) they can co-exist without conflict in an EPUB 3 Publication.
itemref Element
The child itemref elements of the spine represent a sequential list of Publication Resources (typically EPUB Content Documents). The order of the itemref elements defines the default reading order of the given Rendition of the EPUB Publication.
itemref
As a child of spine . Repeatable.
idref [required]
linear [optional]
Specifies whether the referenced content is primary.
The value of the attribute must be yes or no. The default value is yes.
id [optional]
The ID [XML] of this element, which must be unique within the document scope.
properties [optional]
A space-separated list of property values.
Refer to Spine itemref Properties for a set of properties defined by this specification.
Empty
Each itemref element must reference a unique item in the manifest via its idref attribute.
Each referenced manifest item must be either a) an EPUB Content Document or b) another type of Publication Resource which, regardless of whether it is a Core Media Type Resource or a Foreign Resource , must include an EPUB Content Document in its fallback chain.
The itemref element linear attribute indicates whether referenced item is considered primary (yes) or auxiliary (no) in the spine. Each Rendition must include at least one primary itemref.
The linear attribute may be used to enable Reading Systems to distinguish presentation of body content from supplementary content which might be, for example, presented in a popup window or omitted from an aural rendering. Reading Systems should provide Users the ability to control whether non-linear content is rendered in the default reading order.
Any applicable descriptive metadata properties, such as those defined in the Spine itemref Properties, should be declared via the properties attribute.
Reading Systems must ignore all metadata properties expressed in the properties attribute that they do not recognize.
› Examples
The following example shows a spine element corresponding to the manifest example above.
<spine page-progression-direction="ltr">
<itemref idref="intro"/>
<itemref idref="c1"/>
<itemref idref="c1-answerkey" linear="no"/>
<itemref idref="c2"/>
<itemref idref="c2-answerkey" linear="no"/>
<itemref idref="c3"/>
<itemref idref="c3-answerkey" linear="no"/>
<itemref idref="notes" linear="no"/>
</spine>
› 3.4.14 The guide Element [DEPRECATED]
The guide element [OPF2] is deprecated in favor of the landmarks feature in the EPUB Navigation Document. Refer to The landmarks nav Element [ContentDocs301] for more information.
Authors may include the guide element in the Package Document for EPUB 2 Reading System forwards compatibility purposes. EPUB 3 Reading Systems must ignore the guide element when provided in EPUB 3 Publications whose EPUB Navigation Document includes the landmarks feature.
bindings Element
The bindings element defines a set of custom handlers for media types not supported by this specification.
bindings
Optional fourth or fifth child of package , following spine or guide .
None.
One or more mediaType elements [required]
The package element may contain at most one bindings element.
The bindings element provides a means for Authors to include more sophisticated fallbacks than would otherwise be possible with the [HTML5] object element's intrinsic fallback mechanisms. When present, Reading Systems that support scripting must utilize the bindings element to handle object elements that reference unsupported media types.
Each of the bindings element's child mediaType elements defines a unique handler for one of the foreign media types referenced in the Rendition's XHTML Content Documents.
When an unsupported media type is encountered during processing of a document, the Reading System must look up the handler in the bindings element by checking the media-type attribute of each mediaType element for a match (and before attempting any other type of fallback processing). If a match is found, the XHTML Content Document referenced in the element's handler attribute must be instantiated instead of the referenced resource. If no match is found, the Reading System should continue with normal fallback processing (i.e., check for an intrinsic fallback for the object).
The Reading System must instantiate the designated handler as if it had been referenced from the object element's data attribute with the following parameters:
src
the value of which must be an IRI [RFC3987] to the resource (i.e., the value of the object element's data attribute).
type
the value of which must be the resource media type (i.e., the value of the object element's type attribute).
Any additional param children of the object element must be similarly added as parameters using the param element's name attribute as the new parameter name and its value attribute as the new value.
For example, the following object element containing a foreign media type:
<object data="horse.ogg" type="audio/ogg">
<param name="autoplay" value="false"/>
</object>
would result in the following query string being sent to the handler XHTML Content Document after processing:
src=horse.ogg&type=audio/ogg&autoplay=false
All IRI reserved characters, plus the characters <, >, ", space, {, }, |, \, ^ and `, in the generated query string must be encoded and decoded as per [RFC3987].
object elements that reference media types handled by the bindings element are only processed in spine-referenced XHTML Content Documents (i.e., they are ignored in container-constrained scripting contexts ).
› Example
The following partial example illustrates how bindings can be used to provide a slideshow.
Consider a Rendition of an EPUB Publication with the following Package Document:
<package …>
…
<manifest>
<item id="pict1"
href="images/Pict1.jpg"
media-type="image/jpeg"/>
…
<item id="content"
href="content.xhtml"
media-type="application/xhtml+xml"/>
<item id="impl"
href="impl.xhtml"
media-type="application/xhtml+xml"
properties="scripted"/>
<item id="slideshow"
href="slideshow.xml"
media-type="application/x-demo-slideshow"/>
</manifest>
<bindings>
<mediaType handler="impl"
media-type="application/x-demo-slideshow"/>
</bindings>
…
</package>
and the following content in the file content.xhtml:
<html …>
…
<body>
…
<object data="slideshow.xml"
type="application/x-demo-slideshow">
<img src="images/Pict1.jpg"/>
<img src="images/Pict2.jpg"/>
<img src="images/Pict3.jpg"/>
<img src="images/Pict4.jpg"/>
</object>
…
</body>
</html>
and the following content in the file slideshow.xml:
<slides>
<slide src="images/Pict1.jpg" dur="3"/>
<slide src="images/Pict2.jpg" dur="3"/>
<slide src="images/Pict3.jpg" dur="3"/>
<slide src="images/Pict4.jpg" dur="3"/>
</slides>
Depending on the capabilities of the User's Reading System, they will see one of the following renderings of the slideshow:
If the Reading System supports the native slideshow format, it will render a rotating set of images as specified in slideshow.xml.
If the Reading System cannot support the slideshow media type but supports scripting, it can check the bindings element in the Package Document for a scripted fallback. There it will find a reference to the item element containing the handler document (impl.xhtml). The Reading System can now load this document to render a JavaScripted equivalent of the slideshow (source not shown).
If the Reading System does not support the slideshow media type and also does not support scripting, it will use the fallback images specified in the object element to show a static set of all the images.
collection Element
The collection element defines a related group of resources.
collection
Optional sixth element of package. Repeatable.
xml:lang [optional]
Specifies the language used in the contents and attribute values of the carrying element and its descendants, as defined in section 2.12 Language Identification of [XML].
dir [optional]
Specifies the base text direction of the content and attribute values of the carrying element and its descendants.
Inherent directionality specified using [Unicode] takes precedence over this attribute.
Allowed values are ltr (left-to-right) and rtl (right-to-left).
id [optional]
The ID [XML] of this element, which must be unique within the document scope.
role [required]
Specifies the nature of the collection, as defined below.
In this order: metadata [optional], ( collection [1 or more] or ( collection [0 or more], link [1 or more] ))
The collection element allows resources to be assembled into logical groups for a variety of potential uses: enabling content that has been split across multiple EPUB Content Documents to be reassembled back into a meaningful unit (e.g., an index split across multiple documents), identifying resources for specialized purposes (e.g., preview content), or collecting together resources that present additional information about the given Rendition.
The collection element, as defined in this section, represents a generic framework from which specific implementations are intended to be derived (e.g., through IDPF sub-specifications). Such implementations must define the purpose of the collection element within a Rendition, as well as all requirements for its valid production and use (specifically any requirements that differ from the general framework presented below).
Each implementation must define a role value that uniquely identifies all conformant collection elements. The role of each collection element in the Package Document must be identified in its role attribute, whose value must be one or more NMTOKENs [XSD-DATATYPES] and/or full IRIs [RFC3987]. The use of NMTOKEN values is reserved for IDPF-defined roles, a registry of which is maintained at http://www.idpf.org/epub/vocab/package/roles . NMTOKEN values not defined in the registry are not valid. No roles are defined in this section.
Third parties may define custom roles for the collection element, but such roles must be identified using full IRIs. Custom roles must not incorporate the string idpf.org in the host component of their identifying IRI.
To facilitate interoperability of custom roles across Reading Systems, implementers are strongly encouraged to document their use of the collection element at http://www.idpf.org/epub/extensions/roles .
The optional metadata element child of collection is an adaptation of the package metadata element, with the following differences in syntax and semantics:
No metadata is required by default.
Package-level restrictions on the use of metadata elements may be overridden.
All primary metadata expressions apply to the collection.
The refines attribute must not reference elements outside the containing collection.
The OPF2 meta element must not be included.
A collection may define sub-collections through the inclusion of one or more child collection elements.
The link element child of collection is an adaptation of the metadata link element, with the following differences in syntax and semantics:
The href attribute may reference any resource, including those listed in the manifest .
The IRI value of the href attribute may have a fragment component to indicate that only a portion or subset of a resource is included in the collection.
The rel attribute is optional.
The refines attribute must not be attached.
Each link must reference a resource that is a member of the group. The order of link elements is not significant.
Specific implementations of the collection element may tailor the requirements defined above to better reflect their needs (e.g., requiring metadata, imposing further restrictions on the use of elements and attributes, or making the order of link elements significant). However, the resulting content model must represent a valid subset of the one defined in this section (e.g., specific implementations cannot introduce new elements or attributes, or re-introduce those expressly forbidden above). Specific implementations must not define collections in a way that overrides the requirements of the manifest and spine .
In the context of this specification, support for collections in Reading Systems is optional. Reading Systems must ignore collection elements that define unrecognized roles.
The rendering of a Rendition must not be dependent on the recognition of collection elements. The content must remain consumable by a User without any information loss or other significant deterioration.
› Examples
The following example shows the assembly of two XHTML Content Documents that represent a single unit.
<package …>
…
<collection role="http://example.org/roles/unit">
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
<dc:title>Foo Bar</dc:title>
</metadata>
<link href="EPUB/xhtml/foo-1.xhtml"/>
<link href="EPUB/xhtml/foo-2.xhtml"/>
</collection>
…
</package>
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4