Copyright © 1999-2019 International Digital Publishing Forum™ and W3C® (MIT, ERCIM, Keio, Beihang)
EPUB is a registered trademark of the International Digital Publishing Forum.
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.
This specification was published by the EPUB 3 Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Final Specification Agreement (FSA) other conditions apply. Learn more about W3C Community and Business Groups.
If you wish to make comments regarding this document, please send them to public-epub3@w3.org (subscribe, archives).
This section is non-normative.
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.
This specification does not reference a specific version of [SVG], but instead uses an undated reference. Whenever there is any ambiguity in this reference, the latest recommended specification is the authoritative reference.
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.
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.
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.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, OPTIONAL, REQUIRED, SHOULD, and SHOULD NOT are to be interpreted as described in [RFC2119].
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 |
ssml |
https://www.w3.org/2001/10/synthesis |
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.
An XHTML Content Document MUST meet all of the following criteria:
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].
The XHTML Content Document filename SHOULD use the file
extension .xhtml
A conformant EPUB Reading System MUST meet all of the following criteria for processing XHTML Content Documents:
Unless explicitly defined by this specification as overridden, it MUST process XHTML Content Documents using semantics defined by the [HTML] specification and honor any applicable user agent conformance constraints expressed therein.
It MUST meet all Reading System conformance criteria defined in HTML Extensions.
It MUST recognize and adapt behaviorally to the constraints defined in HTML 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 CSS 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 [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.
This section is non-normative.
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 intended to enrich content for use in publishing workflows and for author-defined purposes. While it also allows Reading Systems to learn more about the structure and content of a document, no specific behaviors are defined for the semantics by this specification. Any such behaviors are Reading System-dependent.
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.
epub:type Attributetype
http://www.idpf.org/2007/ops
Global attribute. MAY be specified on all elements.
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.
This specification adopts the vocabulary association mechanisms defined in Vocabulary Association Mechanisms [Packages32], with the following modifications:
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 included, but their use is discouraged. The use of prefixes is the preferred method for adding custom semantics.
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 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.
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.
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.
This section is non-normative.
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.
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.
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].
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].
ssml:ph attributeThe ssml:ph attribute specifies a phonemic/phonetic pronunciation of the text
represented by the element to which the attribute is attached.
ph
https://www.w3.org/2001/10/synthesis
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.
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.
ssml:alphabet attributeThe ssml:alphabet attribute specifies which phonemic/phonetic pronunciation
alphabet is used in the value of the ssml:ph
attribute.
alphabet
https://www.w3.org/2001/10/synthesis
Global attribute. 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] 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".
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.
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.
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].
This section defines deviations from, and constraints on, the underlying [HTML] document model applicable to EPUB 3 XHTML Content Documents.
This section is non-normative.
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.
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:
The math element MUST contain only Presentation MathML, with
the exception of the annotation-xml element.
Content MathML MAY be included within MathML markup in XHTML Content
Documents, and, when present, MUST occur within an annotation-xml child
element of a 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.
Elements and attributes marked as deprecated in [MATHML3] MUST NOT be included within MathML markup in XHTML Content Documents.
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
annotation-xml 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.
XHTML Content Documents support the embedding of SVG document
fragments [SVG] 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.
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.
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 [CSS-Fonts-3] that contains an appropriate glyph for that code point.
This section is non-normative.
rp ElementThe [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.
embed ElementSince 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 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.
Due to the variety of sources that can be associated with
to the [HTML] img element, the following fallback conditions apply to its use:
If it is the child of a picture element:
src and
srcset attributes, when those attributes are specified; andsource element MUST reference a Core Media Type Resource
from its src and srcset attributes unless it specifies a
media type in its type attribute that is not a Core Media Type.src and
srcset attributes provided manifest fallbacks
[Packages32] are defined.The following [HTML] elements can refer to Foreign Resources [EPUB32] without having to provide a fallback Core Media Type Resource:
link — when its rel attribute has the value "pronunciation"
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.
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.
Some features of [SVG] 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.
This section is non-normative.
The Scalable Vector Graphics (SVG) 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 (e.g., for cover art or 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 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.
An SVG Content Document MUST meet all of the following criteria:
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 [SVG], 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].
The SVG Content Document filename SHOULD use the file
extension .svg.
This specification restricts the content model of SVG Content Documents and SVG embedded in XHTML Content Documents as follows:
The [SVG] foreignObject element MUST adhere to the following
criteria:
It MUST contain either [HTML] flow content or
exactly one [HTML] body element.
In the case of embedded SVGs, a
body element is not permitted per the restrictions on SVG defined in [HTML].
Its content MUST be a valid document fragment that conforms to the XHTML Content Document model defined in XHTML Content Documents — Content Conformance.
Its requiredExtensions attribute,
if given, MUST be set to "http://www.idpf.org/2007/ops".
The [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:
Unless explicitly defined by this specification as overridden, it MUST process SVG Content Documents using semantics defined by the [SVG] specification and honor any applicable user agent conformance constraints expressed therein.
It MUST meet the Reading System conformance criteria defined in Scripted Content Documents — Reading System Conformance.
If it has a Viewport, it MUST support the visual rendering of SVG using CSS as defined in Styling [SVG], and it SHOULD support all properties defined in the Property Index [SVG]. 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 as representing the occurrence of XHTML Content Document fragments (e.g., when the
attribute is included on the foreignObject element or children of the
switch element).
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.
This section is non-normative.
CSS is an integral part of the Open Web Platform. 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.
A conformant CSS style sheet MUST meet all of the following criteria:
It MAY include any CSS properties, with the following exceptions:
It MUST NOT use the direction property [CSS-Writing-Modes-3]. Use the
[HTML] dir attribute to set the inline base direction.
It MUST NOT use the unicode-bidi property [CSS-Writing-Modes-3]. Use
[HTML] bdo elements and dir
attributes to control bidirectionality.
It MAY include the prefixed properties defined in CSS Style Sheets — Prefixed Properties.
It MUST be encoded in UTF-8 or UTF-16 [Unicode].
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).
A conformant EPUB Reading System MUST meet all of the following criteria for processing CSS Style Sheets:
It MUST support the official definition of CSS as described in the [CSSSnapshot].
It SHOULD support all applicable modules in [CSSSnapshot] that have reached at least Candidate Recommendation status [W3CProcess] (and are widely implemented).
It MUST support [TrueType], [OpenType], [WOFF] and
[WOFF2] font resources referenced from @font-face rules.
It MUST support all prefixed properties defined in CSS Style Sheets — Prefixed Properties.
In addition to supporting CSS properties as defined above, its user agent style sheet SHOULD support the [HTML] suggested default rendering.
It SHOULD respect Author CSS and user styles as defined in Reading System Overrides.
Reading System developers are encouraged to implement CSS support at the level of major browsers.
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.
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> |
| 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 |
| 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].
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.
EPUB Content Documents MAY contain scripting using the facilities defined for this in the respective underlying specifications ([HTML] and [SVG]). 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:
An instance of the [HTML] script or [SVG] script
element included in a Top-level Content Document.
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 [SVG] 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).
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.
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.
EPUB Content Documents that include scripting SHOULD employ relevant [WAI-ARIA] accessibility techniques to ensure that the content remains consumable by all users.
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.
A Reading System that supports scripting MUST meet the following criteria:
It SHOULD support container-constrained scripting in reflowable EPUB Content Documents.
It SHOULD support spine-level scripting in fixed-layout documents.
It SHOULD support spine-level scripting in reflowable EPUB
Content Documents that use the "scrolled-doc" or "scrolled-continuous" presentation modes defined by the rendition:flow property
[Packages32]. Similarly, if it supports spine-level scripting in reflowable EPUB Content
Documents, it MUST implement the "scrolled-doc" presentation mode and SHOULD
implement the "scrolled-continuous" presentation mode.
It MAY support scripting in other contexts, but this specification does not address such scripting. As a result, the use of scripting in these contexts might not be consistent across Reading Systems.
It MAY render Scripted Content Documents as an interactive, scripted user agent according to [HTML].
It MUST NOT allow a container-constrained script to modify the DOM of the parent Content Document or other contents in the EPUB 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 A, JavaScript epubReadingSystem
Object. It also MUST support the dom-manipulation and
layout-change features defined in Features in container-constrained scripting contexts.
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 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.
This section is non-normative.
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:
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 need to 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 also need to consider including methods to notify the user that network activity is occurring and/or that allow them to disable it.
In practice, Reading Systems might share domains across documents, but they still need to 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 might not provide sufficient protection.
If a Reading System allows persistent data to be stored, that data needs to be treated as sensitive. Scripts might save persistent data through cookies and DOM storage, but Reading Systems might block such attempts. Reading Systems that do allow data to be stored have to 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 also need to provide methods for users to inspect, disable, or delete that data. The data needs to 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 have to examine each potential vulnerability within the context of their Reading System.
This section is non-normative.
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.
This section is non-normative.
This section defines rules for the expression and interpretation of dimensional properties of
Fixed-Layout Documents — 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).
A conformant Fixed-Layout Document MUST meet all of the following criteria:
It MUST specify its initial containing block [CSS2] as defined in Initial Containing Block Dimensions.
A conformant EPUB Reading System MUST meet all of the following criteria for processing Fixed-Layout Documents:
It SHOULD allocate the full Content Display Area for the document, as defined in Viewport Rendering.
It MUST use the dimensions expressed in the viewport
meta tag to render XHTML Content Documents, as defined in Expressing the ICB in HTML.
It MUST use the dimensions as defined in Expressing the ICB in SVG to render SVG Content Documents.
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.
For XHTML Fixed-Layout 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.
For SVG Fixed-Layout Documents, the ICB dimensions MUST be expressed using the viewBox
attribute [SVG].
This section is non-normative.
The W3C Pronunciation Lexicon Specification (PLS) [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].
A conformant Rendition of an 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 they apply using the [HTML] link element with its rel attribute set to
"pronunciation" and its type attribute set to the media type
"application/pls+xml".
The
link element hreflang attribute SHOULD be specified on each
link, and its value MUST match the language
for which the pronunciation lexicon is relevant [PRONUNCIATION-LEXICON] 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 Package — Conformance [Packages32].
A PLS document MUST meet all of the following criteria:
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].
The PLS document filename SHOULD use the file extension
.pls.
Reading Systems with Text-to-Speech (TTS) capabilities SHOULD support PLS documents.
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 [PRONUNCIATION-LEXICON].
It MUST process PLS documents as defined in [PRONUNCIATION-LEXICON].
It MUST apply the supplied pronunciation instructions to all text nodes in the current XHTML Content Document whose language [HTML] matches the language for which the pronunciation lexicon is relevant [PRONUNCIATION-LEXICON]. 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, it MUST give precedence to the last occurrence of the rule in such a way that any previously-defined pronunciation rule gets overridden.
If it also supports SSML
Attributes, it MUST let any pronunciation instructions provided via the ssml:ph attribute take precedence in
cases where a grapheme element [PRONUNCIATION-LEXICON] matches a text node
of an element that carries the ssml:ph attribute [SSML].
epubReadingSystem ObjectThis specification extends the [HTML] Navigator object as follows.
[Exposed=(Window)] interface EpubReadingSystem { [Unforgeable] readonly attribute DOMStringname; [Unforgeable] readonly attribute DOMStringversion; booleanhasFeature(DOMString feature, optional DOMString version); };
[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.
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.
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. |
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.
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.
This section is non-normative.
EPUB 3 is developed by the W3C's EPUB 3 Community Group in coordination with the Publishing Business Group.
The EPUB 3.2 revision was led by:
In addition to the editors, this version of EPUB would not have been possible without significant contributions from:
Special thanks go to the former members of the International Digital Publishing Forum, particularly Markus Gylling and Bill McCoy, without whom EPUB would not have become a reality.
This version is outdated!For the latest version, please refer to https://www.w3.org/TR/epub/ and https://www.w3.org/TR/epub-rs/.