This specification defines profiles of HTML, SVG, and CSS for use in the context of EPUB® Publications.

This specification is one of a family of specifications that compose [[EPUB32]], 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.

Refer to [[EPUB32Changes]] for more information on the differences between this specification and its predecessor.

Introduction

Relationship to Other Specifications

Relationship to HTML

This specification does not reference a specific version of W3C [[HTML]], but instead uses an undated reference that will always point to the latest recommendation. This approach ensures that EPUB will always keep pace with changes to the HTML standard. Authors and Reading System developers will need to keep track of changes to HTML, and ensure that their processes and systems are kept up to date.

As HTML evolves, it is possible that features that were valid in previous versions could become obsolete or be removed. It is anticipated that the W3C will make any such changes carefully to ensure minimal disruption for Authors, but in the case of a backwards-incompatible revision the use of an undated reference could be revisited.

The XHTML profile defined by this specification inherits all definitions of semantics, structure and processing behaviors from [[HTML]] unless otherwise specified.

In addition, this specification defines a set of extensions to the W3C HTML document model that Authors can include in XHTML Content Documents.

This specification does not require EPUB Reading Systems to support scripting, HTML forms or the HTML DOM. Reading Systems conformant with this specification are only expected to be able to process a conforming EPUB Content Document. As support for scripting and HTML forms is not compulsory, a conformant Reading System might not be a fully-conformant HTML user agent.

Relationship to SVG

This specification does not reference a specific version of [[SVG2]], but instead uses an undated reference that will always point to the latest recommendation. This approach ensures that EPUB will always keep pace with changes to the SVG standard. Authors and Reading System developers will need to keep track of changes to the SVG standard, and ensure that their processes and systems are kept up to date.

As SVG evolves, it is possible that features that were valid in previous versions could become obsolete or be removed. It is anticipated that the W3C will make any such changes carefully to ensure minimal disruption for Authors, but in the case of a backwards-incompatible revision the use of an undated reference could be revisited.

Relationship to CSS

EPUB 3 supports CSS as defined by the CSS Working Group Snapshot [[CSSSnapshot]]. EPUB 3 also maintains some prefixed CSS properties, to ensure consistent support for global languages.

Terminology

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

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

Namespace prefix mapping

For convenience, the following namespace prefixes [[!XML-NAMES]] are used in this specification without explicitly being declared. To use any of these prefixes in an EPUB Content Document, a declaration is REQUIRED.

prefix URI
epub http://www.idpf.org/2007/ops
pls https://www.w3.org/2005/01/pronunciation-lexicon
ssml https://www.w3.org/2001/10/synthesis

XHTML Content Documents

Introduction

This section defines a profile of [[!HTML]] for creating XHTML Content Documents. An instance of an XML document that conforms to this profile is a Core Media Type Resource and is referred to in this specification as an XHTML Content Document.

Unless otherwise specified, this specification inherits all definitions of semantics, structure and processing behaviors from the [[!HTML]] specification.

Content Conformance

An XHTML Content Document MUST meet all of the following criteria:

Document Properties

It MUST be an [[!HTML]] document that conforms to the XHTML syntax.

It MUST meet the conformance constraints for XML documents defined in XML Conformance [[!EPUB32]].

For all document constructs used that are defined by [[!HTML]], it MUST conform to the conformance criteria defined for those constructs in that specification, unless explicitly overridden in HTML Deviations and Constraints.

It MAY include extensions to the [[!HTML]] grammar as defined in HTML Extensions, and MUST conform to all content conformance constraints defined therein.

The recommendation that EPUB Publications follow the accessibility requirements in [[EPUBAccessibility]] applies to XHTML Content Documents. See Accessibility [[EPUB32]].

File Properties

The XHTML Content Document filename SHOULD use the file extension .xhtml

Reading System Conformance

A conformant EPUB Reading System MUST meet all of the following criteria for processing XHTML Content Documents:

HTML Extensions

This section defines EPUB 3 XHTML Content Document extensions to the underlying [[!HTML]] document model.

