1 Overview

1.1 Purpose and Scope

This section is informative

This vocabulary, a part of EPUB® 3, defines a set of properties for describing various features of the Package Document [Packages31].

The properties in this vocabulary are usable in the various Package Document attributes that accept the property datatype [Packages31], and are grouped by the element and attribute that they can be used in.

This vocabulary is a companion to the [Packages31] specification and is intended to be read in conjunction with that document.

1.2 Referencing

Properties without a prefix are referenceable using the base IRI http://idpf.org/epub/vocab/package/#.

Properties with the "rendition:" prefix are referenceable using the base IRI http://www.idpf.org/vocab/rendition/#.

The "rendition:" prefix is reserved for use [Packages31] and does not have to be declared in the Package Document.

1.3 Terminology

Terms with meanings specific to EPUB 3.1 are capitalized in this document (e.g., "Author", "Reading System"). A complete list of these terms and definitions is provided in [EPUB31].

Only the first instance of a term in a section is linked to its definition.

1.4 Conformance Statements

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.

2 Metadata `meta` Properties

2.1 rendition:flow

Name:	rendition:flow
Description:	Specifies the Author preference for how Reading Systems should handle content overflow.
Allowed value(s):	`paginated` \| `scrolled-continuous` \| `scrolled-doc` \| `auto` The default value is `auto`
Cardinality:	`Zero or one`
Extends:	Sets the global value for the given Rendition.
Example:	`<meta property="rendition:flow">scrolled-doc</meta>`

2.2 rendition:layout

Name:	rendition:layout
Description:	Specifies whether the given Rendition is reflowable or pre-paginated.
Allowed value(s):	`reflowable` \| `pre-paginated` The default value is `reflowable`
Cardinality:	`Zero or one`
Extends:	Sets the global value for the given Rendition.
Example:	`<meta property="rendition:layout">pre-paginated</meta>`

2.3 rendition:orientation

Name:	rendition:orientation
Description:	Specifies which orientation the Author intends the given Rendition to be rendered in.
Allowed value(s):	`landscape` \| `portrait` \| `auto` The default value is `auto`
Cardinality:	`Zero or one`
Extends:	Sets the global value for the given Rendition.
Example:	`<meta property="rendition:orientation">landscape</meta>`

2.4 rendition:spread

Name:	rendition:spread
Description:	Specifies the intended Reading System synthetic spread behavior for the given Rendition.
Allowed value(s):	`none` \| `landscape` \| `portrait` \| `both` \| `auto` The default value is `auto`
Cardinality:	`Zero or one`
Extends:	Sets the global value for the given Rendition.
Example:	`<meta property="rendition:spread">both</meta>`

2.5 rendition:viewport

Name:	rendition:viewport
Description:	Specifies the CSS initial containing block [CSS2.1] dimensions for pre-paginated [Packages31] XHTML and SVG Content Documents.
Required value:	`width=x, height=y`
Cardinality:	`Zero or one`
Extends:	Sets the global value for the given Rendition.
Example:	`<meta property="rendition:viewport">width=1200, height=800</meta>`

3 Manifest `item` Properties

The following tables define properties for use in the manifest item element [Packages31] properties attribute [Packages31].

The Applies to field indicates which Publication Resource type(s) the given property may be specified on, the Cardinality field indicates the number of times the property must appear within the Package Document scope, and the Usage field indicates usage conditions.

3.1 cover-image

Name:	cover-image
Description:	The cover-image property identifies the described Publication Resource as the cover image for the Publication.
Applies to:	All raster and vector image types [EPUB31]
Cardinality:	`Zero or one`
Usage:	Optional.

3.2 mathml

Name:	mathml
Description:	The mathml property indicates that the described Publication Resource contains one or more instances of MathML markup.
Applies to:	EPUB Content Documents
Cardinality:	`Zero or more`
Usage:	Must be set if and only if the criterion specified in the description is met.

3.3 nav

Name:	nav
Description:	The nav property indicates that the described Publication Resource constitutes the EPUB Navigation Document of the given Rendition.
Applies to:	The EPUB Navigation Document
Cardinality:	`Exactly one`
Usage:	Required.

3.4 remote-resources

Name:	remote-resources
Description:	The remote-resources property indicates that the described Publication Resource contains one or more internal references to other Publication Resources that are located outside of the EPUB Container. Refer to Publication Resource Locations [EPUB31] for more information.
Applies to:	All Publication Resources with the capability of internal referencing (e.g., HTML Content Documents, SVG Content Documents, CSS Style Sheets and Media Overlay Documents).
Cardinality:	`Zero or more`
Usage:	Must be set if and only if the criterion specified in the description is met.

