Specification · §7
Locators and annotations
How a place in a book, and a highlight, is recorded so that every device finds it.
7. Locators and annotations
Locations in a book are Readium Locators, and annotations are modeled on W3C Web Annotations, with a Locator as their target and the note as a Markdown string, rather than the model's selectors and body resources. Exporting them as W3C annotations maps the Locator's quote to a TextQuoteSelector, as Readium Annotations does.
Progress, as progress.updated logs it (§5.3). It's a point, so its quote is the text after it:
{
"edition": "01j9xk2m4n6p8q0r2s4t6v8w0y",
"locator": {
"href": "OEBPS/chapter-03.xhtml",
"type": "application/xhtml+xml",
"locations": {
"progression": 0.42,
"totalProgression": 0.18,
"x-koreader-xpointer": "/body/DocFragment[5]/body/p[12]/text().0"
},
"text": {
"before": "said the Reverend Mother. ",
"highlight": "",
"after": "He who controls the spice"
}
}
}
Locators:
- Fields are Readium's:
href,type,locations {progression, totalProgression, position, fragments, partialCfi, domRange}, andtext {before, highlight, after}. - Every stored Locator has
hrefandprogression, and atextquote whenever there's text at the location (an image has none), and is stored with the ID of itsedition. Everything else is optional. - The quote:
highlightis the selected text, empty or left out for a point, such as a bookmark, andbeforeandafterare up to 32 characters each, counted as below. - An audiobook's progress is a Locator into its audio file, with its time in
fragmentsast=seconds, and no quote (§9). - A writer that can't get the quote from its renderer takes the text at
progressionin the resource, from the first word that starts there or after. - Each reader converts its renderer's locations to and from Locators.
- A resource's text is its
<body>'s text as the DOM'stextContentgives it, without<script>and<style>.progressionis where the location is in it, in characters, divided by its length. hrefis the resource's path from the EPUB's root, without a leading/, percent-encoded as a URL path is: every byte but ASCII letters, digits, and-._~/as%XX, in uppercase hex. Readers decode it before comparing. An audiobook's is its file's name in the edition's folder (§9), encoded the same way.- Counting: offsets and
progressioncount the characters of a resource's text, with these rules:- a character is a Unicode scalar value (a code point that isn't a surrogate), not a UTF-16 unit or a byte: in JavaScript, count
[...text], nottext.length - runs of whitespace collapsed to one space, and the ends trimmed. Whitespace is Unicode's
White_Spaceproperty, so a no-break space (U+00A0) is whitespace too, which Lua's%sdoesn't match - C1 control characters (U+0080–U+009F) read as the Windows-1252 characters they stand for, as HTML parsers read the reference
€as "€" where XML keeps the control character. This is the format's normalization, for counting; renderers needn't agree on it. The five with none (U+0081, U+008D, U+008F, U+0090, U+009D) stay as they are, one character each
- a character is a Unicode scalar value (a code point that isn't a surrogate), not a UTF-16 unit or a byte: in JavaScript, count
- The quote is what has to match, not the offset: renderers extract text differently, so offsets from two renderers can differ for the same place. A web view's
textContenthas no break between</p><p>, for example, where crengine puts a newline. - Renderer extras go in
locationswith anx-prefix: KOReader's crengine XPointers (x-koreader-xpointer,x-koreader-xpointer-end), the kepub span Kobo's reader saves (x-kobo-span, such askobo.108.1), and a reader's own offsets. They're hints for the same edition: use one only if the text at it still matches the quote. - A page is a Readium position, as Readium's
ArchiveEntryLengthstrategy counts them, with 1,024 bytes: one for every 1,024 bytes of each resource in the reading order, as compressed in the EPUB, rounded up, or one per resource in a fixed-layout edition. Every resource in the spine counts,linear="no"ones too, each with at least one position and at most 100,000. They're numbered from 1 through the edition, aspositionhas it. It's the same on every device and in any layout, though not after the EPUB is zipped again with other compression, and an edition's page count is its number of positions. A page a renderer lays out on screen is only shown, never stored or counted.
Annotations:
- Shape:
targetis a Locator into the annotation'sedition;bodyis the note; andmotivationishighlightingorbookmarking. A highlight with a note is stillhighlighting: the note is itsbody. - Re-anchoring looks in the Locator's resource for each place its
highlightis, or for a point, itsbeforeandaftertogether, else either alone. Of those, the one whose surroundings agree withbeforeandafterover the most characters wins, then the one nearestprogression; with none, it stays atprogression, and isn't exact. Finding it by its quote, rather than its offset, is what lets an annotation find its place when the EPUB is replaced by a corrected one. An annotation that can't be anchored is flagged, never dropped. - Colors are yellow, green, blue, pink, and purple. A reader with other colors maps them onto these: red to pink; orange and gray to yellow; olive to green; and cyan to blue.