Although [[HTML]] allows user agents to support vendor-neutral extensions, unless such extensions are listed in this section they are not supported features of EPUB 3.

Semantic Inflection

Introduction

Semantic inflection is the process of attaching additional meaning about the specific purpose and/or nature an element plays in an XHTML Content Document. The epub:type attribute is used to express domain-specific semantics in XHTML Content Documents, with the inflection(s) it carries complementing the underlying [[HTML]] vocabulary.

The applied semantics are intended to refine the meaning of their containing elements; they are not provided to override their nature (e.g., the attribute can be used to indicate a section is a chapter in a work, but is not designed to turn p elements into list items to avoid proper list structures).

Semantic metadata is not intended for direct human consumption; it instead provides a controlled way for Reading Systems 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 elements, the epub:type attribute can be appended to existing elements to inflect the desired semantics. A mechanism to identify external vocabularies that provide controlled values for the attributes is also defined.

The epub:type Attribute

Attribute Name

type

Namespace

http://www.idpf.org/2007/ops

Usage

Global attribute. MAY be specified on all elements.

Value

A white space-separated list of property [[!Packages32]] values, with restrictions as defined in Vocabulary Association.

White space is the set of characters as defined in [[!XML]].

The epub:type attribute inflects semantics on the element on which it appears. Its value is one or more white 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. In the case of semantically neutral elements, such as the [[!HTML]] div and span elements, the inflected semantic MUST NOT attach a meaning that is already conveyed by an existing element (e.g., that a div represents a paragraph or section). Reading Systems MUST ignore inflected semantics that conflict with the carrying element.

As the [[!HTML]] head element contains metadata for the document, structural semantics expressed on this element or any descendant of it have no meaning. Reading Systems MUST ignore such semantics.

Examples

Vocabulary Association

This specification adopts the vocabulary association mechanisms defined in Vocabulary Association Mechanisms [[!Packages32]], with the following modifications:

Default Vocabulary

The default vocabulary for Content Documents is defined to be the [[!EPUB-SSV]]. Unprefixed terms that are not part of the [[!EPUB-SSV]] MAY be used, but reading systems have no obligations to support them.

Reserved Prefixes

Authors MAY use the following reserved prefixes in the epub:type attribute without having to declare them.

Although reserved prefixes are an authoring convenience, reliance on them can lead to interoperability issues. Validation tools will often reject new prefixes until the tools are updated, for example. Authors are strongly encouraged to declare all prefixes they use to avoid such issues.

Prefix IRI
msv http://www.idpf.org/epub/vocab/structure/magazine/#
prism http://www.prismstandard.org/specifications/3.0/PRISM_CV_Spec_3.0.htm#
The prefix Attribute

The prefix attribute definition is unchanged, but the attribute is defined to be in the namespace http://www.idpf.org/2007/ops when used in EPUB Content Documents.

The prefix attribute is only valid on the [[!HTML]] root html element.

Processing Requirements

A Reading System MUST process the epub:type attribute as follows:

  • It MAY associate behaviors with none, some or all of the terms defined in the default vocabulary.

  • It MAY associate behaviors with terms from other vocabularies.

  • It MUST ignore terms that it does not recognize.

When Reading System behavior associated with a given epub:type value conflicts with an element's native behavior, the behavior associated with the element MUST be given precedence.

Semantic Enrichment

Introduction

Unlike semantic inflection, which is about refining the structures within the markup, semantic enrichment enables the layering of meaning into the content in order to facilitate machine processing.

The [[Microdata]] and [[RDFA-CORE]] specifications both define sets of attributes that can be used in XHTML Content Documents to semantically enrich the content.

RDFa

The use of [[!RDFA-CORE]] attributes is allowed in XHTML Content Documents, but any usage MUST conform to the requirements defined in [[!HTML+RDFA]].

The [[!RDFA-CORE]] specification defines changes to the [[!HTML]] content model when RDFa attributes are used. This modified content model is valid in XHTML Content Documents.

EPUB Reading System support for the attribute processing model [[!RDFA-CORE]] is OPTIONAL.

Microdata