3.5 scripted

Name:	scripted
Description:	The scripted property indicates that the described Publication Resource is a Scripted Content Document (i.e., contains scripted content and/or elements from HTML5 forms).
Applies to:	EPUB Content Documents
Cardinality:	`Zero or more`
Usage:	Must be set if and only if the criterion specified in the description is met.

3.6 svg

Name:	svg
Description:	The svg property indicates that the described Publication Resource embeds one or more instances of SVG markup. This property must be set when SVG markup is included directly in the resource and may be set when the SVG is referenced from the resource (e.g., from an [HTML5] `img`, `object` or `iframe` element).
Applies to:	HTML Content Documents; the value is implied for SVG Content Documents.
Cardinality:	`Zero or more`
Usage:	Must be set if and only if the criterion specified in the description is met.

3.7 Usage

The mathml, remote-resources, scripted and switch properties must be specified whenever the resource referenced by an item matches their respective definitions. These properties do not apply recursively to content included into a resource (e.g., via the HTML5 iframe element). For example, if a non-scripted HTML Content Document embeds a scripted Content Document, only the embedded document's manifest item properties attribute will have the scripted value.

3.8 Examples

The following example shows a manifest item element [Packages31] that represents the EPUB Navigation Document.

<item properties="nav" id="c1" href="c1.xhtml" media-type="application/xhtml+xml" />

The following example shows a manifest item element that represents the cover image.

<item properties="cover-image" id="ci" href="cover.svg" media-type="image/svg+xml" />

The following example shows a manifest item element representing a Scripted Content Document that also contains embedded MathML.

<item properties="scripted mathml" id="c2" href="c2.xhtml" media-type="application/xhtml+xml" />

4 Spine `itemref` Properties

The following tables define properties for use in the itemref element [Packages31] properties attribute [Packages31].

The Cardinality field indicates the number of times the property must appear within the Package Document scope, and the Usage field indicates usage conditions.

4.1 rendition:align-x-center

Name:	rendition:align-x-center
Description:	Specifies that the given spine item should be centered horizontally in the viewport or spread.
Cardinality:	`Zero or more`
Usage:	Optional.

4.2 rendition:flow-auto

Name:	rendition:flow-auto
Description:	Indicates no preference for overflow content handling by the Author.
Cardinality:	`Zero or more`
Usage:	Optional. This property must not be specified on an `itemref` that also specifies the rendition:flow-paginated, rendition:flow-scrolled-continuous or rendition:flow-scrolled-doc properties.

4.3 rendition:flow-paginated

Name:	rendition:flow-paginated
Description:	Indicates the Author preference is to dynamically paginate content overflow.
Cardinality:	`Zero or more`
Usage:	Optional. This property must not be specified on an `itemref` that also specifies the rendition:flow-auto, rendition:flow-scrolled-continuous or rendition:flow-scrolled properties.

4.4 rendition:flow-continuous

Name:	rendition:flow-scrolled-continuous
Description:	Indicates the Author preference is to provide a scrolled view for overflow content, and that consecutive spine items with this property are to be rendered as a continuous scroll. The scroll direction is defined relative to the block flow direction [CSS3WritingModes] of the root element of the HTML Content Document referenced by the itemref element [Packages31]. The scroll direction is vertical if the block flow direction is downward (top-to-bottom). It is horizontal if the block flow direction of the root element is rightward (left-to-right) or leftward (right-to-left).
Cardinality:	`Zero or more`
Usage:	Optional. This property must not be specified on an `itemref` that also specifies the rendition:flow-auto, rendition:flow-scrolled-doc or rendition:flow-paginated properties.

4.5 rendition:flow-scrolled-doc

Name:	rendition:flow-scrolled-doc
Description:	Indicates the Author preference is to provide a scrolled view for overflow content, and each spine item with this property is to be rendered as separate scrollable document.
Cardinality:	`Zero or more`
Usage:	Optional. This property must not be specified on an `itemref` that also specifies the rendition:flow-auto, rendition:flow-scrolled-continuous or rendition:flow-paginated properties.

4.6 rendition:layout-pre-paginated

Name:	rendition:layout-pre-paginated
Description:	Specifies that the given spine item is pre-paginated.
Cardinality:	`Zero or more`
Usage:	Optional. This property must not be specified on an `itemref` that also specifies the rendition:layout-reflowable property.

