Possible replacement for EPUBCHECK - Page 20

Kayadelenium · Yesterday, 06:01 AM

A question for the thread: what should a validator do with the findings that are not errors?

Two of you have now reported the same thing from three different directions, and I would rather ask you than keep guessing. This is not a bug report I am answering — it is a design choice I have not made yet, and it is easier to change before people rely on it than after.

What happened

epubcheck sorts its findings into fatal, error, warning, info and usage, and hides the usage ones unless you pass -u. A usage finding is not a defect: it names something your book does, so that you can decide. Ours are the same messages with the same ids.

JSWolf, #206 / #209 — CSS-028 on correct @font-face: "It looks like an error message. It really should not be showing a place in the eBook that's correct." We were showing usage by default; epubcheck was not.
JSWolf, #271 — after I matched epubcheck and hid them, the unused-image note went with them, and it read as a check that does not work.
DNSB, #283 — the reverse again: our plugin showed OPF-088 on a nav, epubcheck showed nothing, and it looked like the two tools disagreed. They do not — epubcheck reports the identical message with -u, at the same line.

The same person asked for less and then for more. That is not anybody being inconsistent; it is a sign I have been adjusting the wrong dial.

How big it actually is

I measured it rather than guessed, on the 474 books I keep for regression testing:

219 of them have no error, warning or fatal at all — the books where epubcheck prints "No errors or warnings detected".
80 of those 219 (37%) still fill my plugin's panel with usage or advisory lines. That is 17% of the shelf.
Median 4 lines on such a book; the worst has 527.
Almost all of it is three ids: OPF-088 (3768 lines), OPF-086b (422), CSS-028 (265).

So DNSB did not find an unusual book. Roughly one book in six does this.

The part that is my fault, plainly

I keep asking this thread for "a book where epubveri reports something epubcheck does not". My own plugins show usage by default and epubcheck hides it, so anyone who does what I asked is guaranteed to find differences that are not differences. I built that and then invited people to walk into it.

And I got a fact wrong in my own code. The comment justifying "show everything" in my Sigil plugin says Sigil's results panel has a Type column, so every line says what it is. It does not. Sigil's panel has four columns — File, Line, Offset, Message — and the severity is carried only by the row's background tint: pale cyan for info, cream for warning, pale pink for error. When the panel holds a single row, as DNSB's did, that tint has nothing to be compared against and carries no information at all. My calibre plugin does have a real Type column, which is why this surfaced on Sigil first.

The options

1. Match epubcheck: hide usage and advisory by default, and print one line saying what was hidden — e.g. "3 usage notes and 1 advisory hidden — see settings".
Diffing the two tools then gives the same report from both, which is the whole reason people compare them. The summary line is what stops it becoming JSWolf's #271 again: you can still see that something is there.

2. Keep showing everything, but stop it looking like a finding — a separator, an indent, a different wording, the notes always last.
Nothing is hidden, so nobody has to discover a setting. But on Sigil I have only four columns and a background tint to work with, so how much I can really change is limited, and a cross-tool diff still shows differences that are not differences.

3. Two lists — defects in the panel, notes somewhere else.
Cleanest to read and the most work; on Sigil I am not sure it is possible at all, since a plugin gets one results table and nothing else.

4. Leave it and document it better.
I am listing this because it should be listed, but I do not believe in it: Doitsu told JSWolf in plain words that it was a usage message and not an error, and the next post still said it looks like an error message. Explaining harder has been tried.

Where I lean, and why

Option 1. It is the only one where somebody following my own request produces zero false reports, and it is the least work by a distance — both plugins already have the filter and the settings; it is a changed default plus one summary line. It also puts the two plugins and the command line on one behaviour, which is one fewer thing to explain.

What I dislike about it: a setting on Sigil lives in a JSON file with no interface, so "see settings" is a real errand rather than a checkbox. That is exactly why the summary line is not optional — without it, a hidden note is indistinguishable from no note, and silence is the one failure a user cannot notice.

