Proposed Specification 23 May 2011
A diff of changes from the previous Working Draft is available at this link.
Copyright © 2010, 2011 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.
Table of Contents
This section is informative
This specification, EPUB Content Documents 3.0, defines profiles of HTML5, SVG, and CSS for use in the context of EPUB® Publications.
This specification is one of a family of related specifications that compose EPUB 3, the third major revision of an interchange and delivery format for digital publications based on XML and Web Standards. It is meant to be read and understood in concert with the other specifications that make up EPUB 3:
The EPUB 3 Overview [EPUB3Overview], which should be read first, provides an informative overview of EPUB and a roadmap to the rest of the EPUB 3 documents.
EPUB Publications 3.0 [Publications30], which defines publication-level semantics and overarching conformance requirements for EPUB Publications.
EPUB Open Container Format (OCF) 3.0 [OCF3], which defines a file format and processing model for encapsulating a set of related resources into a single-file (ZIP) EPUB Container.
EPUB Media Overlays 3.0 [MediaOverlays30], which defines a format and a processing model for synchronization of text and audio.
This specification supersedes Open Publication Structure (OPS) 2.0.1 [OPS2]. Refer to [EPUB3Changes] for information on differences between this specification and its predecessor.
This section is informative
The XHTML document type defined by this specification is based on W3C [HTML5], and inherits all definitions of semantics, structure and processing behaviors from the HTML5 specification unless otherwise specified.
In addition, this specification defines a set of extensions to the W3C HTML5 document model that Authors may include in XHTML Content Documents.
This specification defines a simplified processing model that does not require Reading Systems to support scripting, HTML5 forms or the HTML5 DOM. EPUB Reading Systems conformant with this specification are only required to be able to process a conforming EPUB Content Document. As support for scripting and HTML5 forms are optional Reading System features, a conformant Reading System may not be a fully-conformant HTML5 User Agent (i.e., it may not implement the complete HTML5 processing model).
This specification defines a restricted subset of SVG 1.1 to represent vector graphics inline in XHTML Content Documents and as standalone SVG Content Documents.
The CSS profile defined in this specification has CSS 2.1 [CSS2.1] as its baseline. Any CSS Style Sheet that conforms to CSS 2.1 may be used in the context of an EPUB Publication, except as noted in CSS 2.1.
This specification also incorporates features defined by CSS3 Modules and introduces EPUB-specific CSS constructs.
EPUB 3 references W3C specifications that are not yet final, and incompatible changes to them may occur in the future that would cause EPUB 3 Content Documents that were previously conformant to no longer be conformant to the latest versions of the referenced specifications.
The IDPF anticipates revising the EPUB 3 specifications if and when such incompatible changes occur, updating the normative constraints defined herein as necessary and incrementing the minor version number of EPUB 3 (e.g., publishing an EPUB 3.0.n).
A logical document entity consisting of a set of interrelated resources and packaged in an EPUB Container, as defined by this specification and its sibling specifications.
A resource that contains content or instructions that contribute to the logic and rendering of the EPUB Publication. In the absence of this resource, the Publication may not render as intended by the Author. Examples of Publication Resources include the Package Document, EPUB Content Documents, EPUB Style Sheets, audio, video, images, embedded fonts and scripts.
With the exception of the Package Document itself, Publication Resources must be listed in the manifest [Publications30] and must be bundled in the EPUB container file unless specified otherwise in manifest [Publications30].
Examples of resources that are not Publication Resources include those identified by the Package Document manifest [Publications30] element and third-party resources identified by outbound hyperlinks (e.g., identified in [HTML5] a element href attributes).
A Publication Resource that is a Core Media Type and may therefore be included in the EPUB Publication without the provision of fallbacks [Publications30].
A Publication Resource that conforms to one of the EPUB Content Document definitions (XHTML or SVG).
An EPUB Content Document is a Core Media Type, and may therefore be included in the EPUB Publication without the provision of fallbacks [Publications30].
An EPUB Content Document conforming to the profile of [HTML5] defined in XHTML Content Documents.
XHTML Content Documents use the XHTML syntax of [HTML5].
An EPUB Content Document conforming to the constraints expressed in SVG Content Documents.
A specialization of the XHTML Content Document, containing human- and machine-readable global navigation information, conforming to the constraints expressed in EPUB Navigation Documents.
An EPUB Content Document that includes scripting or an XHTML Content Document that contains HTML5 forms elements.
Refer to Scripted Content Documents for more information.
An EPUB Content Document referenced directly from the spine
A set of Publication Resource types for which no fallback is required. Refer to Publication Resources [Publications30] for more information.
A Publication Resource carrying bibliographical and structural metadata about the EPUB Publication, as defined in Package Documents [Publications30].
A list of all Publication Resources that constitute the EPUB Publication.
Refer to manifest [Publications30] for more information.
An ordered list of Publication Resources, typically EPUB Content Documents, representing the default reading order of the Publication.
Refer to spine [Publications30] for more information.
The rendering of the textual content of an EPUB Publication as artificial human speech using a synthesized voice.
A CSS Style Sheet conforming to the CSS profile defined in EPUB Style Sheets.
The region of an EPUB Reading System in which the content of an EPUB Publication is rendered visually to a User.
A Viewport capable of displaying CSS-styled content.
A Viewport capable of displaying SVG images.
The ZIP-based packaging and distribution format for EPUB Publications defined in [OCF3].
The person(s) or organization responsible for the creation of an EPUB Publication, which may or may not be the creator of the content and resources it contains.
An individual that consumes an EPUB Publication using an EPUB Reading System.
A system that processes EPUB Publications for presentation to a User in a manner conformant with this specification and its sibling specifications.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "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.
For convenience, the following namespace prefix mappings [XMLNS] are used throughout this specification:
| prefix | namespace URI |
|---|---|
epub | http://www.idpf.org/2007/ops |
m | http://www.w3.org/1998/Math/MathML |
pls | http://www.w3.org/2005/01/pronunciation-lexicon |
ssml | http://www.w3.org/2001/10/synthesis |
svg | http://www.w3.org/2000/svg |
This section defines a profile of [HTML5] for creating XHTML Content Documents. An instance of an XML document that conforms to this profile is a Core Media Type and is referred to in this specification and its sibling specifications as an XHTML Content Document.
Unless otherwise specified, this specification inherits all definitions of semantics, structure and processing behaviors from the [HTML5] specification.
The EPUB 3 XHTML Content Document definition references features in the W3C [HTML5] specification that are still works in progress and may change in incompatible ways. When utilizing such features, authors should consider the inherent risks in terms of the potential impact on interoperability and document longevity.
An XHTML Content Document must meet all of the following criteria:
› It must meet the conformance constraints for XML documents defined in XML Conformance [Publications30].
› It must use the XHTML syntax [HTML5].
› It must be valid to the XHTML Content Document schema as defined in XHTML Content Document Schema.
› For all document constructs used that are defined by [HTML5], it must conform to the conformance criteria defined for those constructs in that specification, unless explicitly overridden in HTML5 Deviations and Constraints.
› It must conform to all content conformance constraints defined in HTML5 Extensions and Enhancements.
› The XHTML Content Document filename should use the file extension .xhtml.
All Publication Resources referenced from an XHTML Content Document must conform to the constraints for Publication Resources defined in EPUB Publication — Content Conformance [Publications30]
A conformant EPUB Reading System must meet all of the following criteria for processing XHTML Content Documents:
› Unless explicitly defined by this specification or its sibling specifications as overridden, it must process XHTML Content Documents using semantics defined by the [HTML5] specification, and honor any applicable User Agent conformance constraints expressed therein.
› It must meet all Reading System conformance criteria defined in HTML5 Extensions and Enhancements.
› It must recognize and adapt behaviorally to the constraints defined in HTML5 Deviations and Constraints.
› It must meet the Reading System conformance criteria defined in Scripted Content Documents — Reading System Conformance.
› It must support visual rendering of XHTML Content Documents as defined in EPUB Style Sheets — Reading System Conformance.
› It should recognize embedded ARIA markup and support exposure of any given ARIA roles, states and properties to platform accessibility APIs [WAI-ARIA].
This section defines EPUB 3 XHTML Content Document extensions to the underlying [HTML5] document model.
This section is informative
Semantic inflection is the process of attaching additional meaning about the specific purpose and/or nature that an element plays in an XHTML Content Document. In the context of EPUB Publications, such inflection typically pertains to domain-specific semantics that are not covered by the underlying host language ([HTML5]) vocabulary.
Semantic metadata is not intended for human consumption; it instead provides a controlled way for Reading Systems and other User Agents to learn more about the structure and content of a document, providing them the opportunity to enhance the reading experience for Users.
This specification defines a method for semantic inflection using the attribute axis: instead of adding new XML elements to the XHTML Content Document vocabulary as needed, a fixed set of attributes are used to inflect the desired semantics. A mechanism to identify external vocabularies that provide controlled values for the attributes is also defined.
epub:type AttributeThe epub:type attribute inflects semantics on the element on which it appears. Its value is one or more space-separated terms stemming from external vocabularies associated with the document instance, as defined in Vocabulary Association.
The inflected semantic must express a subclass of the semantic of the carrying element. Note that Reading Systems are required to ignore inflected semantics that conflict with the carrying element.
The epub:type attribute is intended to be functionally equivalent to the W3C Role Attribute [Role], but with restrictions as specified in Vocabulary Association.
type
http://www.idpf.org/2007/ops
May be specified on all elements.
A space-separated list of CURIEs [RDFa11 Core], with restrictions as defined in Vocabulary Association.
This specification uses a subset of the vocabulary association mechanism defined in RDFa 1.1 Core [RDFa11 Core]. The profile and prefix attributes of RDFa 1.1 Core are allowed on the root element of XHTML Content Documents, and are used as follows:
profile attribute [conditionally required]Specifies the URI [RFC3986] of the vocabulary profile for EPUB Content Documents.
This attribute is optional except when the epub:type attribute is used in an XHTML Content Document, in which case its use is required.
This version of the specification requires the attribute have the value http://www.idpf.org/epub/30/profile/content/ [ContentProfile]
prefix attribute [optional]Declares additional vocabulary prefix mappings beyond those declared in the profile, using the syntax defined in [RDFa11 Core].
The prefix attribute must not redeclare a prefix that has already been defined through the metadata profile. Similarly, the XML Namespaces [XMLNS] method of defining namespace prefixes using the xmlns pseudo-attribute must not be used to define vocabulary prefixes.
Besides reserving prefixes for a set of well-known vocabularies, the vocabulary profile for EPUB Content Documents also reserves the EPUB 3 Structural Semantics Vocabulary [StructureVocab] as the default vocabulary for all XHTML Content Documents. The terms defined in this vocabulary are used without prefixes in the epub:type attribute of XHTML Content Documents.
Examples
The following example shows the epub:type attribute used to inflect footnote and note reference semantics. The properties used are defined in the default vocabulary.
<html … profile="http://www.idpf.org/epub/30/profile/content/">
…
<p> … <a epub:type="noteref" href="n1">1</a> … </p>
…
<aside epub:type="footnote" id="n1">
…
</aside>
…
</html> The following example shows the epub:type attribute used to inflect glossary semantics on an HTML5 definition list. The property used is defined in the default vocabulary.
<html … profile="http://www.idpf.org/epub/30/profile/content/">
…
<dl epub:type="glossary">
…
</dl>
…
</html> The following example shows the epub:type attribute used to inflect source publication pagebreak semantics. The property used is defined in the default vocabulary. (Note that the source-identifier [Publications30] property provides a means of identifying the source publication to which the given pagination information applies.)
<html … profile="http://www.idpf.org/epub/30/profile/content/"> … <p> … <span epub:type="pagebreak" title="234"/> … </p> … </html>
Reading Systems must process the epub:type as follows:
› A Reading System may associate specialized behaviors with none, some or all of the terms defined in the default vocabulary.
› A Reading System may also associate specialized behaviors with terms given in vocabularies other than the default one.
› A Reading System must ignore terms that it does not recognize.
› When Reading System behavior associated with a given epub:type value conflicts with behavior associated with the carrying element, then the behavior associated with the element must be given precedence.
The W3C Speech Synthesis Markup Language [SSML] is a language used for assisting Text-to-Speech (TTS) engines in generating synthetic speech. While SSML is a language designed as a standalone document type, it also defines semantics suitable for use within other host languages.
This specification recasts the SSML 1.1 phoneme element as two attributes (ssml:ph and ssml:alphabet), and makes them available within EPUB XHTML Content Documents.
Reading Systems with Text-to-Speech (TTS) capabilities should support the SSML Attributes as defined below.
For more information on EPUB 3 features related to synthetic speech, refer to Text-to-speech [EPUB3Overview].
ssml:ph attributeThe ssml:ph attribute specifies a phonemic/phonetic pronunciation of the text represented by the element onto which the attribute appears.
ph
http://www.w3.org/2001/10/synthesis
May be specified on all elements with which a phonetic equivalent can logically be associated (e.g., elements that contain textual information), but must not be specified on a descendant of an element that already carries this attribute.
A phonemic/phonetic expression, syntactically valid with respect to the phonemic/phonetic alphabet being used.
This attribute inherits all the semantics of the SSML 1.1 [SSML] phoneme element's ph attribute, with the following addition:
› When the ssml:ph attribute appears on an element that has text node descendants, the corresponding document text to which the pronunciation applies is the string that results from concatenating the descendant text nodes, in document order. The specified phonetic pronunciation must therefore logically match the element's textual data in its entirety (i.e., not just an isolated part of its content).
Reading Systems that support the SSML Attributes and PLS Documents must honor the defined precedence rules for these two constructs.
ssml:alphabet attributeThe ssml:alphabet attribute specifies which phonemic/phonetic pronunciation alphabet is used in the value of the ssml:ph attribute.
alphabet
http://www.w3.org/2001/10/synthesis
Global, may be specified on any element.
The name of the pronunciation alphabet used in the value of ssml:ph (inherited).
This attribute inherits all the semantics of the SSML 1.1 [SSML] phoneme element's alphabet attribute, with the following addition:
› The value of the ssml:alphabet attribute is inherited in the document tree. The pronunciation alphabet used in a given ssml:ph attribute value is determined by locating the first occurrence of the ssml:alphabet attribute starting with the element on which the ssml:ph attribute appears, followed by the nearest ancestor element.
Reading Systems that support the SSML Attributes feature of this specification should support the ipa alphabet.
This section is informative
The switch element provides a simple mechanism through which Authors can tailor the Publication content displayed to Users, one that isn't dependent on the scripting capabilities of the Reading System.
Reading System developers may choose to support XML vocabularies and new HTML elements that are not valid in XHTML Content Documents. The switch mechanism encourages this type of development and experimentation, but at the same time provides Authors who wish to take advantage of it the security of knowing that their content will still display on any compliant Reading System (i.e., it maintains the baseline requirement that all XHTML Content Documents be valid if none of the specialized markup is supported).
Content switching is not just about encouraging future development, however; it can also be used to create Publications that maintain a level of compatibility with older Reading Systems unable to handle the new features of EPUB 3. For example, instances of MathML, now a native type, could be added using switch elements so that EPUB 2 Reading Systems could instead provide fallback images or text.
epub:switch ElementThe switch element allows an XML fragment to be conditionally inserted into the content model of an XHTML Content Document.
A Reading System must individually process each switch element in a document to determine whether it can render any of the child case elements (as determined by the value of their required-namespace attributes).
For each switch encountered, the Reading System should render the content of the first case it supports, but is free to select from any of the available options. If the Reading System does not support the markup contained in any of the child case elements, it must render the contents of the default element.
The [HTML5] object element should be used to embed custom (non-core) content types in XHTML Content Documents. Custom markup should be wrapped only in a switch element when the content it represents is an integral part of the document and depends on the context of the document to be properly processed.
Examples
An example of ChemML markup inserted using the switch element.
<epub:switch id="cmlSwitch">
<epub:case required-namespace="http://www.xml-cml.org/schema">
<cml xmlns="http://www.xml-cml.org/schema">
<molecule id="sulfuric-acid">
<formula id="f1" concise="H 2 S 1 O 4"/>
</molecule>
</cml>
</epub:case>
<epub:default>
<p>H<sub>2</sub>SO<sub>4</sub></p>
</epub:default>
</epub:switch>
An example of adding MathML markup for compliance with EPUB 2 Reading Systems.
<epub:switch id="mathmlSwitch">
<epub:case required-namespace="http://www.w3.org/1998/Math/MathML">
<math xmlns="http://www.w3.org/1998/Math/MathML">
<mrow>
<mn>2</mn>
<mo> ⁡<!--INVISIBLE TIMES--></mo>
<mi>x</mi>
</mrow>
<mrow>
<mo>+</mo>
<mi>y</mi>
<mo>-</mo>
<mi>z</mi>
</mrow>
</math>
</epub:case>
<epub:default>
<p>2x + y - z</p>
</epub:default>
</epub:switch>
epub:case ElementThe case element contains markup from XML vocabularies that may or may not be natively supported in XHTML Content Documents.
case
http://www.idpf.org/2007/ops
Required first child of switch. Repeatable.
id [optional] The ID [XML] of this element, which must be unique within the document scope.
required-namespace [required] An extension identifier in URI form [RFC2046] that identifies the XML vocabulary or extension that the Reading System must support in order to process the content of the case element.
An XML fragment conforming to the markup vocabulary identified in the required-namespace attribute.
Each case element must contain an alternate representation of the same content. To ensure the best rendering of their content, Authors should order case elements by to their optimal rendering format.
If the case element contains markup that is valid in an XHTML Content Document (e.g., MathML), that content must be valid at the point where the switch element has been inserted (i.e., its addition must not result in an invalid document).
Foreign markup in a case element must be well formed, but does not have to be valid at its point of insertion. Authors should ensure that any foreign markup matches the context in which it is used (e.g., a block element should not be included in a switch element inserted in an inline context).
The IDPF maintains an informative registry of well-known extension identifiers for use in the required-namespace attribute at http://www.idpf.org/epub/switch/.
epub:default ElementThe default element provides markup that is valid in any XHTML Content Document for when a Reading System cannot render any of the case elements.
default
http://www.idpf.org/2007/ops
Required last child of epub:switch.
id [optional] The ID [XML] of this element, which must be unique within the document scope.
An [HTML5]-compliant markup fragment.
The default element acts as a fallback for the switch and must include a representation of the content that is valid in XHTML Content Documents.
The default element must not include content that would invalidate the document at the point where the switch has been inserted: XHTML Content Documents must be valid if all the switch elements are replaced by their child default elements.
EPUB Reading Systems must support the switch element.
This specification does not require a specific rendering approach for switch elements. A Reading Systems may choose to apply CSS styling to render each switch, for example, but may use any other approach as appropriate. All Reading Systems must present the content of only one case element or the default element per switch for rendering, however.
The switch element must be processed as though all of its children but one have the HTML5 hidden attribute set (i.e., all the same processing rules and requirements outlined for that attribute should be applied to the content not to be rendered).
As the content that may be rendered depends on the capabilities of the User's Reading System, linking can be guaranteed only to the switch element. Deep referencing into the switch element is not recommended.
The occurrence of switch elements in XHTML Content Document is indicated in the Package Document manifest through the switch [Publications30] property.
epub:trigger ElementThe trigger element enables the creation of markup-defined user interfaces for controlling multimedia objects, such as audio and video playback, in both scripted and non-scripted contexts.
trigger
http://www.idpf.org/2007/ops
As a child of head and in Flow content. Repeatable.
id [optional] The ID [XML] of this element, which must be unique within the document scope.
action [required] The action to perform for this event.
Allowed values: show | hide | play | pause | resume | mute | unmute
ref [required] An IDREF [XML] that identifies the element that is the object of the action.
ev:event [required] The applicable event for this trigger, as defined in [XML Events].
ev:observer [required] The source object for this trigger, as defined in [XML Events].
Empty.
The trigger element associates an event from a specified source object (observer) with a desired action to be performed with a specified target object (ref).
The semantics of the defined action values are:
show – set the element's DOM visibility [CSS2.1] property to visible.
hide – set the element's DOM visibility [CSS2.1] property to hidden.
play – play the associated resource from the beginning (only applicable to video or audio elements).
pause – pause playing (only applicable to video or audio elements).
resume – resume playing (only applicable to video or audio elements).
mute – mute sound (only applicable to video or audio elements).
unmute – unmute sound (only applicable to video or audio elements).
Reading Systems that support video or audio playback must support the epub:trigger element.
Sample markup of a video player that uses trigger elements to control playback and muting.
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:epub="http://www.idpf.org/2007/ops"
xmlns:ev="http://www.w3.org/2001/xml-events">
<head>
<epub:trigger ev:observer="pause" ev:event="click" action="pause" ref="test"/>
<epub:trigger ev:observer="resume" ev:event="click" action="resume" ref="test"/>
<epub:trigger ev:observer="mute" ev:event="click" action="mute" ref="test"/>
<epub:trigger ev:observer="mute" ev:event="click" action="show" ref="muted"/>
<epub:trigger ev:observer="unmute" ev:event="click" action="unmute" ref="test"/>
<epub:trigger ev:observer="unmute" ev:event="click" action="hide" ref="muted"/>
</head>
<body>
<video id="test" src="birds.mp4" width="320" height="240"/>
<p>
<span class="button" id="resume">Play/Resume</span>
<span class="button" id="pause">Pause</span>
<span class="button" id="mute">Mute</span>
<span class="button" id="unmute">Unmute</span>
<span id="muted">MUTED</span>
</p>
</body>
</html>
In accordance with [AltStyleTags] , the link element class attribute may include any of the following values: horizontal, vertical, day and night. These values inherit the semantics defined by that specification for their use.
Reading Systems should select and utilize such tagged style sets as appropriate, and as described in that specification.
This section defines deviations and/or constraints in EPUB 3 XHTML Content Documents to the underlying [HTML5] document model.
This section is informative
XHTML Content Documents support embedded MathML [MATHML] but limit its usage to a restricted subset of the full MathML markup language.
This subset is designed to ease the implementation burden on Reading Systems and to promote accessibility, while retaining compatibility with [HTML5] User Agents.
The mathml [Publications30] property of the manifest item element indicates that an XHTML Content Document contains embedded MathML.
Any occurrence of MathML markup in XHTML Content Documents must conform to the constraints expressed in the MathML specification [MATHML], with the following additional restrictions:
› The m:math element must contain only Presentation MathML, with the exception of the m:annotation-xml element as defined below.
› Content MathML may be included within MathML markup in XHTML Content Documents, and, when present, must occur within an m:annotation-xml child element of an m:semantics element.
› When Content MathML is included as per the previous condition, the given m:annotation-xml element's encoding attribute must be set to either of the functionally-equivalent values MathML-Content or application/mathml-content+xml, and its name attribute must be set to contentequiv.
› Elements and attributes marked as deprecated in [MATHML] must not be included within MathML markup in XHTML Content Documents.
› XHTML Content Document fragments may be included within MathML markup in XHTML Content Documents, and, when present, must occur within an m:annotation-xml child element of an m:semantics element.
› When an XHTML Content Document fragment is included as per the above paragraph, the given m:annotation-xml element's encoding attribute must be set to application/xhtml+xml and its name attribute must be set to alternate-representation.
› Any included XHTML Content Document fragments must not themselves contain MathML markup.
› Any included XHTML Content Document fragments must conform to the content model in which the ancestor m:math element occurs, such that if the m:math element is replaced by the given XHTML Content Document fragment the document remains valid.
› Alternative content should be included, and, when present, must be represented as defined in Alternative Content.
A conformant EPUB Reading System must meet all of the following criteria for processing MathML embedded in XHTML Content Documents:
› It must support processing of Presentation MathML, and may support processing of Content MathML, using semantics defined by the MathML 3.0 specification [MATHML].
› If it has a Viewport, it must support visual rendering of Presentation MathML.
› When producing alternative textual content for MathML markup, it should be able to dynamically generate such content from the given Presentation MathML, and if not, must give preference to XHTML Content Document fragments followed by the alttext attribute on the m:math element.
› It must regard the mathml [Publications30] property of the Package Document manifest item element as the authoritative definition of whether an XHTML Content Document includes embedded MathML.
Reading Systems should be able to generate any necessary alternative textual renditions dynamically using the given Presentation MathML markup (e.g., as output to Text-to-Speech (TTS) engines). To support Reading Systems that are not so capable, alternative textual content should be included with each occurrence of the m:math element in XHTML Content Documents.
The alttext attribute on the m:math element should be used for this purpose primarily when shorter alternative text runs are sufficient. When more extensive alternative text is required, XHTML Content Document fragments should be used. (Note that Reading Systems query these two alternative text locations using a defined preference order.)
For Reading System forward compatibility purposes, fallback images may be provided using the altimg attribute on the m:math element. It is recommended that the dimension and alignment attributes (altimg-width, altimg-height and altimg-valign) be used in conjunction with the altimg attribute.
All referenced Publication Resources must conform to the constraints for Publication Resources defined in EPUB Publication — Content Conformance [Publications30].
XHTML Content Documents support the embedding of SVG by reference (embedding via reference, for example, from an img or object element) and by inclusion (embedding via direct inclusion of the svg:svg element in the XHTML Content Document) [SVG].
The content conformance constraints for SVG embedded in XHTML Content Documents are the same as defined for SVG Content Documents in Restrictions on SVG 1.1.
Reading Systems must process SVG embedded in XHTML Content Documents as defined in SVG Content Documents — Reading System Conformance.
The svg [Publications30] property of the manifest item element indicates that an XHTML Content Document contains embedded SVG.
For the purposes of styling SVG embedded in XHTML Content Documents by reference, Reading Systems must not apply CSS style rules of the containing document to the referenced SVG document.
For the purposes of styling SVG embedded in XHTML Content Documents by inclusion, Reading Systems must apply applicable CSS rules of the containing document to the included SVG elements.
SVG included by reference is processed as a separate document, and may include its own CSS style rules just like an SVG Content Document would. Note that this is consistent with situations where an [HTML5] object element references an external [HTML5] element.
This section lists restrictions on the Unicode character repertoire.
Any included characters that map to a code point within one of the Private Use Area (PUA) ranges as defined in [Unicode] must occur within a string that is styled or attributed in a manner that includes a reference to an embedded font that contains an appropriate glyph for that code point.
rp Element› The [HTML5] rp element is intended to provide a fallback — an optional parenthesis display around ruby markup — for older version Reading Systems that do not recognize ruby markup. As EPUB 3 Reading Systems are ruby-aware, and can provide fallbacks, the use of rp elements in Content Documents is discouraged.
embed Element› Since the [HTML5] embed element does not provide intrinsic facilities to provide fallbacks for Reading Systems that do not support scripting, its use is discouraged when the resource referenced has scripting components. Authors should use the object element instead.
This section is informative
The Scalable Vector Graphics (SVG) 1.1 (Second Edition) specification [SVG] defines a format for representing final-form vector graphics and text.
Although an EPUB Publication typically uses XHTML Content Documents as the top-level document type, the use of SVG Content Documents is also permitted. SVGs are typically only used in certain special circumstances, such as when final-form page images are the only suitable representation of the content (as may be the case, for example, in the context of manga or comic books).
This section defines a profile for [SVG] documents. An instance of an XML document that conforms to this profile is a Core Media Type and is referred to in this specification and its sibling specifications as an SVG Content Document.
This section defines conformance requirements for SVG Content Documents. Refer to Embedded SVG for conformance requirements for SVG embedded in XHTML Content Documents.
An SVG Content Document must meet all of the following criteria:
› It must meet the conformance constraints for XML documents defined in XML Conformance [Publications30].
› It must be valid to the SVG Content Document schema as defined in SVG Content Document Schema and conform to all content conformance constraints expressed in Restrictions on SVG 1.1.
› It should adhere to the accessibility guidelines given in [SVG Access].
› The SVG Content Document filename should use the file extension .svg.
All Publication Resources referenced from an SVG Content Document must conform to the constraints for Publication Resources defined in EPUB Publication — Content Conformance [Publications30]
This specification restricts the content model of SVG Content Documents and SVG embedded in XHTML Content Documents as follows:
› The [SVG] Animation Elements and Animation event attributes must not occur.
› The [SVG] svg:foreignObject element must contain only valid XHTML Content Document Flow content, and its requiredExtensions attribute, if given, must be set to http://www.idpf.org/2007/ops.
› The [SVG] svg:title element must contain only valid XHTML Content Document Phrasing content.
A conformant EPUB Reading System must meet all of the following criteria for processing SVG Content Documents and SVG embedded in XHTML Content Documents:
› It must support the language features of SVG that correspond to the feature string http://www.w3.org/TR/SVG11/feature#SVG-dynamic minus the http://www.w3.org/TR/SVG11/feature#Animation and http://www.w3.org/TR/SVG11/feature#AnimationEventsAttribute features (see Feature strings) [SVG].
› It must meet the Reading System conformance criteria defined in Scripted Content Documents — Reading System Conformance.
› If it has an SVG Viewport, it must support the visual rendering of SVG using CSS as defined in Section 6 of [SVG], and it should support all properties defined in Appendix N of that specification. In the case of embedded SVG, it must also conform to the constraints defined in Embedded SVG and CSS.
› It should support User selection and searching of text within SVG elements.
› It must recognize the value http://www.idpf.org/2007/ops of the requiredExtensions attribute when appearing on the svg:switch and svg:foreignObject elements as representing the occurrence of XHTML Content Document fragments.
› It must regard the svg [Publications30] property of the Package Document manifest item element as the authoritative definition of whether an EPUB XHTML Content Document includes embedded SVG.
EPUB Content Documents may contain scripting using the facilities defined for this in the respective underlying specifications ([HTML5] and [SVG]). When an EPUB Content Document contains scripting, it is referred to in this specification and its sibling specifications as a Scripted Content Document. This label also applies to XHTML Content Documents when they contain instances of HTML5 forms.
This specification defines two contexts in which scripts may appear:
An instance of the [HTML5] script element included in a Top-level Content Document.
An instance of the [HTML5] script element included in an EPUB Content Document that is embedded in a parent Content Document using one of the [HTML5] object, iframe or embed elements.
In both of the above-defined contexts, whether the JavaScript code is embedded directly in the script element or referenced via its src attribute makes no difference to the executing context.
Which context a script is used in determines the rights and restrictions that a Reading System may place on it. Refer to Content Conformance and Reading System Conformance for some specific requirements that must be adhered to (not all Reading Systems may provide the same scripting functionality).
Example
Consider the following example Package Document:
<package …>
…
<manifest>
…
<item id="chap01"
href="scripted01.xhtml"
media-type="application/xhtml+xml"
properties="scripted"/>
<item id="inset01"
href="scripted02.xhtml"
media-type="application/xhtml+xml"
properties="scripted"/>
<item id="slideshowjs"
href="slideshow.js"
media-type="text/javascript"/>
</manifest>
<spine …>
<itemref idref="chap01"/>
…
</spine>
…
</package>
and the following file scripted01.xhtml:
<html …>
<head>
…
<script type="text/javascript">
alert("Reading System name: " + navigator.epubReadingSystem.name);
</script>
</head>
<body>
…
<iframe src="scripted02.xhtml" … />
…
</body>
</html>
and the following file scripted02.xhtml:
<html …>
<head>
…
<script type="text/javascript" href="slideshow.js"></script>
</head>
<body>
…
</body>
</html>
From these examples, it is true that:
the code in the script element in the head in scripted01.xhtml is a spine-level script because the document is referenced from the spine;
the code in the script element in scripted02.xhtml is a container-constrained script because the HTML file it occurs in is included in scripted01.xhtml via the iframe element.
› A container-constrained script must not contain instructions for modifying the DOM of the parent Content Document or other contents in the Publication, and must not contain instructions for manipulating the size of its containing rectangle.
› EPUB Content Documents that include spine-level scripting must utilize the progressive enhancement technique, which for the purposes of this specification has the following definition: when the document is rendered by a Reading System without scripting support or with scripting support disabled, the top-level document content must retain its integrity, remaining consumable by the User without any information loss or other significant deterioration.
› EPUB Content Documents that include scripting — using any inclusion model — should employ relevant accessibility techniques to ensure that the content remains consumable by all Users. [WAI-ARIA] [WCAG20]
› EPUB Content Documents that include scripting — using any inclusion model — may provide fallbacks for such content, either by using intrinsic fallback mechanisms (such as those available for the [HTML5] object and canvas elements) or, when an intrinsic fallback is not applicable, by using a manifest-level [Publications30] fallback.
The scripted [Publications30] property of the manifest item element indicates that an EPUB Content Document is a Scripted Content Document.
EPUB Reading System support for scripting is optional. A Reading System that supports scripting must meet the following criteria:
› It must support container-constrained scripting and may support spine-level scripting.
› It may render Scripted Content Documents as an interactive, scripted User Agent according to [HTML5].
› It must not allow a container-constrained script to modify the DOM of the parent Content Document or other contents in the Publication, and must not allow it to manipulate the size of its containing rectangle. (Note: Even if a script is not container-constrained, the Reading System may impose restrictions on modifications (see also the dom-manipulation feature).)
› It may place additional limitations on the capabilities provided to scripts during execution (e.g., limiting networking).
› It must implement the JavaScript navigator extension object epubReadingSystem defined in Appendix B, JavaScript epubReadingSystem Object. It also must support the dom-manipulation and layout-change features defined in Features in container-constrained scripting contexts.
› It must regard the scripted [Publications30] property of the Package Document manifest item element as the authoritative definition of whether an EPUB Content Document includes scripting.
A Reading System that does not support scripting must meet the following criteria:
› It must process fallbacks for scripted content as defined in Fallbacks for Scripted Content Documents.
Reading Systems may render Scripted Content Documents in a manner that disables other EPUB capabilities and/or provides a different rendering and User experience (e.g., by disabling pagination).
Authors choosing to restrict the usage of scripting to the container-constrained model will ensure a more consistent User experience between scripted and non-scripted content (e.g., consistent pagination behavior).
Authors should use declarative techniques whenever practical to increase the interoperability, longevity and accessibility of their Publications, and avoid the inclusion of scripting whenever practical.
This section is informative
All EPUB Authors and Reading System developers need to be aware of the security issues that arise when scripted content is executed by a Reading System. As the underlying scripting model employed by Reading Systems and browsers is the same, the same kinds of issues encountered in Web contexts must be taken into consideration.
Each Reading System should establish if the scripts in a particular document are to be trusted or not. It is recommended that all scripts be treated as untrusted (and potentially malicious), and that all vectors of attack be examined and protected against. In particular, the following should be considered:
an attack against the runtime environment (e.g., stealing files from a User's hard drive);
an attack against the Reading System itself (e.g., stealing a list of a User's books or causing unexpected behavior);
an attack of one Content Document against another (e.g., stealing data that originated in a different document);
an attack of an unencrypted script against an encrypted portion of a document (e.g., an injected malicious script extracting protected content);
an attack against the local network (e.g., stealing data from a server behind a firewall).
The following recommendations are provided as a guide to handling untrusted scripts:
Reading Systems should behave as if a unique domain were allocated to each Content Document, as browser-based security relies heavily on document URLs and domains. Adopting this approach will isolate documents from each other and from other Internet domains, thereby limiting access to external URLs, cookies, DOM storage, etc.
Reading Systems that enable scripting and network access should also consider including methods to notify the user that network activity is occurring and/or that allow them to disable it.
In practice, Reading Systems may share domains across documents, but they still should maintain isolation between documents.
If parts of a document are encrypted and parts are not, or if different encryption keys are used for different parts of the document, a unique per-document domain may not provide sufficient protection.
If a Reading System allows persistent data to be stored, that data should be treated as sensitive. Scripts may save persistent data through cookies and DOM storage, but Reading Systems may block such attempts. Reading Systems that do allow data to be stored must ensure that it is not made available to other unrelated documents (e.g., ones that could have been spoofed). In particular, checking for a matching document identifier (or similar metadata) is not a valid method to control access to persistent data.
Reading Systems that allow local storage should also provide methods for Users to inspect, disable, or delete that data. The data should be destroyed if the corresponding EPUB Publication is deleted.
Note that compliance with these recommendations does not guarantee protection from the possible attacks listed above; developers must examine each potential vulnerability within the context of their Reading System.
This section is informative
Reading Systems should follow the DOM Event model as per [HTML5] and pass UI events to the scripting environment before performing any default action associated with these events. Reading System implementers should ensure that scripts cannot disable critical functionality (such as navigation) to constrain the extent to which a potentially malicious script could impact their Reading Systems. As a result, although the scripting environment should be able to cancel the default action of any event, some events either may not be passed through or may not be cancelable.
Authors should take into account the wide variety of possible Reading System implementations when adding scripting functionality to their Publications (e.g., not all devices have physical keyboard, and in many cases a soft keyboard is only activated only for text input elements). Consequently, relying on keyboard events alone is not recommended; alternative ways to trigger the desired action should always be provided.
This section defines a profile for Cascading Style Sheets (CSS) intended to be used for styling of XHTML Content Documents. An instance of a CSS Style Sheet that conforms to this profile is a Core Media Type and is referred to in this specification and its sibling specifications as an EPUB Style Sheet.
The EPUB 3 CSS Profile references CSS specifications that are still works in progress and may change in incompatible ways. When utilizing features from such specifications, authors should consider the inherent risks in terms of the potential impact on interoperability and document longevity.
The EPUB 3 CSS Profile employs the usage of the -epub- prefix for a number of CSS3 property names, as detailed below. As the CSS3 modules that define these properties mature and stabilize, EPUB authoring guidelines may encourage authors to also include unprefixed equivalents of these properties in EPUB 3 Style Sheets.
A conformant EPUB Style Sheet must meet all of the following criteria:
› It must adhere to all content restrictions given in EPUB 3 CSS Profile.
› It may include constructs not explicitly identified in the EPUB 3 CSS Profile, but should be authored so that rendering fidelity does not depend on such additional constructs.
› It must be UTF-8 or UTF-16 encoded.
All Publication Resources referenced from a CSS Style Sheet must conform to the constraints for Publication Resources defined in EPUB Publication — Content Conformance [Publications30]
› Reading Systems with a CSS Viewport should support — render as defined by the corresponding specification in the Viewport — all CSS constructs included in this profile unless detailed otherwise in EPUB 3 CSS Profile.
› Reading Systems may support additional CSS constructs not explicitly identified in the EPUB 3 CSS Profile, and must handle any unsupported constructs as defined in [CSS2.1].
Reading Systems have varying capabilities with regards to CSS rendering support, so may ignore some or all style information of an EPUB Style Sheet.
In addition, even when a Reading System does have a CSS Viewport, it is likely to render content in a manner that differs from typical HTML5 User Agents (e.g., paginating content rather than providing a infinitely scrolling surface).
The style baseline of the EPUB 3 CSS Profile is Cascading Style Sheets Level 2 Revision 1 [CSS2.1]. The profile includes all style sheet constructs normatively defined in [CSS2.1], with the following exceptions:
The fixed value of the position property is not part of the EPUB 3 CSS Profile. To avoid potential rendering and interoperability issues, it should not be included in an EPUB Style Sheet.
The direction and unicode-bidi properties must not be included in an EPUB Style Sheet. Authors should use appropriate [HTML5] markup to express directionality information instead.
Reading Systems that have a CSS Viewport must support the font-family property.
The ability of Reading Systems to paginate absolutely positioned layouts is not guaranteed, so reliance on absolute positioning is discouraged. Reading Systems may not support these property values.
The EPUB 3 CSS Profile includes the following values for the list-style-type property as defined in [CSS2.0]:
cjk-ideographic
hebrew
hiragana
hiragana-iroha
katakana
katakana-iroha
The EPUB 3 CSS Profile includes -epub- prefixed versions of the following properties from the CSS3 Speech Module [CSS3Speech] using syntax as defined in [CSS3Speech-20110419] and semantics as defined in [CSS3Speech]:
-epub-cue
-epub-pause
-epub-rest
-epub-speak
-epub-speakability
-epub-voice-family
For more information on EPUB 3 features related to synthetic speech, refer to Text-to-speech [EPUB3Overview].
The EPUB 3 CSS Profile includes @font-face rules and descriptors as defined in the CSS Fonts Module Level 3 [CSS3Fonts] specification, using syntax as defined in [CSS3Fonts-20110324] and semantics as defined in [CSS3Fonts].
Reading Systems with a CSS Viewport must support OpenType [OpenType] and WOFF [WOFF] fonts embedded using the @font-face rule.
Refer to Embedded Font Intrinsic Fallback [Publications30] for font fallback processing requirements.
In addition, Reading Systems must support at least the following @font-face font descriptors.
font-family
font-style
font-weight
src
unicode-range
For forwards compatibility with EPUB 2 Reading Systems that do not support @font-face rules, authors should reference a generic font using the font-family property.
Refer to Font Obfuscation [OCF3] for Reading System font obfuscation requirements.
The EPUB 3 CSS Profile includes -epub- prefixed versions of the following properties from the CSS Text Level 3 [CSS3Text] specification using syntax as defined in [CSS3Text-20110412] and semantics as defined in [CSS3Text].
-epub-hyphens
-epub-line-break
-epub-text-align-last
-epub-text-emphasis
-epub-text-emphasis-color
-epub-text-emphasis-style
-epub-word-break
In addition, the EPUB 3 CSS Profile includes the unprefixed text-transform property from CSS Text Level 3 using semantics as defined in [CSS3Text] and syntax as defined in [CSS3Text-20110412], with the exception that the fullwidth and fullsize-kana values are prefixed in the EPUB 3 CSS Profile (-epub-fullwidth and -epub-fullsize-kana, respectively).
With exceptions for the direction and unicode-bidi properties as noted below, the EPUB 3 CSS Profile includes all of the features defined in the CSS Writing Modes Module Level 3 [CSS3WritingModes] specification using -epub- prefixed property names, syntax as defined in [CSS3WritingModes-20110428] and semantics as defined in [CSS3WritingModes].
The direction and unicode-bidi properties from [CSS3WritingModes] are not included in the EPUB 3 CSS Profile. Authors should use appropriate [HTML5] markup to express directionality information instead.
The EPUB 3 CSS Profile includes @media and @import rules with media queries as defined in the Media Queries [MediaQueries] specification.
The EPUB 3 CSS Profile includes the @namespace rule defined in [CSS Namespaces] for declaring the default namespace for a style sheet and for binding prefixes to namespaces.
The EPUB 3 CSS Profile includes all of the features defined in the CSS Multi-column Layout Module [CSSMultiCol] specification with the exception of the column-span property.
Authors should not rely on column behavior in overflow conditions as this behavior is unstable and may change.
Pagination algorithms are not fully defined in CSS. Authors should therefore expect exact pagination points to vary from Reading System to Reading System.
Reading Systems must treat the oeb-column-number property as an alias for the column-count property. The use of the oeb-column-number property in EPUB Style Sheets is deprecated; this conformance requirement may be removed in the next major version of EPUB.
The EPUB 3 CSS Profile includes the -epub-ruby-position property as defined below:
| Name: | -epub-ruby-position |
| Value: | over | under | inter-character |
| Initial: | over |
| Applies to: | ruby text elements |
| Inherited: | yes |
| Percentages: | N/A |
| Media: | visual |
| Computed value: | as specified |
This property controls the placement of ruby text with respect to its base text. Values have the following meanings:
The -epub-ruby-position property will become an alias for the ruby-position property in the CSS Ruby Module [CSS3Ruby].
oeb-page-head and oeb-page-footIn addition to the standard values defined for the display property in Section 9.2.4 of [CSS2.1], EPUB Style Sheets may specify the values oeb-page-head and oeb-page-foot.
Reading Systems should present the content of an element assigned display: oeb-page-head only as a header, and the content of an element assigned display: oeb-page-foot only as a footer. Neither should be presented simply as if it were inline or block. The way Reading Systems present headers and footers is not defined by this specification (e.g., they may render them in fixed positions as per print layouts or pop them up on demand if only limited screen space is available).
For the purposes of page layout, these display values are similar to block boxes with an absolute position (i.e., a position value of fixed or absolute). That is, they are removed from the normal flow and a new block box is created with its own flow. Margins, padding, and other block characteristics are determined as if the element had position: fixed set.
An element assigned display: oeb-page-head or display: oeb-page-foot must not be considered in effect while any markup specified before such an element is still being rendered in the same context (for example, if it is on the same page in a paginated context, or in the viewport for a scrolled context). Once in effect, the element must remain in effect until either of the following conditions is true:
another header or footer (respectively) is in effect instead; or
no part of its parent element remains presented.
For example, when rendered to a screen with appropriate style settings, the myhead-classed div element in the following example would become the page header as soon as nothing preceding the containing div is displayed, and go out of effect when that div is no longer visible:
<div>
<div class="myhead" style="display: none; display: oeb-page-head">
The OEB Publication Structure: Introduction
</div>
<h2>Introduction</h2>
<p>…</p>
</div>The display property has its value set to none in the preceding example before setting it to oeb-page-head to ensure that Reading Systems that do not support this feature do not display the content. This approach is recommended whenever setting the oeb-page-head or oeb-page-foot values.
This section is informative
The W3C Pronunciation Lexicon Specification [PLS] defines syntax and semantics for XML-based pronunciation lexicons to be used by Automatic Speech Recognition and Text-to-Speech (TTS) engines.
The following sections define conformance criteria for PLS documents when included in EPUB Publications, and rules for associating PLS Documents with XHTML Content Documents.
For more information on EPUB 3 features related to synthetic speech, refer to Text-to-speech [EPUB3Overview].
A conformant EPUB Publication must meet all of the following criteria for inclusion of PLS Documents:
› PLS Documents may be associated with XHTML Content Documents. Each XHTML Content Document may contain zero or more PLS Document associations.
› PLS Documents must be associated with the XHTML Content Document to which it applies using the [HTML5] link element with its rel attribute set to pronunciation and its type attribute set to the PLS media type (application/pls+xml).
› The link element hreflang attribute should be specified on each PLS link, and its value must match the language for which the pronunciation lexicon is relevant [PLS] when specified.
› PLS Documents must meet the content conformance criteria defined in PLS Documents — Content Conformance.
› PLS Documents must be represented and located as defined in EPUB Publication — Content Conformance [Publications30].
Examples
The following example shows two PLS Documents (one for Chinese and one for Mongolian) associated with an XHTML Content Document.
<html … >
<head>
…
<link rel="pronunciation" type="application/pls+xml" hreflang="zh" href="../speech/zh.pls"/>
<link rel="pronunciation" type="application/pls+xml" hreflang="mn" href="../speech/mn.pls"/>
</head>
…
</html>To be considered a Core Media Type Resource, a PLS Document must meet all of the following criteria:
› It must meet the conformance constraints for XML documents defined in XML Conformance [Publications30].
› It must be valid to the RELAX NG schema for PLS documents available at the URI http://www.w3.org/TR/pronunciation-lexicon/pls.rng [PLS].
› The PLS Document filename should use the file extension .pls.
A conformant EPUB Reading System must meet all of the following criteria for processing PLS Documents:
› Reading Systems with Text-to-Speech (TTS) capabilities should support PLS.
› Reading Systems that support PLS must process PLS documents as defined in [PLS].
› Reading Systems that support PLS must apply the supplied pronunciation instructions to all text nodes in the current XHTML Content Document whose language [HTML5] matches the language for which the pronunciation lexicon is relevant [PLS]. The algorithm for matching language tags is defined in BCP47.
› When a pronunciation rule is specified more than once for a given string target in a given language, the last occurrence of the rule takes precedence, in such a way that any previously-defined pronunciation rule gets overridden.
› Reading Systems that support PLS and the SSML Attributes must let any pronunciation instructions provided via the ssml:ph attribute take precedence in cases where a pls:grapheme matches a text node of an element that carries the ssml:ph attribute.
The schemas in this Appendix are normative.
NOTE: In this release of this specification, the referenced schemas are not complete.
Validation using these schemas will require a processor that supports [NVDL], [RelaxNG] and [ISOSchematron].
Note, however, that the NVDL schema layer can be substituted by a multi-pass validation using the embedded RELAX NG and ISO Schematron schemas alone.
The schema for XHTML Content Documents is available at http://www.idpf.org/epub/30/schema/epub-xhtml-30.nvdl.
The schema for SVG Content Documents is available at http://www.idpf.org/epub/30/schema/epub-svg-30.nvdl.
ReadingSystem = navigator.epubReadingSystem;
The epubReadingSystem object provides an interface through which a Scripted Content Document can query information about a User's Reading System.
The object exposes a number of properties, about the Reading System, such as its name and version, and provides the hasFeature method which can be invoked to determine the features it supports.
Example JavaScript function that displays the name of the current Reading System.
alert("Reading System name: " + navigator.epubReadingSystem.name);The following properties must be made available for retrieving information about the Reading System.
| Name | Description |
|---|---|
name | Returns a String value representing the name of the Reading System (e.g., iBooks, Kindle). |
version | Returns a String value representing the version of the Reading System (e.g., 1.0, 2.1.1). |
layoutStyle | Returns a A Reading System will typically return one of the values |
hasFeature(feature[, version])
For recognized features, the hasFeature method returns a boolean value indicating whether any version is supported.
If the optional version parameter is included, the return value indicates support only for the specified version.
The method returns undefined if the feature is not recognized by the Reading System.
Example JavaScript function that displays whether the current Reading System supports scripted manipulation of the DOM.
var feature = "dom-manipulation";
var conformTest = navigator.epubReadingSystem.hasFeature(feature);
alert("Feature " + feature + " supported?: " + conformTest);The following table details the features that must be recognized by all Reading Systems that support scripting (spine-level or container-constrained). Reading Systems may support some or all of these features (refer to Scripted Content Documents — Reading System Conformance for more information).
Feature names are case-insensitive.
| Name | Description |
|---|---|
dom-manipulation | Scripts may make structural changes to the document’s DOM (applies to spine-level scripting only). |
layout-changes | Scripts may modify attributes and CSS styles that affect content layout (applies to spine-level scripting only). |
touch-events | The device supports touch events and the Reading System passes touch events to the content. |
mouse-events | The device supports mouse events and the Reading System passes mouse events to the content. |
keyboard-events | The device supports keyboard events and the Reading System passes keyboard events to the content. |
spine-scripting | Spine-level scripting is supported. |
If a Reading System supports a feature defined in this section, it must return a true value both when queried without the version parameter set and when that parameter is set to the value 1.0. Otherwise, it must return false. Reading System developers should not change the version number of these features independently of this specification.
Additional features may be added by Reading System developers, but future versions of this specification may append to this list in ways that may conflict or be incompatible with any such custom additions.
This appendix is informative
EPUB has been developed by the International Digital Publishing Forum in a cooperative effort, bringing together publishers, vendors, software developers, and experts in the relevant standards.
The EPUB 3 specifications were prepared by the International Digital Publishing Forum’s EPUB Maintenance Working Group, operating under a charter approved by the membership in May, 2010 under the leadership of:
Active members of the working group included:
IDPF Members
Invited Experts/Observers
For more detailed acknowledgements and information about contributors to each version of EPUB, refer to Acknowledgements and Contributors [EPUB3Overview].
[AltStyleTags] Alternate Style Tags .
[CSS Namespaces] CSS Namespaces Module .
[CSS2.0] Cascading Style Sheets, level 2 - CSS2 Specification . 12 May 1998 (revised 11 April 2008).
[CSS3Fonts] CSS Fonts Module Level 3 .
[CSS3Fonts-20110324] CSS Fonts Module Level 3 (20110324) . 24 March 2011.
[CSS3Ruby] CSS3 Ruby Annotation Module .
[CSS3Speech] CSS3 Speech Module .
[CSS3Speech-20110419] CSS3 Speech Module (20110419) . 19 April 2011.
[CSS3Text] CSS Text Level 3 .
[CSS3Text-20110412] CSS Text Level 3 (20110412) . 12 April 2011.
[CSS3WritingModes] CSS Writing Modes Module Level 3 .
[CSS3WritingModes-20110428] CSS Writing Modes Module Level 3 (20110428) . 28 April 2011.
[CSSMultiCol] CSS Multi-column Layout Module .
[ContentDocs30] EPUB Content Documents 3.0 .
[ContentProfile] Vocabulary Profile for EPUB Content Documents .
[ISOSchematron] ISO/IEC 19757-3: Rule-based validation — Schematron .
[MATHML] Mathematical Markup Language (MathML) Version 3.0 . 21 October 2010.
[MediaOverlays30] EPUB Media Overlays 3.0 .
[MediaQueries] Media Queries .
[OCF3] Open Container Format 3.0 .
[OPF2] Open Packaging Format 2.0.1 .
[OPS2] Open Publication Structure 2.0.1 .
[OpenType] ISO/IEC 14496-22:2009 - Information technology -- Coding of audio-visual objects -- Part 22: Open Font Format .
[PLS] Pronunciation Lexicon Specification 1.0 (PLS) . 14 October 2008.
[Publications30] EPUB Publications 3.0 .
[RDFa11 Core] RDFa Core 1.1 . Syntax and processing rules for embedding RDF through attributes. 26 October 2010.
[RFC2046] Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types (RFC 2046) . November 1996.
[RFC2119] Key words for use in RFCs to Indicate Requirement Levels (RFC 2119) . March 1997.
[RFC3986] Uniform Resource Identifier (URI): Generic Syntax (RFC 3986) . January 2005.
[RFC5646] Tags for Identifying Languages (RFC 5646) . September 2009.
[RelaxNG] ISO/IEC 19757-2: Regular-grammar-based validation — RELAX NG. Second Edition . 2008-12-15.
[SSML] Speech Synthesis Markup Language (SSML) Version 1.1 . 7 September 2010.
[SVG] Scalable Vector Graphics (SVG) 1.1 (Second Edition) . 22 June 2010.
[SVG Access] Accessibility Features of SVG . 7 August 2000.
[StructureVocab] EPUB 3 Structural Semantics Vocabulary .
[Unicode] The Unicode Consortium. The Unicode Standard, Version 5.0.0, defined by: The Unicode Standard, Version 5.0 (Boston, MA, Addison-Wesley, 2007. ISBN 0-321-48091-0).
[WAI-ARIA] Accessible Rich Internet Applications (WAI-ARIA) 1.0 .
[WCAG20] Web Content Accessibility Guidelines (WCAG) 2.0 . 11 December 2008.
[WOFF] WOFF File Format 1.0 .
[XML] Extensible Markup Language (XML) 1.0 (Fifth Edition) . 26 November 2008.
[XML Events] XML Events . 14 October 2003.
[XMLNS] Namespaces in XML (Third Edition) . 8 December 2009.
[EPUB3Changes] EPUB 3 Differences from EPUB 2.0.1 .
[EPUB3Overview] EPUB 3 Overview .
[Role] Role Attribute . An attribute to support the role classification of elements. 05 August 2010.