epubsana — automatic repair for what epubcheck reports (not an editor)

[Kayadelenium]

epubsana 0.30.0 is out today. It also brings 0.29.0, from earlier today, which I did not post about separately.

https://github.com/veripublica/epubs...es/tag/v0.30.0

As before: your original file is never modified, and the repaired copy is written beside it. Every fix is shown to you before it is made, and the run ends with a report of exactly what changed. The browser version needs no install and uploads nothing: https://veripublica.github.io/epubsana/

Most of what is new came from books that epublift had upgraded from EPUB 2 to EPUB 3. Each one is also a defect a book can carry without any upgrade.

Named characters that stopped a file from opening

A file that uses a named character such as emsp, thinsp, rarr or a Greek letter, without a DTD that declares it, cannot be read by a reading system that reads the file as XML. epubsana replaced these names with the characters they stand for, but it only knew 117 of them. It now knows every name the XHTML 1.x DTDs declare, so the em space and its relatives are repaired too. A name outside that set is still left alone.

Files declared as HTML

Some books declare a chapter as text/html in the manifest when the file is really XHTML. In EPUB 2 that is a warning. In EPUB 3 it is an error, and the chapter is in the reading order with nothing to fall back on. epubsana now declares such a file application/xhtml+xml, but only after checking that the file reads as XML with an XHTML html root. A file that is real HTML is left alone, because it needs converting, not relabelling. The file itself is not changed.

One thing to expect: the report can end with more errors than it started with. epubveri never fully checks a file declared text/html. In EPUB 3 it does not open the file at all, and in EPUB 2 it does not check the file's ids. Once the declaration is right, the file is checked for the first time, and whatever was wrong in it all along shows up. epubsana says so at the end of the run. Run it again on the repaired copy to repair what it can; for example, an empty title it found in a chapter it could not read before.

A script that points at nothing

Some books carry a script element whose file is not in the book. In my library it is always Kobo's kobo.js. epubsana now offers to delete the element, and to remove the scripted declaration from the manifest if nothing else in the file needs it. It asks first, and here is why: I do not know whether a Kobo device supplies its own kobo.js to a book that names it. If you know, I would like to hear it. A script element with code inside, or one whose file is in the book under another path, is left alone.

Smaller repairs

• A space in a link or image reference inside a chapter is encoded as %20. That still names the same file, so nothing is renamed. Before proposing it, epubsana checks with epubveri that the reference is then accepted.
• An anchor target wrapped around a link (an a with only an id around a real link) was already repaired in EPUB 2. It is now repaired in EPUB 3 too.
• From 0.29.0: an empty optional Dublin Core element (dc:rights, dc:source and the like) was already dropped in EPUB 2. It is now dropped in EPUB 3 too, where it is an error. Title, identifier and language are never touched.

For plugin authors

New fix_ids: fix.content_url_spaces (AutoSafe, so --auto-safe applies it), fix.html_media_type and fix.missing_script (both ConfirmNeeded, so they are always asked). The EPUB 3 anchor and Dublin Core repairs keep their old fix_ids, fix.nested_anchor and fix.empty_metadata_element. For anyone using the Rust crate directly: entities::TABLE is gone, and entities::lookup now returns a char.

The ask

Same as always. epubsana checks its own repairs with epubveri, so it cannot see damage epubveri cannot see. If a repair leaves one of your books worse, please tell me here. The same goes for a book that is still reported valid when epubcheck disagrees.

Command-line binaries for Windows, macOS and Linux are on the releases page.

https://crates.io/crates/epubsana
https://www.npmjs.com/package/@verip.../epubsana-wasm

[JSWolf]

Originally Posted by Kayadelenium

Agreed, and that is the order epubsana fills an empty title in. It takes the file's entry in the book's table of contents first, then the file's own first heading, and only then the book's title, which you argued for earlier. So a chapter gets the most specific name the book itself gives it. The book's title is the last resort, for a file nothing else names.

What it does not do is replace a title that is already there, such as c01. No validator reports that title as a defect, and picking a better name is a choice for whoever edits the book. epubsana only repairs what epubveri reports.

Which read-aloud programs read the title? If you can name one, I will test how it handles each of those three sources.

Balabolka can read the <title>.
https://www.cross-plus-a.com/btext.htm

TTS Reader by Librera (Android)

EPUBReader + Read Aloud (for Chrome/Edge/Firefox)

Thorium Reader (Windows)