Two things will not change whichever way this goes:

It is a display filter, never a change to what the validator finds. epubsana — the repair tool — calls the library directly and is never filtered, and three of its repairs act on findings below error severity. Hiding a line from a panel must never make a repair quietly stop working.
Advisory findings never move the verdict. A book that passes epubcheck passes epubveri. That is not up for a vote.

Please answer for the shape, not for this case

One thing worth saying before you answer, because it changes what a good answer looks like.

This is not really a question about OPF-088 in a Sigil panel. Whatever comes out of it becomes the rule for the command line, for both of my plugins, for epubsana (the repair tool that reads epubveri's findings), and for whatever integrations come after — an editor, a conversion pipeline, somebody else's tool. I would rather take an answer that still makes sense in a place none of us is looking at yet than the perfect answer for the one panel this came up in.

And being straight about the timeline, because it is part of the question. epubveri is what I work on every day at the moment, and that is exactly why it is moving fast enough to keep bothering you. It will not stay that way: once it is mature the daily work moves to another Rust project, and epubveri settles into being maintained rather than rebuilt. That is the normal shape of it, and it is the shape anyone integrating it wants — I am not going anywhere, but the pace of change should drop, and it should drop on purpose rather than because I got distracted.

The practical consequence is the same for you as for me. Every time I have to come back and change a default, it lands on people who had already learned the old one — that cost is yours, not mine. My side of it is only that the project I am on at that moment stops while I do it. Both get smaller the fewer times I have to return, which is why I would rather spend a week asking now than change this twice over the next year.

So if your answer is "this, and here is why it would still be right in an editor I have never used", that is worth far more to me than a vote.

What would help

You are the ones reading these panels on real books:

Which option would you actually want, and does it change if you are in Sigil rather than calibre?
When you open a book, are you asking "is this valid" or "tell me everything about this book"? I suspect different people want different ones and that is the real split.
If usage notes were hidden by default, would a one-line summary be enough for you to go and find them?
And the one I would most like answered: can you think of a workflow where the answer you just gave would be the wrong one? A conversion pipeline, a batch check over a whole library, somebody reading the output as a machine rather than a person. If a choice breaks down somewhere, I would rather hear it now than ship it and find out.

No hurry from my side. Nothing is broken while this is open — the fix for the report that started it is already out as 0.13.6, and this is only about what the panel shows. I would rather decide it once, slowly, and then leave it alone.

Kayadelenium · Yesterday, 11:47 AM

epubveri 0.13.7 — https://github.com/veripublica/epubv...es/tag/v0.13.7

One fix. An element whose entire content is a NO-BREAK SPACE was treated as empty here, and epubcheck does not treat it that way: Rust's trim counts * as whitespace, while XML's whitespace is four characters and does not include it.

Four checks read it the wrong way — an empty <dc:title> (OPF-055), any empty <dc:*> (OPF-072), an NCX <navLabel> (NCX-006), and a content document's <title> (RSC-005). The last one is an error, so a book epubcheck passes was reported invalid here. That is why this went out on its own rather than waiting for the end of the day.

Settled against epubcheck 5.3.0, one book per case, with an ordinary space as the control — both tools still report that one.

Nothing here could have found it: no book on my 474-book shelf holds such an element, and the 981-scenario corpus is unchanged either way. It came from epubsana, the repair tool, whose session read this source and asked a question it could not test and I could.

patrik · Today, 04:57 AM

In the beginning of this thread, I made a quick&dirty script that recursively went through all my epubs, run checkdsk and yours, and when number of errors/warnings differed, added to a log. Running over night, it found none! My script was obviously faulty... :-) I have been meaning to redo it, but never got around to it.

Considering your skills, maybe you can create such a script for us? You know exactly what info is valueable to you and can create logs etc. (without any privacy info)

Just a thought... :-)

Kayadelenium · Today, 11:03 AM

epubveri 0.14.0 — https://github.com/veripublica/epubv...es/tag/v0.14.0

