Readwyn 0.1.0

EPUB 2 or EPUB 3: what changes when your books are converted

Readwyn’s reader opens EPUB 3, so when you add an EPUB 2 book (2.0 or 2.0.1) it leaves your file alone and makes an EPUB 3 copy beside it. The package and the chapter markup are brought up to EPUB 3; the text, every file path, the images and the fonts stay as they were.

Inside the copy

Each chapter becomes valid EPUB 3 XHTML, and the book gains an EPUB 3 navigation document plus a new NCX (the EPUB 2 form of the table of contents) built from the old one. Images, fonts and style sheets keep their bytes. So does the book’s unique identifier, because the obfuscation of embedded fonts depends on it.

Five real EPUB 2.0 books and five real EPUB 2.0.1 books make up the test set. In every copy the file paths and the text match the original, and epubcheck finds no errors. OEB packages, the format that came before EPUB, go through the same conversion and keep every file path too (What is an OEB package, and how to open one).

Your EPUB 2 stays the “Original” in the Details tab; it’s the copy that the reader opens and “Send to device” sends. An EPUB 3 that you add gets no copy: Readwyn checks it once, notes that it needs no conversion, and reads it as it is.

Highlights, on the Mac and on a Kobo

Because the two files have the same chapters, with the same text in each, a highlight works in either of them. Highlight a passage on the Mac, in the EPUB 3, and it still points to the same words in your EPUB 2.

That matters when a Kobo holds a KEPUB made from the EPUB 2. When Readwyn syncs with a Kobo, it looks at the version in each KEPUB’s package, 2.0 or 3.0, and maps the highlight positions through the file of that version in your library:

  • The library has that version. Positions go through that file. A highlight made on the Mac carries over to the EPUB 2 original, and so to the KEPUB made from it.
  • The library doesn’t have that version. Readwyn matches the chapters by their text, and positions only carry over through the text the two chapters share at their start or their end.

Readwyn never rewrites a KEPUB on the device to make the positions line up. It doesn’t need to: a book that’s already on the Kobo still maps through the EPUB 2 in your library.