The use of [[!Microdata]] attributes is allowed in XHTML Content Documents, but any usage MUST conform to the requirements defined in that specification.

The [[!Microdata]] specification defines changes to the [[!HTML]] content model when Microdata attributes are used. This modified content model is valid in XHTML Content Documents.

EPUB Reading System support for the attribute processing model is OPTIONAL, as is the conversion to JSON [[!Microdata]].

SSML Attributes

Introduction

The W3C Speech Synthesis Markup Language [[!SSML]] is a language used for assisting Text-to-Speech (TTS) engines in generating synthetic speech. Although SSML is designed as a standalone document type, it also defines semantics suitable for use within other markup languages.

This specification recasts the [[!SSML]] phoneme element as two attributes — ssml:ph and ssml:alphabet — and makes them available within 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]].

The ssml:ph attribute

The ssml:ph attribute specifies a phonemic/phonetic pronunciation of the text represented by the element to which the attribute is attached.

Attribute Name

ph

Namespace

https://www.w3.org/2001/10/synthesis

Usage

Global attribute. MAY be specified on all elements with which a phonetic equivalent can logically be associated (e.g., elements that contain textual information).

MUST NOT be specified on a descendant of an element that already carries this attribute.

Value

A phonemic/phonetic expression, syntactically valid with respect to the phonemic/phonetic alphabet being used.

This attribute inherits all the semantics of the [[!SSML]] phoneme element 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.

The ssml:alphabet attribute

The ssml:alphabet attribute specifies which phonemic/phonetic pronunciation alphabet is used in the value of the ssml:ph attribute.

Attribute Name

alphabet

Namespace

https://www.w3.org/2001/10/synthesis

Usage

Global attribute. MAY be specified on any element.

Value

The name of the pronunciation alphabet used in the value of ssml:ph (inherited).

This attribute inherits all the semantics of the [[!SSML]] phoneme element 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.

Although the [[SSML]] specification makes reference to a registry of alphabets, one has not been published. As the charter of the W3C Voice Browser Working Group has expired, the publication of such a registry is not anticipated. Authors therefore need to reference Reading System support documentation to determine what alphabet values are supported. Some common alphabets include: x-JEITA (also x-JEITA-IT-4002 and x-JEITA-IT-4006) and x-sampa.

Reading Systems that support the SSML Attributes feature of this specification SHOULD support the IPA alphabet [[!IPA]], as expressed by the value "ipa".

Content Switching (Deprecated)

The switch element provides a simple mechanism through which Authors can tailor the content displayed to users, one that is not dependent on the scripting capabilities of the EPUB Reading System.

Use of the switch element is deprecated. Refer to its definition in [[!ContentDocs301]] for usage information.

The epub:trigger Element (Deprecated)

The 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.

Use of the trigger element is deprecated. Refer to its definition in [[!ContentDocs301]] for usage information.

Custom Attributes

Reading Systems MAY introduce functionality not defined in this specification to enhance the rendering of EPUB Publications. To facilitate this experimentation, vendors MAY define custom attributes for use in XHTML Content Documents.

Custom attributes MAY be included on any element in an XHTML Content Document provided such attributes are from a foreign namespace, which is defined as a namespace [[!XML-NAMES]] that does not map to either of the following URIs:

  • http://www.w3.org/1999/xhtml

  • http://www.idpf.org/2007/ops

Custom attributes, and the behaviors associated with them, MUST NOT alter the integrity of an EPUB Publication. The content MUST remain consumable by a user without any information loss or other significant deterioration, regardless of the Reading System it is rendered on.

To facilitate interoperability of custom attributes across Reading Systems, vendors are strongly encouraged to document any extensions they implement in [[AttributeExtensions]].

HTML Deviations and Constraints

This section defines deviations from, and constraints on, the underlying [[!HTML]] document model applicable to EPUB 3 XHTML Content Documents.

Embedded MathML

Introduction

XHTML Content Documents support embedded [[MATHML3]] 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 [[HTML]] user agents.

The mathml property of the manifest item element indicates that an XHTML Content Document contains embedded MathML.

Content Conformance