No finding, ID, severity or position changes in this release. The corpus is unchanged — 603/603 exact-ID matches, no false positives on the 355 should-be-clean cases — and all 474 books on my reference shelf report byte-identically. If you only use the command line and read the human output, there is nothing here for you and you can skip the rest.

What changed is the JSON. Two things, both of which existed to stop the output making a claim it could not back.

Every count is now present, including zero. fatal, info and usage used to be dropped from summary when they were zero. That turned "the key is missing" into "this book has no usage findings", which is a false statement rather than an ambiguous one — you could not tell an absent count from an absent feature. A clean book now reports all five.

And the output says when it has been filtered. Without -u the usage findings are held back, exactly as epubcheck does — but until now the JSON gave no sign of it, so a "usage": 0 could mean either "none found" or "not shown". There is now a "suppressed": ["usage"] beside the counts saying which. It records that the filter was on, not that something was actually hidden, because the question it answers is "can I trust this number?".

Both come from the shared output convention the veripublica tools follow, which moved to 0.5.0; the convention field in the envelope says 0.5 now. Nothing was removed, so a reader that used summary.usage still works.

One thing under the surface, mentioned only because it touches the zip reader: 18 dependencies moved up, and one of them changed how the archive is decompressed. That is the part of the code every single book goes through, so rather than trust it I re-ran the whole reference shelf — 474 books, byte-identical output — and the corpus with it.

If you build from source: the minimum Rust is unchanged at 1.88, and it is now actually tested rather than only claimed.