4.7 rendition:layout-reflowable

Name:	rendition:layout-reflowable
Description:	Specifies that the given spine item is reflowable.
Cardinality:	`Zero or more`
Usage:	Optional. This property must not be specified on an `itemref` that also specifies the rendition:layout-pre-paginated property.

4.8 rendition:orientation-auto

Name:	rendition:orientation-auto
Description:	Specifies that the Reading System can determine the orientation to rendered the spine item in.
Cardinality:	`Zero or more`
Usage:	Optional. This property must not be specified on an `itemref` that also specifies the rendition:orientation-landscape or rendition:orientation-portrait property.

4.9 rendition:orientation-landscape

Name:	rendition:orientation-landscape
Description:	Specifies that the given spine item is to be rendered in landscape orientation.
Cardinality:	`Zero or more`
Usage:	Optional. This property must not be specified on an `itemref` that also specifies the rendition:orientation-portrait or rendition:orientation-auto property.

4.10 rendition:orientation-portrait

Name:	rendition:orientation-portrait
Description:	Specifies that the given spine item is to be rendered in portrait orientation.
Cardinality:	`Zero or more`
Usage:	Optional. This property must not be specified on an `itemref` that also specifies the rendition:orientation-landscape or rendition:orientation-auto property.

4.11 rendition:page-spread-center

Name:	rendition:page-spread-center
Description:	Specifies the forced placement of a Content Document in a Synthetic Spread
Cardinality:	`Zero or more`
Usage:	Optional. This property must not be specified on an `itemref` that also specifies the page-spread-right or page-spread-left properties.

4.12 page-spread-left

Name:	page-spread-left
Description:	The page-spread-left property indicates that the first page of the associated `item` element's EPUB Content Document represents the left-hand side of a two-page spread.
Cardinality:	`Zero or more`
Usage:	Optional. This property must not be specified on an `itemref` that also specifies the page-spread-right or rendition:page-spread-center properties.

4.13 page-spread-right

Name:	page-spread-right
Description:	The page-spread-right property indicates that the first page of the associated `item` element's EPUB Content Document represents the right-hand side of a two-page spread.
Cardinality:	`Zero or more`
Usage:	Optional. This property must not be specified on an `itemref` that also specifies the page-spread-left or rendition:page-spread-center properties.

4.14 rendition:spread-auto

Name:	rendition:spread-auto
Description:	Specifies the Reading System can determine when to render a synthetic spread for the spine item.
Cardinality:	`Zero or more`
Usage:	Optional. This property must not be specified on an `itemref` that also specifies the rendition:spread-portrait, rendition:spread-landscape, rendition:spread-both or rendition:spread-none property.

4.15 rendition:spread-both

Name:	rendition:spread-both
Description:	Specifies the Reading System should render a synthetic spread for the spine item in both portrait and landscape orientations.
Cardinality:	`Zero or more`
Usage:	Optional. This property must not be specified on an `itemref` that also specifies the rendition:spread-portrait, rendition:spread-landscape, rendition:spread-auto or rendition:spread-none property.

4.16 rendition:spread-landscape

Name:	rendition:spread-landscape
Description:	Specifies the Reading System should render a synthetic spread for the spine item only when in landscape orientation.
Cardinality:	`Zero or more`
Usage:	Optional. This property must not be specified on an `itemref` that also specifies the rendition:spread-portrait, rendition:spread-both, rendition:spread-auto or rendition:spread-none property.

4.17 rendition:spread-none

Name:	rendition:spread-none
Description:	Specifies the Reading System should not render a synthetic spread for the spine item.
Cardinality:	`Zero or more`
Usage:	Optional. This property must not be specified on an `itemref` that also specifies the rendition:spread-portrait, rendition:spread-landscape, rendition:spread-both or rendition:spread-auto property.

4.18 rendition:spread-portrait

Name:	rendition:spread-portrait
Description:	Specifies the Reading System should render a synthetic spread for the spine item only when in portrait orientation.
Cardinality:	`Zero or more`
Usage:	Optional. This property must not be specified on an `itemref` that also specifies the rendition:spread-landscape, rendition:spread-both, rendition:spread-auto or rendition:spread-none property.

4.19 Examples

The following example shows how a two-page spread of a map might be indicated in the spine.

<spine>
	<itemref idref="title"/>
	<itemref idref="ps-1-l" properties="page-spread-left"/>
	<itemref idref="ps-1-r" properties="page-spread-right"/>
	<itemref idref="toc"/>
	…
</spine>