Any occurrence of MathML markup in XHTML Content Documents MUST conform to the constraints expressed in the MathML specification [[!MATHML3]], with the following additional restrictions:

Presentation MathML

The math element MUST contain only Presentation MathML, with the exception of the annotation-xml element as defined below.

Content MathML

Content MathML MAY be included within MathML markup in XHTML Content Documents, and, when present, MUST occur within an annotation-xml child element of an semantics element.

When Content MathML is included as per the previous condition, the given 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.

Deprecated MathML

Elements and attributes marked as deprecated in [[!MATHML3]] MUST NOT be included within MathML markup in XHTML Content Documents.

XHTML Content Document fragments

XHTML Content Document fragments MAY be included within MathML markup in XHTML Content Documents, and, when present, MUST occur within an annotation-xml child element of an semantics element.

When an XHTML Content Document fragment is included as per the above paragraph, the given 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 math element occurs, such that if the math element is replaced by the given XHTML Content Document fragment the document remains valid.

Reading System Conformance

A conformant EPUB Reading System MUST meet all of the following criteria for supporting MathML embedded in XHTML Content Documents:

  • It MUST be an input-compliant renderer for Presentation MathML, as defined in the [[!MATHML3]] specification.

  • It MAY support rendering of Content MathML found in xml-annotation elements.

  • If it has a Viewport, it MUST support visual rendering of Presentation MathML.

EPUB Reading Systems may choose to use third-party libraries such as MathJax to provide MathML rendering.

Embedded SVG

XHTML Content Documents support the embedding of SVG document fragments [[!SVG2]] by reference (embedding via reference, for example, from an img or object element) and by inclusion (embedding via direct inclusion of the svg element in the XHTML Content Document).

The content conformance constraints for SVG embedded in XHTML Content Documents are the same as defined for SVG Content Documents in Restrictions on SVG.

Reading Systems MUST process SVG embedded in XHTML Content Documents as defined in SVG Content Documents — Reading System Conformance.

The svg property of the manifest item element [[Packages32]] indicates that an XHTML Content Document contains embedded SVG.

Embedded SVG and CSS

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 can include its own CSS style rules just like an SVG Content Document would. Note that this is consistent with situations where an [[HTML]] object element references an external [[HTML]] element.

Unicode Restrictions

This section lists restrictions on the Unicode character repertoire.

Private Use Characters and Embedded Fonts

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 [[!CSS-Fonts-3]] that contains an appropriate glyph for that code point.

Discouraged Constructs

The rp Element

The [[HTML]] rp element is intended to provide a fallback for older Reading Systems that do not recognize ruby markup (i.e., a parenthesis display around ruby markup). As EPUB 3 Reading Systems are ruby-aware, and can provide fallbacks, the use of rp elements is discouraged.

The embed Element

Since the [[!HTML]] embed element does not include intrinsic facilities to provide fallback content for Reading Systems that do not support scripting, Authors are discouraged from using the element when the referenced resource includes scripting. The [[!HTML]] object element can be used instead, as it includes intrinsic fallback capabilities.

Foreign Resource Restrictions

Foreign Resources MAY be referenced from elements that have intrinsic fallback mechanisms, where an intrinsic fallback method is the capability to offer an alternative presentation if the foreign resource is not supported. For example, most [[!HTML]] embedded content elements provide options for alternative rendering, such as allowing multiple sources to be specified or allowing embedded HTML content for when a resource cannot be rendered. A Core Media Type Resource or embedded HTML content MUST be provided via the given element's intrinsic fallback mechanism when a Foreign Resource is referenced.

[[!HTML]] flow content MAY be embedded within the audio and video elements for rendering in older Reading Systems that do not recognize these elements (e.g., EPUB 2 Reading Systems), but it does not represent a fallback Core Media Type Resource.

The following [[!HTML]] elements can refer to Foreign Resources [[!EPUB32]] without having to provide a fallback Core Media Type Resource:

Foreign Resources MAY be referenced from the preceding three elements without the provision of a fallback Core Media Type Resource.

Refer to manifest fallbacks [[Packages32]] for the provision of fallbacks for elements without intrinsic mechanisms, such as the [[HTML]] iframe and img elements.

