MobileRead Forums - View Single Post - epubsana — automatic repair for what epubcheck reports (not an editor)

Kayadelenium · 09-12-2026, 07:56 AM

epubsana 0.15.0

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

One new fixer, a change plugin authors will care about, and the media-type question from a few posts up.

A fragment that is real but has moved

The new fixer, thirty-seven in total. A link points at a #fragment that the target document does not define — but exactly one document in the book does define that anchor. The fragment did not die; it moved.

On real books this is almost always the same accident: an editor split a file at a page break, and a footnote link and its return link were left pointing into the wrong half. Ten links in one book on my shelf are in exactly that state: five notes and the five return links that go with them, each pointing at the wrong side of the same split. The repair writes the path of the document that actually holds the anchor in front of the fragment, relative to the referring document. Nothing else in the link changes. Where the anchor turns out to be in the referring document itself, the link becomes a plain same-document #fragment, which is what a bare fragment means.

What it declines is the more useful half, and it is most of the population:

An anchor defined in several documents. Which one the link meant is a guess, and a guess that silently relinks a footnote is worse than a broken link you can see.
An anchor defined nowhere in the book. The only repair available is to drop the fragment, and that throws away the author's target — the one piece of evidence about where the link was supposed to go.
A target the spine leaves out of the reading order, and a reference that is not visible as a whole quoted attribute value.

The last two decline nothing in my own library and are there anyway, because each of them names a defect the repair would otherwise create. That is the recurring lesson here: a repair that clears one finding and authors another can leave a book's error count unchanged, so a total is not evidence that anything got better.

For anyone reading the JSON

The summary now reports every counter it has a concept of, including zero. Under --dry-run it used to say applied 0, skipped 0 while every item in the same document was marked proposed — so the summary and the items disagreed about the size of the run, and a tool asking the summary how many fixes there were got zero while two sat in the list. Every number in it was true and the document still misled.

There is now a proposed counter beside applied and skipped, and this holds: applied plus skipped plus proposed equals the number of items.

The same gap one field over: only fatals and errors were counted, in a tool where some fixes clear a warning or a usage finding and move the error line not at all. All five severities are now reported, before and after. If you were inferring "nothing happened" from an unchanged error count, that inference was wrong and is now unnecessary.

Both are additive — nothing that was there has moved or changed meaning.

The font media type

JSWolf reported that the rename of application/vnd.ms-opentype to font/otf was wrong. I have answered that separately just above; the short version is that I went and checked, the rename follows EPUB 3.3's own table, and I was wrong to think otherwise at first.

One thing did change because of it. epubsana used to decide these renames from a small table of its own, written before epubveri started naming the preferred type itself. It now takes the replacement from the finding. That removes a real hazard rather than a theoretical one: with two tables there were inputs where epubsana would have named a replacement that epubveri had deliberately refused to name, because the file's own bytes ruled it out. No book in my library is in that state — this closes the hole rather than repairing damage — but the two tools can no longer disagree about what to write.

As always

Your original file is never touched: a repaired copy is written beside it, every fix is proposed 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/

And the ask is unchanged, because it is the only check this project has that is not circular: epubsana verifies its own repairs with epubveri, so it cannot see damage epubveri cannot see. If a repair leaves a book worse in a way that still validates, only someone opening the book will notice. Please say so if you do.

crates.io: https://crates.io/crates/epubsana — command-line binaries for Windows, macOS and Linux are on the releases page.

09-12-2026, 07:56 AM	#27
Kayadelenium Groupie Posts: 173 Karma: 363834 Join Date: Jul 2026 Location: Planet Earth Device: Kobo Forma	epubsana 0.15.0 https://github.com/veripublica/epubs...es/tag/v0.15.0 One new fixer, a change plugin authors will care about, and the media-type question from a few posts up. A fragment that is real but has moved The new fixer, thirty-seven in total. A link points at a #fragment that the target document does not define — but exactly one document in the book does define that anchor. The fragment did not die; it moved. On real books this is almost always the same accident: an editor split a file at a page break, and a footnote link and its return link were left pointing into the wrong half. Ten links in one book on my shelf are in exactly that state: five notes and the five return links that go with them, each pointing at the wrong side of the same split. The repair writes the path of the document that actually holds the anchor in front of the fragment, relative to the referring document. Nothing else in the link changes. Where the anchor turns out to be in the referring document itself, the link becomes a plain same-document #fragment, which is what a bare fragment means. What it declines is the more useful half, and it is most of the population: An anchor defined in several documents. Which one the link meant is a guess, and a guess that silently relinks a footnote is worse than a broken link you can see. An anchor defined nowhere in the book. The only repair available is to drop the fragment, and that throws away the author's target — the one piece of evidence about where the link was supposed to go. A target the spine leaves out of the reading order, and a reference that is not visible as a whole quoted attribute value. The last two decline nothing in my own library and are there anyway, because each of them names a defect the repair would otherwise create. That is the recurring lesson here: a repair that clears one finding and authors another can leave a book's error count unchanged, so a total is not evidence that anything got better. For anyone reading the JSON The summary now reports every counter it has a concept of, including zero. Under --dry-run it used to say applied 0, skipped 0 while every item in the same document was marked proposed — so the summary and the items disagreed about the size of the run, and a tool asking the summary how many fixes there were got zero while two sat in the list. Every number in it was true and the document still misled. There is now a proposed counter beside applied and skipped, and this holds: applied plus skipped plus proposed equals the number of items. The same gap one field over: only fatals and errors were counted, in a tool where some fixes clear a warning or a usage finding and move the error line not at all. All five severities are now reported, before and after. If you were inferring "nothing happened" from an unchanged error count, that inference was wrong and is now unnecessary. Both are additive — nothing that was there has moved or changed meaning. The font media type JSWolf reported that the rename of application/vnd.ms-opentype to font/otf was wrong. I have answered that separately just above; the short version is that I went and checked, the rename follows EPUB 3.3's own table, and I was wrong to think otherwise at first. One thing did change because of it. epubsana used to decide these renames from a small table of its own, written before epubveri started naming the preferred type itself. It now takes the replacement from the finding. That removes a real hazard rather than a theoretical one: with two tables there were inputs where epubsana would have named a replacement that epubveri had deliberately refused to name, because the file's own bytes ruled it out. No book in my library is in that state — this closes the hole rather than repairing damage — but the two tools can no longer disagree about what to write. As always Your original file is never touched: a repaired copy is written beside it, every fix is proposed 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/ And the ask is unchanged, because it is the only check this project has that is not circular: epubsana verifies its own repairs with epubveri, so it cannot see damage epubveri cannot see. If a repair leaves a book worse in a way that still validates, only someone opening the book will notice. Please say so if you do. crates.io: https://crates.io/crates/epubsana — command-line binaries for Windows, macOS and Linux are on the releases page.