MobileRead Forums - View Single Post

Kayadelenium · 08-22-2026, 08:21 AM

Three answers, all measured, and one of them settles a disagreement rather than taking a side.

Ordering. I have gone with grouped by severity, most serious first as the default, and added `--sort document` for the old behaviour. Doitsu, you argued for document order and JSWolf asked for warnings first, so let me give the reasoning rather than just the outcome: the set that makes a book invalid is the set you act on, and it is what the verdict line counts. Inside each group the file order is untouched, so it is one pass down the errors, fix, re-run, then one pass down the rest — each still reading top to bottom.

Neither arrangement is epubcheck's, which is worth saying because it looks like it might be. epubcheck does not sort at all: it emits in the order its checks run, and severities cluster as a side effect. On 23 of my test books carrying both severities its sequence differs from mine on 10, and of those 23 it happens to come out warnings-first on 15, errors-first on 3, and interleaved on 5.

Doitsu — please pin whichever you prefer rather than relying on my default. `epubveri --sort document -i book.epub` (or `--sort=document`) works alongside `-u` and `--advisory`. I would rather your plugin be immune to my default than have you depend on my agreeing with you today, because that agreement would not protect you from a future change and an explicit flag will. One caveat: the flag does not exist before this release, so if you support an older binary you would need a fallback — an unknown option is an exit-2 usage error, not a warning.

The same goes for anyone building on the output more generally: the human report is written for a person and is free to change — its wording, its order, and as of this release which severities it shows. `--format json` is the stable, documented one, and it is never filtered or reordered. There is now a page about exactly this: `docs/INTEGRATING.md`.

Unused resources — you are both right, about different books. Doitsu is correct that OPF-097 already covers this; JSWolf is correct that he never sees it. I built the same book twice, one unreferenced stylesheet, and ran both tools:

- EPUB 3 — epubcheck and epubveri both report `USAGE OPF-097` ("declared in the manifest, but no content document references it"). Exact parity.
- EPUB 2 — neither tool reports anything.

JSWolf, you work in EPUB 2, which is why the check looks missing to you. So the open question is not "should someone build this" but "should that question be asked of an EPUB 2 book at all?" — which is a deliberate step beyond epubcheck, so it would live behind `--advisory` if it happens. Note it is a `usage` finding either way, so from this release you need `-u` to see it.

encryption.xml. JSWolf, both shapes your case can take are already errors in epubcheck, and epubveri was reporting neither — that is now fixed:

- the entry was deleted with the font, leaving `<encryption>` empty — epubcheck says `element "encryption" incomplete`;
- the entry stayed and points at a font that is gone — epubcheck says `RSC-007: Referenced resource … could not be found in the EPUB`.

I had it as an INFO note saying the file was encrypted, and called such a book VALID. Both now match epubcheck exactly, along with three other `encryption.xml` shapes I checked while I was there. So this was not a new feature — it was a real miss on my side, and it took your report to find it. Thank you.

Doitsu, on "an unused encryption.xml causes no problems": that is true of the third shape, a valid one pointing at files that are actually there, and nothing new is needed for that. It is not true of the two above, where epubcheck has been erroring all along.

All of this, plus a column that now points at the offending attribute instead of its element (JSWolf, #220), is in tonight's release.

08-22-2026, 08:21 AM	#225
Kayadelenium Connoisseur Posts: 89 Karma: 100000 Join Date: Jul 2026 Location: Planet Earth Device: Kobo Forma	Three answers, all measured, and one of them settles a disagreement rather than taking a side. Ordering. I have gone with grouped by severity, most serious first as the default, and added `--sort document` for the old behaviour. Doitsu, you argued for document order and JSWolf asked for warnings first, so let me give the reasoning rather than just the outcome: the set that makes a book invalid is the set you act on, and it is what the verdict line counts. Inside each group the file order is untouched, so it is one pass down the errors, fix, re-run, then one pass down the rest — each still reading top to bottom. Neither arrangement is epubcheck's, which is worth saying because it looks like it might be. epubcheck does not sort at all: it emits in the order its checks run, and severities cluster as a side effect. On 23 of my test books carrying both severities its sequence differs from mine on 10, and of those 23 it happens to come out warnings-first on 15, errors-first on 3, and interleaved on 5. Doitsu — please pin whichever you prefer rather than relying on my default. `epubveri --sort document -i book.epub` (or `--sort=document`) works alongside `-u` and `--advisory`. I would rather your plugin be immune to my default than have you depend on my agreeing with you today, because that agreement would not protect you from a future change and an explicit flag will. One caveat: the flag does not exist before this release, so if you support an older binary you would need a fallback — an unknown option is an exit-2 usage error, not a warning. The same goes for anyone building on the output more generally: the human report is written for a person and is free to change — its wording, its order, and as of this release which severities it shows. `--format json` is the stable, documented one, and it is never filtered or reordered. There is now a page about exactly this: `docs/INTEGRATING.md`. Unused resources — you are both right, about different books. Doitsu is correct that OPF-097 already covers this; JSWolf is correct that he never sees it. I built the same book twice, one unreferenced stylesheet, and ran both tools: - EPUB 3 — epubcheck and epubveri both report `USAGE OPF-097` ("declared in the manifest, but no content document references it"). Exact parity. - EPUB 2 — neither tool reports anything. JSWolf, you work in EPUB 2, which is why the check looks missing to you. So the open question is not "should someone build this" but "should that question be asked of an EPUB 2 book at all?" — which is a deliberate step beyond epubcheck, so it would live behind `--advisory` if it happens. Note it is a `usage` finding either way, so from this release you need `-u` to see it. encryption.xml. JSWolf, both shapes your case can take are already errors in epubcheck, and epubveri was reporting neither — that is now fixed: - the entry was deleted with the font, leaving `<encryption>` empty — epubcheck says `element "encryption" incomplete`; - the entry stayed and points at a font that is gone — epubcheck says `RSC-007: Referenced resource … could not be found in the EPUB`. I had it as an INFO note saying the file was encrypted, and called such a book VALID. Both now match epubcheck exactly, along with three other `encryption.xml` shapes I checked while I was there. So this was not a new feature — it was a real miss on my side, and it took your report to find it. Thank you. Doitsu, on "an unused encryption.xml causes no problems": that is true of the third shape, a valid one pointing at files that are actually there, and nothing new is needed for that. It is not true of the two above, where epubcheck has been erroring all along. All of this, plus a column that now points at the offending attribute instead of its element (JSWolf, #220), is in tonight's release.