Ad Hoc Group Draft 20120208
This version: |
http://www.idpf.org/epub/fxl/epub-fxl-20120210.html |
Latest version: |
http://www.idpf.org/epub/fxl/ |
Previous version: | N/A |
Editors: Markus Gylling (IDPF), Dave Cramer (Hachette)
Authors: Takeshi Kanai (Sony), Peter Sorotokin (Adobe), Roger Webster (Barnes & Noble), James Lester (Barnes & Noble), Brady Kroupa (Barnes & Noble), Garth Conboy (Google), Brady Duga (Google), MURATA Makoto (JEPA), Theresa O’Connor (Apple)
Status of this Document
This is an IDPF ad-hoc group draft that has no official status at this time. It may be updated, replaced, or rendered obsolete by other documents at any time. Its publication does not imply endorsement by the IDPF membership or the IDPF EPUB 3 Working Group.
The rendition:render-style property
The rendition:orientation-lock property
Usage of rendition properties in the EPUB 3 Package Document
Specifying name-value pairs on the spine itemref element
Viewport Rendering Instructions
Viewport rendering instructions in XHTML
Viewport rendering instructions in SVG
Appendix C. Note on the use of CSS absolute positioning in EPUB 3
Informative
The default layout principle of EPUB documents is that of reflowability: based primarily on device viewport dimensions, the consuming Reading System reflows the given content within the viewport to maximize utilization of the screen surface area. As for overflow behaviors, Reading Systems often also employ [dynamic pagination] as an alternative to scrolling.
For some document types, referred to in this document as fixed-layout documents, these default layout principles are not applicable.In the context of graphically rich document types such as childrens books and magazines with rich layout, authors need a mechanism to gain explicit control over Reading System reflow and overflow behaviors. In the case of documents that are fully or partially [pre-paginated], authors sometimes also need to express page spread behaviors.
This document, EPUB 3 Fixed-Layout Documents, defines a set of metadata properties to allow declarative expression of intended rendering behaviors of fixed-layout documents in the context of EPUB 3.
[note] EPUB 3 affords three mechanisms for representing fixed-layout content in EPUB 3 documents: as bitmap images, as SVG, and as XHTML that uses CSS absolute positioning. When fixed-layout content is necessary, the author's choice between these representations will depend on many factors including desired degree of precision, file size, accessibility, etc. This document does not attempt to dictate this choice, and a fully-conforming EPUB 3 reading system should support all three of these options.
Name | rendition:render-style[a] |
Description | Specifies whether the given Publication or spine item is reflowable or pre-paginated. |
Value | reflowable | pre-paginated |
Usage | Package Document <meta> element Package Document <itemref> element |
Initial | In <meta>: reflowable In <itemref>: inherited from <meta> |
Cardinality | In <metadata>: zero or one In <itemref>: zero or one |
When the rendition:render-style property is specified on the Package Document <meta> element, it indicates that the paginated or reflowable rendering style (see below) applies globally for the given Publication (i.e. for all spine items).
As ‘reflowable’ is the initial value of this property in the <meta> usage context, this value must be assumed by Reading Systems as the global value if no <meta> element carrying this property is occurs in the Package Document instance.
The rendition:render-style property may also be specified on the Package Document spine <itemref> element, and will in this case override the [global value] for the given spine item. (Refer to [itemref-name-value-pairs] for syntactical rules specific to local specification.)
For any given spine item that has attained a value for the rendition:render-style property either through inheritance from a [global] specification or through a [local] specification, the allowed values have the following meaning:
reflowable
The given spine item is not pre-paginated. Reading Systems may apply dynamic pagination when rendering this spine item.
pre-paginated
The given spine item is pre-paginated. Reading Systems must produce exactly one page when rendering this spine item. (Refer to [viewport meta] for information on viewport size declarations.)
[note] It is common behavior for Reading Systems to restrict or deny the application of User or User Agent stylesheets to pre-paginated documents, since as a result of intrinsic properties of such documents, dynamic style changes are highly likely to have unintended consequences. Authors should take the negative impact on usability and accessibility that these restrictions have into account when choosing to use pre-paginated instead of reflowable content.
Name | rendition:orientation-lock |
Description | Specifies whether the given Publication or spine item is adaptable to multiple orientations |
Value | (landscape | portrait | auto) |
Usage | Package Document <meta> element Package Document <itemref> element |
Initial | In <meta>: auto In <itemref>: inherited from <meta> |
Cardinality | In <metadata>: zero or one In <itemref>: zero or one |
When the rendition:orientation-lock property is specified on the Package Document <meta> element, it indicates that the intended orientation applies globally for the given Publication (i.e. for all spine items).
As ‘auto’ is the initial value of this property in the <meta> usage context, this value must be assumed by Reading Systems as the global value if no <meta> element carrying this property is occurs in the Package Document instance.
The rendition:orientation-lock property may also be specified on the Package Document spine <itemref> element, and will in this case override the [global value] for the given spine item. (Refer to [itemref-name-value-pairs] for syntactical rules.)
For any given spine item that has attained a value for the rendition:orientation-lock property either through inheritance from a [global] specification or through a [local] specification, the allowed values have the following meaning:
landscape
The given spine item is intended for landscape rendering. Reading Systems should disable adaption to other orientations when rendering this item, if multiple orientations are supported.
portrait
The given spine item is intended for portrait rendering. Reading Systems should disable adaption to other orientations when rendering this item, if multiple orientations are supported.
auto
The given spine item is not orientation constrained.
Name | rendition:spread |
Description | Specifies the intended Reading System synthetic spread behavior for this Publication or spine item. |
Value | (none | landscape | portrait | both | auto) |
Usage | Package Document <meta> element Package Document <itemref> element |
Initial | In <meta>: auto In <itemref>: inherited from <meta> |
Cardinality | In <metadata>: zero or one In <itemref>: zero or one |
When the rendition:spread property is specified on the Package Document <meta> element, it indicates that the intended synthetic spread behavior applies globally for the given Publication (i.e. for all spine items).
As ‘auto’ is the initial value of this property in the <meta> usage context, this value must be assumed by Reading Systems as the global value if no <meta> element carrying this property is occurs in the Package Document instance.
The rendition:spread property may also be specified on the Package Document spine <itemref> element, and will in this case override the [global value] for the given spine item. (Refer to [itemref-name-value-pairs] for syntactical rules.)
For any given spine item that has attained a value for the rendition:spread property either through inheritance from a [global] specification or through a [local] specification, the allowed values have the following meaning, where synthetic spread is defined as the rendering of two adjacent pages simultaneously on the device screen.
none
Reading Systems must not incorporate this spine item in a synthetic spread.
landscape
Reading Systems should incorporate this spine item in a synthetic spread only when the device is in landscape orientation.
portrait
Reading Systems should incorporate this spine item in a synthetic spread only when the device is in portrait orientation.
both
Reading Systems should incorporate this spine item in a synthetic spread regardless of device orientation.
auto
No explicit synthetic spread behavior is defined. Reading Systems may use synthetic spreads in specific or all device orientations as part of a viewport utilization optimization process.
When synthetic spreads are used, the size given in [viewport meta] represents the size of one page in the spread.
[note] Refer to[c] [http://idpf.org/epub/30/spec/epub30-publications.html#sec-spine-elem 3.4.12 The spine Element] for information about declaration of global flow directionality using the page-progression-direction attribute.
Names | rendition:page-spread-center and, as defined in [Publications30] page-spread-left page-spread-right |
Description | Specifies the forced placement of a Content Document in a [synthetic spread] |
Usage | Package Document spine <itemref> element |
Cardinality | Zero or one |
When a Reading System is rendering synthetic spreads, the default modus operandi is to populate the spread, which conceptually consists of two adjacent viewports, by rendering the next Content Document in the next available unpopulated viewport, where the location of “next” is determined by the given [http://idpf.org/epub/30/spec/epub30-publications.html#attrdef-spine-page-progression-direction page progression direction]. By providing one of the page-spread-* properties on the spine itemref element, the author can override this automatic population behavior by forcing the given Content Document to be placed in a particular viewport.
The page-spread-left and page-spread-right properties are defined in [Publications30]. This document defines one additional property, rendition:page-spread-center, which indicates that the synthetic spread mode should be overridden such that instead of two adjacent viewports, a single viewport must be used, and positioned at the center of the screen. Note that the presence of rendition:page-spread-center does not in itself affect the [#Viewport Rendering Instructions viewport size].
[note] The page-spread-left, page-spread-right and rendition:page-spread-center properties apply to both pre-paginated and reflowable content, and they only apply when the Reading System is creating synthetic spreads.
When the metadata properties defined in this document are included in an EPUB 3 Package Document, they must be mapped to the URI http://www.idpf.org/vocab/rendition/# using the prefix attribute, as defined in [EPUB Publications 3.0 vocabulary association mechanism epub30-publications.html#sec-metadata-assoc].
<package …
prefix="rendition: http://www.idpf.org/vocab/rendition/#">
…
</package>
Implementors should note that future revisions of [Publications30] may establish the vocabulary represented by the URI http://www.idpf.org/vocab/rendition/# as a [reserved vocabulary epub30-publications.html#sec-metadata-reserved-vocabs]. In this case, the result will be that a) explicit mapping declaration using the prefix attribute will no longer be applicable, and b) the prefix ‘rendition’ will be reserved for this vocabulary. Future revisions of Publications30 may also integrate the properties defined here into the Package Document default vocabulary. In this case the properties defined herein will be allowed to occur in Package Documents without a prefix.
Note that Package Documents may include additional proprietary metadata properties that pertain to layout expressions (refer to [Vocabulary Association Mechanisms http://idpf.org/epub/30/spec/epub30-publications.html#sec-metadata-assoc] for further information on extensibility). Reading Systems must ignore such expressions if they behaviorally conflict with the property semantics defined in this document.
In the context of the properties defined in this document, and when specifying property name-value pairs in the properties attribute on the spine <itemref> element, the following syntax must be used.
The property name and value is concatenated[d] into a single string using a hyphen-minus [e]character (U+002D) as separator. Note that leading and trailing whitespace [DEF] around the separator character is not allowed.
For example, to express that the rendition:render-style property has the value ‘reflowable’ for the given spine item, the string ‘rendition:render-style-reflowable’ is used:
<itemref … properties="rendition:render-style-reflowable" />
This section defines how to express intrinsic dimensionality properties of XHTML and SVG Content Documents [ContentDocs30]. Each XHTML and SVG spine item which has the ‘pre-paginated’ value set for its rendition:render-style property must contain the viewport rendering instructions as defined below.[f]
For both XHTML and SVG Content Documents, the dimension (viewport/viewbox) expressions identified below define the [CSS initial containing block] expressed in CSS Pixels.
Reading Systems must clip XHTML and SVG content to the initial containing block dimensions declared in the viewport meta tag/viewBox attribute, and therefore content positioned outside of the initial containing block is not going to be visible. When the initial containing block aspect ratio does not match the viewport aspect ratio, Reading Systems may position the initial containing block inside the viewport to accommodate the user interface; in other words, added letter-boxing space may appear on either side (or both) of the content.
This document does not define how the initial containing block will be placed within the viewport.
XHTML viewport dimensions are expressed using the viewport meta tag using syntax as per [MetaTags]. In this version of this document, only the width and height expressions are required to be recognized by Reading Systems.
Example
<head>
…
<meta name="viewport" content="width=1200, height=600"/>
…
</head>
SVG viewport dimensions are defined using the [http://www.w3.org/TR/SVG/coords.html#ViewBoxAttribute viewBox attribute].
Example
<svg xmlns="http://www.w3.org/2000/svg"
version="1.1" width="100%" height="100%"
viewBox="0 0 844 1200">
...
</svg>
Fully fixed-layout content, intended to be rendered using synthetic spreads in landscape orientation, and no spreads in portrait orientation.
OPF
<meta property="rendition:render-style">pre-paginated</meta>
<meta property="rendition:spread">landscape</meta>
XHTML
All content documents contain:
<meta name="viewport" content="width=512, height=600"/>
Note: to leave the spread behavior up to the Reading System, the rendition:spread element is either omitted or set to ‘auto’.
Fully fixed-layout content, intended to be rendered without synthetic spreads, and locked to landscape orientation.
OPF
<meta property="rendition:render-style">pre-paginated</meta>
<meta property="rendition:spread">none</meta>
<meta property="rendition:orientation-lock">landscape</meta>
XHTML
All content documents contain:
<meta name="viewport" content="width=1024, height=600"/>
Reflowable content with a single fixed-layout page (title page), where the fixed-layout page is intended for right-hand spread slot if the device renders synthetic spreads.
OPF
<meta property="rendition:render-style">reflowable</meta>
<meta property="rendition:spread">auto</meta>
…
<itemref id="titlepage"
properties="page-spread-right
rendition:render-style-pre-paginated"/>
HTML
The content document representing the title page contains:
<meta name="viewport" content="width=684, height=1024"/>
Note that in this example, both the rendition:render-style and rendition:spread properties are set to their initial values, which means that these two meta elements can be omitted without any impact on the resulting expression.
Fully fixed-layout content where synthetic spreads - if used - must be disabled for a center plate.
OPF
<meta property="rendition:render-style">pre-paginated</meta>
<meta property="rendition:spread">auto</meta>
…
<itemref id="center-plate"
properties="rendition:page-spread-center"/>
HTML
The content document representing the center plate contains:
<meta name="viewport" content="width=1024, height=600"/>
Note that even though the center plate viewport dimension expression indicates landscape orientation, the author has omitted the orientation-lock property, leaving it to the Reading System to decide how to handle the situation. Note also that the rendition:spread=none expression is not needed here, as the rendition:page-spread-center property already specifies semantics that dictates that synthetic spreads be disabled.
Note finally that in this example, the rendition:spread property is set to its initial value, and so it can be omitted without any impact on the resulting expression.
Reflowable content with a fixed-layout two-page center plate that is intended to be rendered using synthetic spreads in any device orientation. The author has left spread behavior for the other (reflowable) parts of the publication undefined, since the global value of rendition:spread is initialized to ‘auto’.
OPF
<spine page-progression-direction=”ltr”>
…
<itemref id="center-plate-left"
properties="rendition:spread-both
page-spread-left"/>
<itemref id="center-plate-right"
properties="rendition:spread-both
page-spread-right"/>
…
</spine>
HTML
The two content documents representing the center plate contains:
<meta name="viewport" content="width=512, height=600"/>
Fully fixed-layout content which includes three separate stylesheets used for three different device categories, using [MediaQueries].
OPF
<meta property="rendition:render-style">pre-paginated</meta>
HTML
<link rel="stylesheet" href="eink-style.css" media="(max-monochrome: 3)" />
<link rel="stylesheet" href="skinnytablet-style.css" media="((color) and (max-height:600px) and (orientation:landscape), (color) and (max-width:600px) and (orientation:portrait))" />
<link rel="stylesheet" href="fattablet-style.css" media="((color) and (min-height:601px) and (orientation:landscape), (color) and (min-width:601px) and (orientation:portrait)" />
The tables below describe how the vocabulary defined in this document maps to some of the pre-existing proprietary metadata vocabularies for fixed-layout expressions.
Amazon Property | IDPF Equivalent (prefixes omitted for clarity) |
fixed-layout (true | false) | render-style (reflowable | pre-paginated) |
original-resolution (width, ‘x’, height) | viewport [in HTML meta] |
orientation-lock (portrait | landscape) | orientation-lock (portrait | landscape | auto) |
book-type (children | comic) | not applicable |
RegionMagnification (true | false) | not applicable, proprietary |
Note that the Sony metadata properties are defined for single renditions only, and are not used for rendition selection.
Sony Property | IDPF Equivalent (prefixes omitted for clarity) |
fixed-layout (true | false) | render-style (reflowable | pre-paginated) |
orientation (portrait | landscape | auto) | orientation-lock (portrait | landscape | auto) |
page-spread (full | double | auto) | rendition:spread (none | portrait | landscape | both | auto) |
overflow-scroll (true | false) | defined in CSS |
viewport | viewport [in HTML meta] |
Note that for page-spread, the values for portrait and both would all map to double, landscape would map to auto, and none would map to full.
Apple currently stores some of this metadata in an XML file in META-INF.
Apple Property | IDPF Equivalent (prefixes omitted for clarity) |
fixed-layout (true | false) | render-style (reflowable | pre-paginated) |
viewport [in HTML meta] | viewport [in HTML meta] |
orientation-lock (landscape-only | portrait-only | none) | orientation-lock (landscape | portrait | auto) |
platform name | use rendition:media to target a rendition to a specific device |
open-to-spread (true | false) | no equivalent |
An informative note at the end of [Section 3.3.1 ("CSS 2.1") of EPUB 3 Content Documents] has been a source of some confusion relative to fixed layout and EPUB 3. This appendix intends to clarify that note until the concerned specification is updated accordingly.
The note states: "The ability of Reading Systems to paginate absolutely positioned layouts is not guaranteed, so reliance on absolute positioning is discouraged. Reading Systems might not support these property values.".
First, given its location in the CSS section of the specification, it should be noted that this statement is only applicable to fixed-layout documents that utilize CSS. Second, this note does not imply that the "absolute" value of the position property is not in the EPUB 3 CSS profile; "position:absolute" is in fact part of the profile, since it is part of its baseline (CSS 2.1). Only the "fixed" value is excluded from the EPUB 3 CSS Profile (as stated in normative prose above the note).
Lastly, this note does not discourage use of CSS for absolutely positioned layouts but only reliance on such for content expected to be delivered to arbitrary Reading Systems, which as stated may not support these values. In particular, EPUB 2.x Reading Systems will likely not support these values, as they were not included in the EPUB 2 CSS Profile. Many uses of absolutely-positioned CSS will gracefully degrade if these property values are ignored, and such graceful degradation behavior (non-reliance) is encouraged.
[ContentDocs30]
[MediaQueries]
Media Queries
[MetaTags]
Supported Meta Tags (informative)
[OCF3]
[Publications30]
[a]markus.gylling:
Could perhaps be named "rendition:layout" instead.
[b]markus.gylling:
Need to be more clear on how draconian RS behaviors are expected to be re "locking". One plausible approach might be to express this more clearly as "author intent", and let the RS (possibly in dialog with the user in addition to the UX department) decide whether to slavishly follow it or not. This would likely entail removing "-lock" from the name as well.
[c]markus.gylling:
From Murata: [...] the spread issue needs more careful wording since the ppd property may be overridden by the writing mode of the content document. [...] why don't we simply mention both? For two consecutive pages from a single content doc, the writing mode wins. For two pages from different content docs, the ppd property wins.
[d]markus.gylling:
An alternative and less experimental approach to using concatenation in itemref/@properties is to use meta/@refines.
[e]markus.gylling:
Using equals sign instead of hyphen would make sense here, but using hyphen gives syntax harmony with pre-existing props, e.g. the EPUB3-defined page-spread-right, (which really is saying page-spread=right)
[f]markus.gylling:
TODO Is it a "must not" for the inverse case?