Yesterday, 06:01 AM	#286
Kayadelenium Zealot Posts: 144 Karma: 211110 Join Date: Jul 2026 Location: Planet Earth Device: Kobo Forma	A question for the thread: what should a validator do with the findings that are not errors? Two of you have now reported the same thing from three different directions, and I would rather ask you than keep guessing. This is not a bug report I am answering — it is a design choice I have not made yet, and it is easier to change before people rely on it than after. What happened epubcheck sorts its findings into fatal, error, warning, info and usage, and hides the usage ones unless you pass -u. A usage finding is not a defect: it names something your book does, so that you can decide. Ours are the same messages with the same ids. JSWolf, #206 / #209 — CSS-028 on correct @font-face: "It looks like an error message. It really should not be showing a place in the eBook that's correct." We were showing usage by default; epubcheck was not. JSWolf, #271 — after I matched epubcheck and hid them, the unused-image note went with them, and it read as a check that does not work. DNSB, #283 — the reverse again: our plugin showed OPF-088 on a nav, epubcheck showed nothing, and it looked like the two tools disagreed. They do not — epubcheck reports the identical message with -u, at the same line. The same person asked for less and then for more. That is not anybody being inconsistent; it is a sign I have been adjusting the wrong dial. How big it actually is I measured it rather than guessed, on the 474 books I keep for regression testing: 219 of them have no error, warning or fatal at all — the books where epubcheck prints "No errors or warnings detected". 80 of those 219 (37%) still fill my plugin's panel with usage or advisory lines. That is 17% of the shelf. Median 4 lines on such a book; the worst has 527. Almost all of it is three ids: OPF-088 (3768 lines), OPF-086b (422), CSS-028 (265). So DNSB did not find an unusual book. Roughly one book in six does this. The part that is my fault, plainly I keep asking this thread for "a book where epubveri reports something epubcheck does not". My own plugins show usage by default and epubcheck hides it, so anyone who does what I asked is guaranteed to find differences that are not differences. I built that and then invited people to walk into it. And I got a fact wrong in my own code. The comment justifying "show everything" in my Sigil plugin says Sigil's results panel has a Type column, so every line says what it is. It does not. Sigil's panel has four columns — File, Line, Offset, Message — and the severity is carried only by the row's background tint: pale cyan for info, cream for warning, pale pink for error. When the panel holds a single row, as DNSB's did, that tint has nothing to be compared against and carries no information at all. My calibre plugin does have a real Type column, which is why this surfaced on Sigil first. The options 1. Match epubcheck: hide usage and advisory by default, and print one line saying what was hidden — e.g. "3 usage notes and 1 advisory hidden — see settings". Diffing the two tools then gives the same report from both, which is the whole reason people compare them. The summary line is what stops it becoming JSWolf's #271 again: you can still see that something is there. 2. Keep showing everything, but stop it looking like a finding — a separator, an indent, a different wording, the notes always last. Nothing is hidden, so nobody has to discover a setting. But on Sigil I have only four columns and a background tint to work with, so how much I can really change is limited, and a cross-tool diff still shows differences that are not differences. 3. Two lists — defects in the panel, notes somewhere else. Cleanest to read and the most work; on Sigil I am not sure it is possible at all, since a plugin gets one results table and nothing else. 4. Leave it and document it better. I am listing this because it should be listed, but I do not believe in it: Doitsu told JSWolf in plain words that it was a usage message and not an error, and the next post still said it looks like an error message. Explaining harder has been tried. Where I lean, and why Option 1. It is the only one where somebody following my own request produces zero false reports, and it is the least work by a distance — both plugins already have the filter and the settings; it is a changed default plus one summary line. It also puts the two plugins and the command line on one behaviour, which is one fewer thing to explain. What I dislike about it: a setting on Sigil lives in a JSON file with no interface, so "see settings" is a real errand rather than a checkbox. That is exactly why the summary line is not optional — without it, a hidden note is indistinguishable from no note, and silence is the one failure a user cannot notice. Two things will not change whichever way this goes: It is a display filter, never a change to what the validator finds. epubsana — the repair tool — calls the library directly and is never filtered, and three of its repairs act on findings below error severity. Hiding a line from a panel must never make a repair quietly stop working. Advisory findings never move the verdict. A book that passes epubcheck passes epubveri. That is not up for a vote. Please answer for the shape, not for this case One thing worth saying before you answer, because it changes what a good answer looks like. This is not really a question about OPF-088 in a Sigil panel. Whatever comes out of it becomes the rule for the command line, for both of my plugins, for epubsana (the repair tool that reads epubveri's findings), and for whatever integrations come after — an editor, a conversion pipeline, somebody else's tool. I would rather take an answer that still makes sense in a place none of us is looking at yet than the perfect answer for the one panel this came up in. And being straight about the timeline, because it is part of the question. epubveri is what I work on every day at the moment, and that is exactly why it is moving fast enough to keep bothering you. It will not stay that way: once it is mature the daily work moves to another Rust project, and epubveri settles into being maintained rather than rebuilt. That is the normal shape of it, and it is the shape anyone integrating it wants — I am not going anywhere, but the pace of change should drop, and it should drop on purpose rather than because I got distracted. The practical consequence is the same for you as for me. Every time I have to come back and change a default, it lands on people who had already learned the old one — that cost is yours, not mine. My side of it is only that the project I am on at that moment stops while I do it. Both get smaller the fewer times I have to return, which is why I would rather spend a week asking now than change this twice over the next year. So if your answer is "this, and here is why it would still be right in an editor I have never used", that is worth far more to me than a vote. What would help You are the ones reading these panels on real books: Which option would you actually want, and does it change if you are in Sigil rather than calibre? When you open a book, are you asking "is this valid" or "tell me everything about this book"? I suspect different people want different ones and that is the real split. If usage notes were hidden by default, would a one-line summary be enough for you to go and find them? And the one I would most like answered: can you think of a workflow where the answer you just gave would be the wrong one? A conversion pipeline, a batch check over a whole library, somebody reading the output as a machine rather than a person. If a choice breaks down somewhere, I would rather hear it now than ship it and find out. No hurry from my side. Nothing is broken while this is open — the fix for the report that started it is already out as 0.13.6, and this is only about what the panel shows. I would rather decide it once, slowly, and then leave it alone.