Form Submission

Reading System support for the submission of [[!HTML]] forms is OPTIONAL. A Reading System might, for example, prevent form submissions by limiting access to networking.

SVG Content Documents

Some features of [[!SVG2]] are not fully supported in Reading Systems, or supported across all platforms on which Reading Systems run. When utilizing such features, Authors need to consider the inherent risks in terms of the potential impact on interoperability and document longevity.

Introduction

The Scalable Vector Graphics (SVG) specification [[SVG2]] 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 (e.g., for cover art or in the context of manga or comic books).

This section defines a profile for [[SVG2]] documents. An instance of an XML document that conforms to this profile is a Core Media Type Resource and is referred to in this specification as an SVG Content Document.

This section defines conformance requirements for SVG Content Documents. Refer to Embedded SVG for the conformance requirements for SVG embedded in XHTML Content Documents.

Content Conformance

An SVG Content Document MUST meet all of the following criteria:

Document Properties

It MUST meet the conformance constraints for XML documents defined in XML Conformance [[!EPUB32]].

It MAY include references to Foreign Resources provided a fallback to a Core Media Type Resource is included.

It MUST be an SVG document fragment [[!SVG2]], and conform to all content conformance constraints expressed in Restrictions on SVG.

The recommendation that EPUB Publications follow the accessibility requirements in [[EPUBAccessibility]] applies to SVG Content Documents. See Accessibility [[EPUB32]].

File Properties

The SVG Content Document filename SHOULD use the file extension .svg.

Restrictions on SVG

This specification restricts the content model of SVG Content Documents and SVG embedded in XHTML Content Documents as follows:

Reading System Conformance

A conformant EPUB Reading System MUST meet all of the following criteria for processing SVG Content Documents and SVG embedded in XHTML Content Documents:

Semantic Inflection

The syntax and semantics defined in XHTML Semantic Inflection are inherited for use of the epub:type and epub:prefix attributes in SVG Content Documents.

The use of the epub:prefix attribute is only valid on the root svg element in SVG Content Documents. Prefixes used in embedded SVG MUST be declared on the [[!HTML]] root html element, as defined in XHTML Semantic Inflection.

CSS Style Sheets

Introduction

CSS has been an integral part of the Open Web Platform for nearly two decades — readers, publishers, and document authors expect CSS to "just work," as they expect HTML to just work.

In the past, EPUB defined a profile of CSS that mandated support for certain properties and provided prefixed versions of numerous other properties. Although the CSS Working Group no longer recommends the use of prefixed properties, this specification has to maintain some prefixed properties to avoid breaking existing content. But with the minor exceptions defined in this section, EPUB defers to the W3C to define CSS.

Content Conformance

A conformant CSS style sheet MUST meet all of the following criteria:

Keep in mind that some Reading Systems will not support all desired features of CSS. In particular, the following are known to be problematic:

  • Reading System-induced pagination can interact poorly with style sheets. Pagination is sometimes done using columns, which can result in incorrect values for viewport sizes. Fixed and absolute positioning are particularly problematic.

  • Some types of screens will render animations and transitions poorly (e.g., those with high latency).

Reading System Conformance

A conformant EPUB Reading System MUST meet all of the following criteria for processing CSS Style Sheets:

Reading System developers are encouraged to implement CSS support at the level of major browsers.

Prefixed Properties

Authors are strongly encouraged to use unprefixed properties, and Reading Systems to support current CSS specifications. The widely-used prefixed properties from [[!ContentDocs301]] have been retained, but support for the other properties has been removed. Authors are advised to use CSS-native solutions for the removed properties where and when they are available.

Authors currently using these prefixed properties are advised to move to unprefixed versions as soon as support allows, as these properties are not anticipated to be supported in the next major version of EPUB.

CSS Writing Modes

The following table lists the -epub- prefixed properties for [[!CSS-Writing-Modes-3]]. The Value column indicates the value the property accepts. The Prior EPUB Mapping column indicates values/properties that were used in previous versions of EPUB 3. An asterisk (*) denotes that the older property or value is now deprecated. The final column describes how to implement the prefixed property based on [[!CSS-Writing-Modes-3-20151215]].

