[GUI Plugin] kepubverto

[Kayadelenium]

kepubverto for calibre converts the EPUBs in your calibre library to KEPUB with kepubverto, and adds the KEPUB to each book beside its EPUB. Your EPUB is not changed.

Why it exists. kepubverto adds what a Kobo needs for reading statistics, faster page turns and the proper progress bar, and nothing else: it inserts its markup into each chapter, leaves every other byte of that chapter as it was, and copies the files it does not convert unchanged. A book that was valid before the conversion is still valid after it. calibre can already make KEPUBs itself, through its Kobo driver and its KEPUB output format, but its conversion rewrites the book on the way. This plugin hands kepubverto the EPUB file exactly as it sits in your library, and never sends it through calibre's conversion pipeline.

Why it is safe to point at your library

• The EPUB is only read. The KEPUB is written to a temporary folder and then added to the book as calibre's KEPUB format.
• A book that already has a KEPUB keeps it, unless you tick Replace an existing KEPUB in the settings. A KEPUB you made on purpose, with other options or another tool, is never replaced silently.
• A chapter kepubverto cannot convert safely is copied unchanged, and the report names it. The KEPUB is never worse than the EPUB it came from.
• Converting the whole library always asks first, with the number of books.

What I measured. On my 562-book shelf, with calibre 9.16 and epubveri 0.28.0 checking every book before and after, calibre's Kobo driver conversion (the one that runs when it sends a book to the device) added at least one error to 546 of the 561 books it converted, and every one of the 252 books that were valid before came out invalid. Most of it is markup EPUB 2 does not allow and a kobo.js script added to every chapter of an EPUB 3 book without declaring it. kepubverto 0.2.0 on the same shelf made no book worse. I have not measured calibre's KEPUB output format (Convert books, output KEPUB) on the whole shelf. I have tried it on one book, Jane Austen's Emma, valid before the conversion: calibre 9.17's KEPUB came out with 61 errors in epubcheck 5.4.0, all the same one (the kobo.js script in every chapter, undeclared), and kepubverto's with none. That is one book, not a measurement of how many it affects. To see it on your own books, check a KEPUB from each with epubveri or epubcheck.

In the toolbar menu

• Convert the selected books to KEPUB, or Convert the whole library to KEPUB.
• Save the KEPUB as .kepub.epub: saves the selected books' KEPUBs to a folder you choose. calibre stores the format as KEPUB and its own Save to disk names the file .kepub; .kepub.epub is the name a Kobo uses. calibre's Kobo driver already gives the file that name when it sends it to the device.
• Show the last report, Clear the marks it left, Stop the running conversion and Settings.

The conversion runs as a background job, so calibre stays usable, and stopping it keeps what is already converted. When every book converted cleanly the status bar says so; otherwise a report opens with one row per book, what needs a look first: not converted (with kepubverto's own reason), converted with chapters left as they were, skipped because there is no EPUB or there is already a KEPUB. Show in library filters calibre's book list to those books, and Copy puts the report on the clipboard with the date and the plugin, kepubverto, calibre and system versions, so a report posted here can be compared with your own.

Settings

• Hyphenation: as the book says, on, or off.
• Your own CSS, added after kepubverto's rules. kepubverto refuses CSS that refers to a file, has @font-face, or would add a finding epubveri reports, and the report shows its reason.
• Replace an existing KEPUB: off by default.
• How many books are converted at the same time. The default uses most of your processor's cores and leaves two for calibre and the rest of the system.
• Check for a newer kepubverto: at most once an hour, never during a conversion.

Nothing is bundled, and nothing is trusted blindly. The plugin contains no binary. On first use it downloads the kepubverto build for your platform from kepubverto's own GitHub releases, verifies it against that release's published SHA256SUMS.txt before extracting anything, and checks it again before every run. kepubverto 0.3.0 or later is required; the plugin downloads the latest.

Installing. Download the zip attached to this post, then Preferences / Plugins / Load plugin from file, and restart calibre. If the kepubverto button does not appear, add it under Preferences / Toolbars & menus. calibre 6.0 or later is required. I have tested it on calibre 9.17 on macOS; reports from Windows and Linux are very welcome.

What would help

• Your device. Send a converted book to your Kobo and tell me whether reading position, progress and page turns behave.
• A book that came out wrong. Your EPUB is untouched, so you can compare the two; epubveri or epubcheck will check the KEPUB.
• Anything about the plugin itself: the menu, the report, the settings, installing.

Where to report what. Anything about this plugin belongs in this thread or at https://github.com/veripublica/calibre-plugins/issues. A question about the conversion itself, what kepubverto does to a book, belongs in the kepubverto thread, https://www.mobileread.com/forums/sh...d.php?t=375668.

Links

• Releases and changelog: https://github.com/veripublica/calibre-plugins/releases (take the release tagged kepubverto-)
• Source, GPL-3: https://github.com/veripublica/calibre-plugins
• kepubverto itself: https://github.com/veripublica/kepubverto

Plugin Download

[Kayadelenium]

0.1.1: a proper icon

The first release went out with a placeholder arrow. 0.1.1 replaces it with the real icon: a k on a book drawn the way calibre draws its own toolbar books. Nothing else changed; converting works exactly as in 0.1.0.

The k comes from KF Libron, Nico Verbruggen's font for e-readers in its Kobo build (SIL Open Font License). I tried a k inside two turning arrows as well, but at toolbar size the arrows turned into an O, and the k alone was the only one still readable at 16 pixels.

The zip in the first post is now 0.1.1. Install it from there as before (Preferences / Plugins / Load plugin from file) and restart calibre; your settings are kept.

[JSWolf]

I've found an issue.

You have convert the selected books and convert the entire library next to each other. It's too easy to accidentality select to convert the entire library. It's a good idea to remove the option to convert the entire library. It's easy enough to select the entire library and then convert the selected books. That way it prevents the entire library getting converted when it's not supposed to be.

To convert the entire library, all you have to do is select one book, hit CTRL-A and them convert all of the selected books.

[Kayadelenium]

JSWolf, thank you, that is a fair point about the two convert items sitting next to each other.
I would rather keep the whole-library item, though: some people want to convert everything at once, and it is not quite the same as CTRL-A. CTRL-A selects only the books on screen, so a search or a virtual library limits it; the menu item takes every book in the library.

0.1.2 is out, now in the first post. It makes the item hard to pick by mistake instead:

• It moves to its own section of the menu, between separators, away from Convert the selected books.
• Its question now says "the whole library" and the number of books.
• That question's default button is No, so pressing Enter out of habit does not start it.

It already asked before starting; it still does, and so does any selection of more than 20 books. Nothing is converted without that answer, and the EPUBs are never changed either way.

[JSWolf]

Originally Posted by Kayadelenium

CTRL-A selects only the books on screen, so a search or a virtual library limits it; the menu item takes every book in the library.

A CTRL-A does select all of the books. The 1st image shows 1 selected. The 2nd shows what happens after a CTRL-A without a virtual library.

I don't see anyone in a virtual library wanting to convert the entire library to KePub. I can see wanting to convert the entire virtual library.

But as long as you cannot accidentally select to convert the entire library, that will do. But one last thing, I cannot see someone hitting CTRL-A and then selecting to convert to KePub.