3.1 Path Resolution
The process of resolving an EPUB CFI to a location within an EPUB Publication begins with the root
package element of the Package Document. Each step in the CFI is then processed one by one, left
to right, applying the rules defined in the following subsections.
note
The EPUB CFI examples in the following subsections are based on the sample documents in Examples.
3.1.1 Step Reference to Child Element or Character Data (/)
A step with a slash (/) followed by a positive integer refers to either a child element or a
chunk of character data, as per the rules defined herein:
-
[XML] content other than element and character data is ignored. Note that as per the
[XML] specification, character data inside CDATA sections is included, and conversely, XML
comments are ignored.
-
[XML] character data that corresponds to insignificant white space (typically used for
markup formatting/indenting) is preserved. Character and entity references are considered expanded, and
character data is obtained from the "included replacement text" (as per the terminology defined in the [XML] specification).
-
[XML] character data that is interspersed amongst sibling child elements (i.e., "mixed
content" context) is logically organised into (potentially-empty) chunks of contiguous character data: the
first chunk is located before the first child element (left sibling), the last chunk is located after the last
child element (right sibling), and there is one chunk between each pair of child elements. When there are no
child elements, there is one (potentially-empty) chunk of character data. Consecutive (potentially-empty)
chunks of character data are each assigned odd indices (i.e., starting at 1, followed by 3, etc.).
-
Child [XML] elements are assigned even indices (i.e., starting at 2, followed by 4,
etc.). Additionally, 0 is a valid index that refers to a non-existing element which virtually precedes the
first potentially-empty chunk of character data within the parent element's content. Similarly,
n+2 is a valid index that refers to a non-existing element which virtually follows the
last potentially-empty chunk of character data, where n is the even index of the last child
element, or 0 if there are no child elements. CFI processors (e.g., Reading Systems) must be capable of consuming (e.g., parsing and interpreting) CFI expressions containing
references to the 0 and n+2 "virtual" elements, even when the first (or last, respectively)
chunk of character data is empty. Conversely, the *production* of such CFI expressions is governed by the
following conformance requirement: if the first chunk of character data is empty, a CFI expression should not be constructed using a reference to the "virtual" element at index 0,
instead the "real" first child element (at index 2) should be referred to.
Similarly, if the last chunk of character data is empty, a CFI expression should
not be constructed using a reference to the "virtual" element at index n+2,
instead the "real" last child element (at index n) should
be referred to.
note
The "virtual" first / last elements mechanism might facilitate interoperability with certain instances of DOM
Ranges, whereby non-existing elements are used to span across textual content without relying on character
offsets at the start/end boundaries.
For a Standard EPUB CFI, the leading step in the CFI must start
with a slash (/) followed by an even number that references the spine child
element of the Package Document's root package element. The Package Document traversed by the CFI
must be the one specified as the Default Rendition in the EPUB Publication's
META-INF/container.xml file (i.e., the Package Document referenced by the first
rootfile element in container.xml).
For an Intra-Publication EPUB CFI, the first step must start with
a slash followed by a node number that references a position in Package Document starting from the root
package element.
3.1.2 XML ID Assertion ([)
When an EPUB CFI references an element that contains an ID [XML], the corresponding path
step must include that ID in square brackets (i.e., after the slash
(/) and even number that identifies the element).
Specification of identifiers adds robustness to the CFI scheme: a Reading System can determine that the
location referenced by the CFI is not the original intended location, and can use the identifier to compute the set
of steps that reach the desired destination in the content (see Intended Target Location Correction). The cost
of this added robustness is that comparison (and sorting) of CFI strings can be performed only after logically
stripping all bracketed substrings (see Sorting Rules).
3.1.3 Step Indirection (!)
If a step, or a sequence of steps, points to an element that references another document, the exclamation mark
(!) must be used whenever that step is immediately followed
by an expression that applies to the referenced document ("indirection"). The following expression is then resolved
from the root element of the referenced XML document, or from the targeted XML fragment (when specified).
Only the following references are honored:
-
For itemref in the Package Document spine, the reference is defined by
the href attribute of the corresponding item element in the
manifest (i.e., that the itemref's idref attribute
references).
-
For [HTML]
iframes and embed
elements, references are defined by the src attribute
-
For the [HTML]
object element, the reference is defined by the data attribute
-
For [SVG]
image and use elements, references are defined
by the xlink:href attribute
note
This scheme does not take into account hyperlinks, only embedding references. Consequently, it is illegal to
follow links from the [HTML] (or [SVG]) a element.
3.1.4 Character Offset (:)
A path terminating with a leading colon (:) followed by an integer refers to a character
offset. The given character offset may apply to an element only if this element
is the [HTML]
img
element with an alt attribute containing the text to which the character offset applies.
For XML character data, the offset is zero-based and always refers to a position between characters, so
0 means before the first character and a number equal to the total UTF-16 length means after
the last character. A character offset value greater than the UTF-16 length of the available text must not be specified.
In this specification, the definition of an "offset" within XML character data is based on the UTF-16 text
encoding, whereby each "character" (Unicode code point) may be represented using
a single 16-bit code unit, or two units (surrogate pairs, for Unicode characters outside of BMP / Basic
Multilingual Plane) [Unicode]. A CFI "character offset" is a zero-based number that refers to a
position between UTF-16 code units. Here, the "length" of the text is the total count of 16-bit units. Offset zero
therefore means before the first 16-bit unit, and a number equal to the "length" of the text means after the last
16-bit unit. An offset value greater than the "length" of the text must not be
specified.
A character offset may follow a /N step. For XHTML Content
Documents, N would be an even number when referencing the alt text of an
img element, and N would be odd when referencing XML character data within
elements.
CFI expressions that terminate with an odd numbered /N step should include an explicit character offset. However, CFI processors (e.g., Reading Systems) must be capable of consuming (i.e., parse + interpret / render) such CFI expressions, by
assuming the implicit /N:0 character offset.
3.1.5 Temporal Offset (~)
A path terminating with a leading tilde (~) followed by a number indicates a temporal
position for audio or video measured in seconds.
3.1.6 Spatial Offset (@)
A path terminating with a leading at sign (@) followed by two colon-separated numbers
indicates a 2D spatial position within an image or video. The two numbers represent scaled locations in the
x and y axes, and must be in the range
0 to 100 regardless of the image's native or display dimensions (i.e., the
upper left is 0:0 and the lower right is 100:100).
3.1.7 Temporal-Spatial Offset (~ + @)
A temporal and a spatial position may be used together. In this case, the
temporal specification must precede the spatial one syntactically (e.g.,
[email protected]:97.6 refers to a point 23.5 seconds into a video in the lower left of the
frame).
3.1.8 Text Location Assertion ([)
An EPUB CFI may specify a substring that is expected to precede and/or follow
the encountered point, but such assertions must occur only after a character offset.
For example, the following expression asserts that yyy is expected immediately before the
encountered point using the sample content below:
An additional substring that follows the encountered point can be given after a comma. For example:
refers to the position marked by the asterisk:
If there is no preceding text, or only trailing text is specified, a comma must immediately precede the text assertion:
There is no restriction on the amount of the preceding and following text that can be included in the match.
Text is taken from the document ignoring element boundaries and white space is always collapsed (i.e., a non-empty
sequence of contiguous white space characters is always replaced with a single space character).
A Reading System can determine that the location referenced by the CFI is not the original intended location
(due to non-matching text), and can use the preceding/trailing text to compute the set of steps that reach the
desired destination in the content (see Intended Target Location Correction). The cost of this added robustness
is that comparison (and sorting) of CFI strings can be performed only after logically stripping all bracketed
substrings (see Sorting Rules).
3.1.9 Side Bias ([ + ;s=)
In some situations, it is important to preserve which side of a location a reference points to. For example,
when resolving a location in a dynamically paginated environment, it would make a difference if a location is
attached to the content before or after it (e.g., to determine whether to display the verso or recto side at a page
break).
The s parameter is used to preserve this sided-ness aspect of a location. It can take two
values: 'b' ("before") means that the location is attached to the content that precedes
(according to the XML serialization document order), 'a' ("after") refers to the content that
follows. This parameter must always be used inside square brackets at the end of
the CFI, even if the ID [XML] or text location assertion is empty.
The location just after yyy in the sample content
below can be expressed as belonging with the content before it as follows:
Equally, it can be expressed including a text location assertion as:
The location at the start of em element can be attached to the content preceding the
em element as follows:
If the side bias in the preceding example was set to a rather than b, the
location would be attached to the child content of the em element, not the content following the
em element.
Since side bias is expressed as a parameter, it does not participate in CFI comparison (see Sorting Rules).
Side is not defined for locations with spatial offset.
note
Side bias is only meaningful when some type of break falls at the location (e.g., a page break or line
break).
3.1.10 Examples
This section is informative
Given the following Package Document:
and the XHTML Content Document chapter01.xhtml:
Then the EPUB CFI:
refers to the position right after the digit 9 in the paragraph with the ID
para05. When producing CFIs for text locations, unless the text is defined by an
img element's alt tag, one should always
start with the reference to the (possibly-empty) chunk of XML character data that corresponds to the location and
then trace the ancestor and reference chain to the Package Document root.
The following examples show how EPUB CFIs can be constructed to reference additional content locations.
3.4 Simple Ranges
EPUB CFIs allow the expression of simple ranges extending from a start location to an end location. A range
must be expressed as a triple of parent path
(P), start subpath (S) and end
subpath (E), or of the form:
The parent path must not be empty, and must
end at a step that is common for resolving both the path of the start and end locations of the range, and each start
and end subpath must resolve to a location in non-decreasing order in the
document.
To determine the start and end locations of the range, the start and end subpaths must be concatenated to the parent path to create the start location path (PS) and
end location path (PE). The parent path should include the
deepest possible common path leading to both the start and end path (in other words, the start and end location
should not contain a common path). The start location may be empty, to avoid repetition of a common path in cases where the end location is situated within
the subtree rooted at the start location.
Using the sample documents above, the following range would represents
the text from the second y in yyy up to (and including) digit
3:
Ranges must be compared according to their PS, then
PE, components. The start and end locations should reference
points in the document that have the same "nature", that is to say elements and character offsets (document
structure), temporal offsets (timed media), spatial offsets (visual media), or the combined temporal-spatial offsets.
In the case of temporal offsets, the start and end locations should reference the
same timed media. In the case of spatial offsets, the start and end locations should reference the same visual media. This specification does not define expected behaviors, such as
how the combination of two spatial offsets (i.e., start and end locations within a visual media) is to be interpreted
by processing agents, including production tools and reading systems.
It is not valid to use a path to an element as a shorthand for the range from the beginning to the end of the
element. Single path notation always denotes a location point, and range is represented by the notation described
above. There is no special step to produce a reference to the end of an element, as that would make sorting
impossible without consulting the content of the document.
If range is used where single location is expected by the context, the start location must be used.
Side-bias parameters must not be used for ranges; the start of a range is
implicitly attached to the content after the start location and the end is implicitly attached to the content before
the end location.
3.5 Intended Target Location Correction
As an EPUB Publication can be updated, corrected or otherwise altered over time, it is useful to be able to
derive an EPUB CFI for the modified document from one that targeted a previous version. This specification provides
two mechanisms to detect and adapt to content changes that impact CFIs: IDs [XML] and text location assertions.
When a Reading System is processing a CFI, it should check the correctness of
any encountered assertions. For example, given the path /6/4[chap01ref]!…, the Reading System
should verify that the element has the ID matching chap01ref
when processing element 4 (for this example, an itemref in the
spine). If not, the Reading System should locate the ID
chap01ref within the document and correct the CFI (e.g., if a new itemref was
inserted before the chap01ref
itemref, the desired element number would now be 6 and the corrected CFI would be
/6/6[chap01ref]!…). Likewise, text location assertions should
be used to check referenced target locations, and used to derive a corrected CFI that targets the desired text
location.
If one of the assertions fails during processing, and a corrected CFI can not be derived (the ID is not found in
the document, or text matches could not be found), the CFI must be considered an
invalid reference. In cases where a Reading System cannot check for correctness (e.g., document-resident XML IDs are
not available at CFI processing time), a Reading System must ignore the CFI
assertions.
This notion of correcting CFIs can lead to circumstances where two different CFIs point to the same location
(i.e., the "stale" CFI, pre-correction, and the corrected CFI). The corrected CFI should be used where possible. A Reading System and any surrounding content management system should attempt to replace stale CFIs with their corrected versions where possible.
note
This specification encourages the development of custom functions to assist with CFI correction where the
intrinsic functionality is insufficient. Refer to Extending EPUB CFIs for more information on how to
develop such functionality.