Property Value Prior EPUB Mapping Mapping to [[!CSS-Writing-Modes-3-20151215]]
-epub-text-orientation upright upright upright
-epub-text-orientation mixed vertical-right* mixed
-epub-text-orientation sideways-right sideways-right sideways
-epub-text-orientation sideways-right rotate-right* sideways
-epub-text-orientation sideways rotate-normal* sideways
-epub-text-orientation sideways sideways sideways
-epub-text-orientation mixed mixed mixed
-epub-writing-mode horizontal-tb horizontal-tb horizontal-tb
-epub-writing-mode vertical-rl vertical-rl vertical-rl
-epub-writing-mode vertical-lr vertical-lr vertical-lr
-epub-text-combine* -epub-text-combine-horizontal: none none text-combine-upright: none
-epub-text-combine* -epub-text-combine-horizontal: all horizontal text-combine-upright: all
-epub-text-combine* Error horizontal <number> text-combine-upright: digits <number>

CSS Text Level 3

Property Value Mapping to [[!CSS-Text-3-20160119]]
-epub-hyphens none | manual | auto No Change
-epub-hyphens all Not Supported
-epub-line-break auto | loose | normal | strict No Change
-epub-text-align-last auto | start | end | left | right | center | justify No Change
-epub-word-break normal | keep-all | break-all No Change
text-transform -epub-fullwidth text-transform: full-width

CSS Text Decoration Level 3

Property Value Mapping to [[!CSS-Text-Decor-3]]
-epub-text-emphasis-color <color> No Change
-epub-text-emphasis-position [ over | under ] && [ right | left ] No Change
-epub-text-emphasis-style none | [ [ filled | open ] || [ dot | circle | double-circle | triangle | sesame ] ] | <string> No Change
-epub-text-underline-position auto | [ under || [ left | right ] ] No Change
-epub-text-underline-position alphabetic text-underline-position: auto

Property value syntax defined in Component value combinators [[!CSS-Values-3]].

Reading System Overrides

EPUB Reading Systems SHOULD apply Author style sheets as written to EPUB Content Documents. If a Reading System allows, users SHOULD be able to override Author style sheets as desired. EPUB Reading Systems SHOULD NOT override Author style sheets unless strictly necessary.

If a Reading System has to override an Author style sheet, it SHOULD do so in a way that preserves the Cascade: through a user agent style sheet, the getOverrideStyle method [[!DOM-Level-2-Style]], or [[!HTML]] style attributes.

Developers of Reading Systems are strongly encouraged to publicly document their user agent style sheets and how they interact with Author style sheets.

Scripting

Scripting Contexts

EPUB Content Documents MAY contain scripting using the facilities defined for this in the respective underlying specifications ([[!HTML]] and [[!SVG2]]). When an EPUB Content Document contains scripting, it is referred to in this specification as a Scripted Content Document. This label also applies to XHTML Content Documents when they contain instances of [[!HTML]] forms.

This specification defines two contexts in which scripts MAY appear:

spine-level

An instance of the [[!HTML]] script or [[!SVG2]] script element included in a Top-level Content Document.

container-constrained

Either of the following:

  • An instance of the [[!HTML]] script element included in an XHTML Content Document that is embedded in a parent XHTML Content Document using the [[!HTML]] iframe element.

  • An instance of the [[!SVG2]] script element included in an SVG Content Document that is embedded in a parent XHTML Content Document using the [[!HTML]] iframe element.

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 places on it. Refer to Content Conformance and Reading System Conformance for some specific requirements that have to be adhered to (not all Reading Systems will provide the same scripting functionality).

Example

Content Conformance

Container-constrained scripts

A container-constrained script MUST NOT contain instructions for modifying the DOM of the parent Content Document or other contents in the EPUB Publication, and MUST NOT contain instructions for manipulating the size of its containing rectangle.

Spine-level scripts

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 Content Document MUST retain its integrity, remaining consumable by the user without any information loss or other significant deterioration.