Similar Threads
Thread	Thread Starter	Forum	Replies	Last Post
EPUBCheck v4.2.6	jhowell	ePub	0	06-30-2021 03:49 PM
EPUBCheck v4.2.5	jhowell	ePub	0	03-23-2021 09:45 AM
EPUBCheck v4.2.4	jhowell	ePub	3	06-24-2020 09:51 AM
EPUBCheck v4.1.1	Doitsu	ePub	2	03-18-2019 10:39 AM
Web-based epubcheck upgraded to epubcheck 1.0.5	kjk	ePub	4	02-09-2010 09:53 PM

Yesterday, 11:47 AM	#287
Kayadelenium Zealot Posts: 144 Karma: 211110 Join Date: Jul 2026 Location: Planet Earth Device: Kobo Forma	epubveri 0.13.7 — https://github.com/veripublica/epubv...es/tag/v0.13.7 One fix. An element whose entire content is a NO-BREAK SPACE was treated as empty here, and epubcheck does not treat it that way: Rust's trim counts * as whitespace, while XML's whitespace is four characters and does not include it. Four checks read it the wrong way — an empty <dc:title> (OPF-055), any empty *<dc:> (OPF-072), an NCX <navLabel> (NCX-006), and a content document's <title> (RSC-005). The last one is an error**, so a book epubcheck passes was reported invalid here. That is why this went out on its own rather than waiting for the end of the day. Settled against epubcheck 5.3.0, one book per case, with an ordinary space as the control — both tools still report that one. Nothing here could have found it: no book on my 474-book shelf holds such an element, and the 981-scenario corpus is unchanged either way. It came from epubsana, the repair tool, whose session read this source and asked a question it could not test and I could.

Today, 04:57 AM	#288
patrik Guru Posts: 705 Karma: 4568205 Join Date: Jan 2010 Location: Sweden Device: Kobo Forma	In the beginning of this thread, I made a quick&dirty script that recursively went through all my epubs, run checkdsk and yours, and when number of errors/warnings differed, added to a log. Running over night, it found none! My script was obviously faulty... :-) I have been meaning to redo it, but never got around to it. Considering your skills, maybe you can create such a script for us? You know exactly what info is valueable to you and can create logs etc. (without any privacy info) Just a thought... :-)

Today, 11:03 AM	#289
Kayadelenium Zealot Posts: 144 Karma: 211110 Join Date: Jul 2026 Location: Planet Earth Device: Kobo Forma	epubveri 0.14.0 — https://github.com/veripublica/epubv...es/tag/v0.14.0 No finding, ID, severity or position changes in this release. The corpus is unchanged — 603/603 exact-ID matches, no false positives on the 355 should-be-clean cases — and all 474 books on my reference shelf report byte-identically. If you only use the command line and read the human output, there is nothing here for you and you can skip the rest. What changed is the JSON. Two things, both of which existed to stop the output making a claim it could not back. Every count is now present, including zero. fatal, info and usage used to be dropped from summary when they were zero. That turned "the key is missing" into "this book has no usage findings", which is a false statement rather than an ambiguous one — you could not tell an absent count from an absent feature. A clean book now reports all five. And the output says when it has been filtered. Without -u the usage findings are held back, exactly as epubcheck does — but until now the JSON gave no sign of it, so a "usage": 0 could mean either "none found" or "not shown". There is now a "suppressed": ["usage"] beside the counts saying which. It records that the filter was on, not that something was actually hidden, because the question it answers is "can I trust this number?". Both come from the shared output convention the veripublica tools follow, which moved to 0.5.0; the convention field in the envelope says 0.5 now. Nothing was removed, so a reader that used summary.usage still works. One thing under the surface, mentioned only because it touches the zip reader: 18 dependencies moved up, and one of them changed how the archive is decompressed. That is the part of the code every single book goes through, so rather than trust it I re-ran the whole reference shelf — 474 books, byte-identical output — and the corpus with it. If you build from source: the minimum Rust is unchanged at 1.88, and it is now actually tested rather than only claimed.