Skip to content
Boeks

Appearance

Theme

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}, and text {before, highlight, after}.
  • Every stored Locator has href and progression, and a text quote whenever there's text at the location (an image has none), and is stored with the ID of its edition. Everything else is optional.
  • The quote: highlight is the selected text, empty or left out for a point, such as a bookmark, and before and after are up to 32 characters each, counted as below.
  • An audiobook's progress is a Locator into its audio file, with its time in fragments as t= seconds, and no quote (§9).
  • A writer that can't get the quote from its renderer takes the text at progression in 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's textContent gives it, without <script> and <style>. progression is where the location is in it, in characters, divided by its length.
  • href is 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 progression count 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], not text.length
    • runs of whitespace collapsed to one space, and the ends trimmed. Whitespace is Unicode's White_Space property, so a no-break space (U+00A0) is whitespace too, which Lua's %s doesn't match
    • C1 control characters (U+0080–U+009F) read as the Windows-1252 characters they stand for, as HTML parsers read the reference &#128; 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
  • 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 textContent has no break between </p><p>, for example, where crengine puts a newline.
  • Renderer extras go in locations with an x- prefix: KOReader's crengine XPointers (x-koreader-xpointer, x-koreader-xpointer-end), the kepub span Kobo's reader saves (x-kobo-span, such as kobo.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 ArchiveEntryLength strategy 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, as position has 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: target is a Locator into the annotation's edition; body is the note; and motivation is highlighting or bookmarking. A highlight with a note is still highlighting: the note is its body.
  • Re-anchoring looks in the Locator's resource for each place its highlight is, or for a point, its before and after together, else either alone. Of those, the one whose surroundings agree with before and after over the most characters wins, then the one nearest progression; with none, it stays at progression, 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.