Accessibility

EPUB Content Documents that include scripting SHOULD employ relevant [[!WAI-ARIA]] accessibility techniques to ensure that the content remains consumable by all users.

Fallbacks

EPUB Content Documents that include scripting MAY provide fallbacks for such content, either by using intrinsic fallback mechanisms (such as those available for the [[!HTML]] object and canvas elements) or, when an intrinsic fallback is not applicable, by using a manifest-level fallback [[!Packages32]].

Authors MUST ensure that scripts only generate Core Media Type Resources or fragments thereof [[!EPUB32]].

The scripted property of the manifest item element indicates that an EPUB Content Document is a Scripted Content Document.

Reading System Conformance

A Reading System that supports scripting MUST meet the following criteria:

A Reading System that does not support scripting MUST meet the following criteria:

Reading Systems might 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 are advised to use declarative techniques whenever practical to increase the interoperability, longevity and accessibility of their EPUB Publications, and avoid the inclusion of scripting whenever practical.

Security Considerations

All EPUB Authors and EPUB Reading System developers have 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 have to be taken into consideration.

Each Reading System has to establish if the scripts in a particular document are to be trusted or not. It is advised 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 need to be considered:

The following recommendations are provided as a guide to handling untrusted scripts:

Note that compliance with these recommendations does not guarantee protection from the possible attacks listed above; developers have to examine each potential vulnerability within the context of their Reading System.

Event Model Considerations

Reading Systems need to follow the DOM Event model as per [[HTML]] and pass UI events to the scripting environment before performing any default action associated with these events. Reading System implementers need to 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 needs to be able to cancel the default action of any event, some events either might not be passed through or might not be cancelable.

Authors need to take into account the wide variety of possible Reading System implementations when adding scripting functionality to their EPUB Publications (e.g., not all devices have physical keyboards, and in many cases a soft keyboard is activated only for text input elements). Consequently, relying on keyboard events alone is not advised; alternative ways to trigger a desired action always need to be provided.

Fixed Layouts

Introduction

This section defines rules for the expression and interpretation of dimensional properties of EPUB Content Documents marked as pre-paginated in the Package Document.

This specification does not define how the initial containing block [[!CSS2]] will be placed within the Reading System Content Display Area.

Refer to Fixed-Layout Properties [[Packages32]] for information on how to designate that a Rendition, or its individual spine items, are to be rendered in a pre-paginated manner (i.e., with fixed width and height dimensions).

Content Conformance

A conformant Fixed-Layout Document MUST meet all of the following criteria:

Reading System Conformance

A conformant EPUB Reading System MUST meet all of the following criteria for processing Fixed-Layout Documents:

Viewport Rendering

When rendering Fixed-Layout Documents, the default intent is that the Content Display Area SHOULD occupy as much of the available Viewport area as possible. Reading Systems SHOULD NOT inject additional content such as border, margins, headers or footers into the Viewport.

The exposure of Reading System control widgets to the user is implementation-specific and not included in the above behavioral expectations.

Initial Containing Block Dimensions

Expressing in HTML

For XHTML Content Documents, the initial containing block [[!CSS2]] dimensions MUST be expressed in a viewport meta tag using the syntax defined in [[!CSS-Device-Adapt-1]]. In this version of this specification, only the width and height expressions MUST be recognized by Reading Systems.

Reading Systems MUST clip XHTML content to the initial containing block (ICB) dimensions declared in the viewport meta tag — content positioned outside of the initial containing block will not be visible. When the ICB aspect ratio does not match the aspect ratio of the Reading System Content Display Area, Reading Systems MAY position the ICB inside the area to accommodate the user interface; in other words, added letter-boxing space MAY appear on either side (or both) of the content.

Expressing in SVG

For SVG Content Documents, the root svg element MUST include one or both of:

It is RECOMMENDED to use only the viewBox attribute to ensure proper rescaling of the SVG Content Document, as needed.

If only the [[!SVG2]] viewBox attribute is present, the coordinate system it defines is mapped to the Viewport, keeping the aspect ratio, thereby establishing the initial containing block (ICB) in pixels [[!CSS2]]. The result of this mapping is typically the bounds of the Viewport.

If only the x, y, height and width attributes are present, they SHOULD be defined in pixel values (establishing the ICB). Note that if the pixel values defined by x, y, height and width attributes exceed the Viewport's pixel values, the graphic will be clipped on the Viewport boundaries (i.e., the graphics will not be rescaled).

If the coordinate system is defined by the viewBox and the width/height values, the coordinate system defined by the viewBox is mapped on the boundaries as described in the previous item.

See [[SVG2]] for more details on the interplay between viewBox and the width/height values.

Pronunciation Lexicons

Introduction

The W3C Pronunciation Lexicon Specification [[PRONUNCIATION-LEXICON]] 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]].

EPUB Publication Conformance

A conformant Rendition of an EPUB Publication MUST meet all of the following criteria for inclusion of PLS Documents:

Examples

Content Conformance

A PLS Document MUST meet all of the following criteria:

Document Properties

It MUST meet the conformance constraints for XML documents defined in XML Conformance [[!EPUB32]].

It MUST be valid to the RELAX NG schema for PLS documents available at the URI https://www.w3.org/TR/2008/REC-pronunciation-lexicon-20081014/ [[!PRONUNCIATION-LEXICON]].

File Properties

The PLS Document filename SHOULD use the file extension .pls.

Reading System Conformance

A conformant EPUB Reading System MUST meet all of the following criteria for processing PLS Documents:

JavaScript epubReadingSystem Object

Interface Definition

This specification extends the [[!HTML]] Navigator object as follows.

[Exposed=(Window)]
interface EpubReadingSystem {
    [Unforgeable] readonly attribute DOMString name;
    [Unforgeable] readonly attribute DOMString version;
    boolean hasFeature(DOMString feature, optional DOMString version);
};

partial interface Navigator {
    [Unforgeable, SameObject] readonly attribute EpubReadingSystem epubReadingSystem;
};

[[!WEBIDL]] notation.

This specification does not define an epubReadingSystem property extension for the WorkerNavigator object [[WebWorkers]]. Reading Systems therefore do not have to expose the epubReadingSystem object in the scripting context of Workers, and Authors cannot rely on its presence.

Description

The Navigator.epubReadingSystem object provides an interface through which a Scripted Content Document can query information about a user's Reading System.

The object exposes properties of the Reading System (its name and version), and provides the hasFeature method which can be invoked to determine the features it supports.

Reading Systems MUST expose the epubReadingSystem object on the navigator object of all loaded Scripted Content Documents, including any nested container-constrained scripting contexts. Reading Systems MUST ensure that the epubReadingSystem object is available no later than when the DOMContentLoaded event is triggered [[!HTML]].

Reading systems implementations might create cloned instances of the epubReadingSystem object in Scripted Content Documents for technical feasibility reasons. In such cases, the Reading System has to ensure that the object’s state — as reflected by the values of its properties and methods — is consistently maintained across all copied instances.

Properties

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 Use of the layoutStyle property is deprecated. Refer to its definition in [[!ContentDocs301]] for usage information.

Methods

hasFeature

Description

The hasFeature method returns a boolean value indicating whether any version of the specified feature is supported, or undefined if the specified feature is not recognized.

The OPTIONAL version parameter is included for querying custom features that could change in incompatible ways over time. The return value indicates support only for the specified version of the feature.

Authors SHOULD NOT include the version parameter when querying features defined in this specification — these features are considered versionless. If a Reading System supports a feature defined in this specification, it MUST ignore any supplied version parameter and return a true value.

Features

The following table lists the set of features that Reading Systems that support the epubReadingSystem object MUST recognize (i.e., provide a return value for). Support for these features is OPTIONAL.

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 Indicates whether the Reading System supports spine-level scripting (e.g., so a container-constrained script can determine whether any actions that depend on scripting support in a Top-level Content Document have any chance of success before attempting them).

Additional features MAY be added by Reading System developers, but future versions of this specification might append to this list in ways that could conflict or be incompatible with any such custom additions.