epubveri – standalone EPUB validator

[JSWolf]

Read the following thread starting with page 9. It points out some rather stupid changes to the ePub spec and epubcheck 4.5.0. Please don't follow the stupidness.

https://www.mobileread.com/forums/sh...=374659&page=9

[DiapDealer]

Originally Posted by JSWolf

Read the following thread starting with page 9. It points out some rather stupid changes to the ePub spec and epubcheck 4.5.0. Please don't follow the stupidness.

https://www.mobileread.com/forums/sh...=374659&page=9

You do realize the stupidness of suggesting that an epub validator NOT follow changes to the epub spec, right?

[JSWolf]

Originally Posted by DiapDealer

You do realize the stupidness of suggesting that an epub validator NOT follow changes to the epub spec, right?

Or how about a warning that it breaks backward comparability?

[DiapDealer]

You just need to relax while others absorb the ramifications of these changes. Careful thought is needed, not knee-jerk demands.

[Kayadelenium]

Originally Posted by Doitsu

EPUBCheck 4.5.0 flagged two errors in a commercial epub3 book that epubveri did not report.

Thank you for the fragment — it reproduces exactly. I built a minimal book around it and ran both tools: EPUBCheck 5.4.0 gives those two RSC-005 errors, epubveri reports nothing and calls the book valid.

That difference is deliberate, and this is the one case where epubveri is right and 5.4.0 is not.

It is w3c/epubcheck#1726, a regression introduced in 5.4.0: the grammar for the nav elements of a navigation document lost aria-label and aria-labelledby. You can see it in the message itself — aria-expanded is still in the list of permitted attributes, and the rest of the aria-* family is gone. The specifications allow them, and they are what makes a second or third nav announce itself to a screen reader, so your book's markup is not only valid but the better practice.

rdeltour has confirmed it, it is marked critical, and it is milestoned for 5.4.1, which has not been released yet. Nothing to change in your book.

I posted this as a correction at #297, a few days after saying "if the two tools disagree, believe 5.4.0" — that post has scrolled well out of sight by now, so it is entirely reasonable that it did not reach you. The general rule still holds; this is its one standing exception until 5.4.1 is out.

[Kayadelenium]

Originally Posted by JSWolf

It points out some rather stupid changes to the ePub spec and epubcheck 4.5.0. Please don't follow the stupidness.

I read the thread, and I went to the specifications rather than to EPUBCheck before answering, because that is the order here: the specification is what epubveri is measured against, and EPUBCheck is how the rest of the world measures the same thing. I track it closely, but where the two disagree the specification wins. There is a live example of that one post up, in Doitsu's report: 5.4.0 rejects aria-label and aria-labelledby on a navigation document's nav elements, the specifications allow them, and epubveri accepts them. That is w3c/epubcheck#1726 — confirmed, marked critical, milestoned for 5.4.1. And where the fault is theirs rather than the specification's, I report it: w3c/epubcheck#1731, which I filed last Friday — a dc:date ending in a bare dot, such as a timestamp written 2010-01-01T10:00:00., throws an uncaught exception in EPUBCheck's date parser. It prints a stack trace, stops checking the rest of the book, and its JSON report comes out with zero messages and zero errors, so a pipeline reading that file sees a clean book. rdeltour reproduced it the same day and it is milestoned for 5.4.1 too. Both links are worth a click if you want to see how these get settled. So "follow EPUBCheck" is not the rule, and if 5.4.0 had invented these messages I would have said so.

It did not, and that is why I have to decline. EPUB 3.4 adds a new category called outdated features, and its list is exactly what OBS-001 reports: the NCX, the OPF 2 meta and guide elements, the collection element, font obfuscation, content fallbacks, the rendition flow, orientation and spread properties, and the -epub- prefixed CSS properties. The specification then tells conformance checkers not to raise alerts about them, and that is precisely why they arrive as usage notes rather than warnings — it was the specification's own editor who asked EPUBCheck for them, at usage or info severity, so that they could never fail a book. The safeguard you are asking for is already the design. HTM-062 is the same story: EPUB 3.4's normative reference for SVG is the unversioned one, which today is SVG 2, and SVG 2 is where xlink:href was deprecated. (That also answers the question elibrarian raised in the other thread about SVG 1.1.)

What I will not do is go quiet on a rule the specification and EPUBCheck agree on, because the way that failure reaches you is silence: you run epubveri, it tells you nothing, and you find out from whoever rejects the file. An error I decline to report does not stop existing — it just stops being mine to tell you about. Worth saying plainly, though: nothing is being asked of you here. OBS-001 and HTM-062 do not move a verdict and do not set the exit code, so a book carrying nothing but those is a book both tools call valid. The noise you are objecting to is a display question with a switch on it, not a correctness one.

Originally Posted by JSWolf

Or how about a warning that it breaks backward compatibility?

That one I want. It is a different and much better request, and it is a question EPUBCheck cannot ask — "is this valid?" and "will this still open on a 2012 reader?" are not the same question, and no conformance checker will ever answer the second. epubveri has a place built for exactly this: --advisory, an opt-in flag whose findings never touch the verdict or the exit code.

What it needs before a line of it is written is evidence, because an advisory that is wrong is worse than no advisory. Not "old readers may break" but which reader, which version, which markup. The thread already has the beginning of it: elibrarian found plain href fine in ADE 4.5 and not in Readest 0.12.8; you found it breaks older RMSDK. That is the shape of the data that turns this into a check — and it is the kind only people with the devices can produce. I cannot measure it from here.

This is the same family as epubveri#136, which came out of your last request — tell me when an EPUB 3 has no NCX, because an older RMSDK reader needs one. I would rather fold both into one honest answer to "will this book open on old hardware" than bolt on two unrelated warnings. It is research with no promised date, but it is open and it is the direction I want to go.

Two facts that take some of the pressure off in the meantime.

1. You do not have to choose between xlink:href and href. Doitsu worked this out in the Sigil thread and I verified it in both tools: an image carrying both attributes with the same value is silent — no HTM-062, no HTM-063, in EPUBCheck 5.4.0 and in epubveri alike. HTM-062 fires only when xlink:href stands alone; HTM-063 only when the two values disagree. So an SVG cover can keep the xlink:href that old readers need and add the href beside it, and both tools go quiet. I implemented that branch from EPUBCheck's own source (OPSHandler30.getSVGHrefs) rather than guessing, and re-ran it today to be sure.

2. The switch I mentioned above. On the command line, both tools hide usage messages unless you pass -u — EPUBCheck and epubveri alike. Worth knowing if you meet them in a panel rather than a terminal: the Sigil plugin and the calibre editor plugin show usage notes by default, which is their choice and not the tool's — the calibre library plugin does not — and all three have a switch for it in their settings.

[Kayadelenium]

One clarification on point 1 of my post at #294, patrik, because it changes what your script should do.

The hazard I described there is real: if one tool shows usage messages and the other does not, every usage note turns into a phantom difference. I had the direction the wrong way round, though. Both tools hide usage by default and in both the switch is -u — in epubveri that covers the human report, --format ids and --format json alike, as described at #289. So the rule is the simple symmetrical one: -u to both, or to neither. Points 2 to 4 stand as written.

One thing that is worth more than the clarification, given how your first attempt went. In --format json the summary carries all five counts, and when the filter is on it carries "suppressed": ["usage"] beside them. So a script never has to infer whether a zero means "none found" or "not shown" — it can read the flag and assert on it. That is the check I would put in first, on a book you know produces usage findings: assert that epubveri's report either carries them or says it suppressed them, and that EPUBCheck's output is not empty. Neither assertion costs anything, and one of them would have caught the overnight run that came back with nothing. A comparison that silently reports no differences is nearly always a comparison that did not run.

On the downloadable version of my own comparison tool, which I said at #294 I would look at: it is still the test harness, and still needs Rust, Java and the jar. Nothing to announce yet.

[JSWolf]

I do plan on testing if removing xlink SVG will work on RMSDK on a Kobo as it's a slightly newer version then the version of ADE I tested it with. On old Sony Readers, it won't work without xlink:. I also want to test that it works without xlink: on a Kobo as a KePub. I'll do that later today when I get time to do do.

[Doitsu]

Originally Posted by JSWolf

I do plan on testing if removing xlink SVG will work on RMSDK on a Kobo as it's a slightly newer version then the version of ADE I tested it with. On old Sony Readers, it won't work without xlink:. I also want to test that it works without xlink: on a Kobo as a KePub. I'll do that later today when I get time to do do.

Since adding an addtional href attribute will suppress the USAGE message all you have to do is test if this additional href will be ignored by older readers and apps.

For example:

<svg xmlns="http://www.w3.org/2000/svg" height="100%" preserveAspectRatio="xMidYMid meet" version="1.1" viewBox="0 0 800 600" width="100%" xmlns:xlink="http://www.w3.org/1999/xlink">
<image width="800" height="600" href="../Images/cover.jpg" xlink:href="../Images/cover.jpg"/>
</svg>

[JSWolf]

Originally Posted by Doitsu

Since adding an addtional href attribute will suppress the USAGE message all you have to do is test if this additional href will be ignored by older readers and apps.

For example:

<svg xmlns="http://www.w3.org/2000/svg" height="100%" preserveAspectRatio="xMidYMid meet" version="1.1" viewBox="0 0 800 600" width="100%" xmlns:xlink="http://www.w3.org/1999/xlink">
<image width="800" height="600" href="../Images/cover.jpg" xlink:href="../Images/cover.jpg"/>
</svg>

That works. Well done!

[KevinH]

But according to the epub 3.4 spec under the section obsolete, they list the entire ncx, guide, and old meta as obsolete. If these generate Usage messages, then pedantic users will not be able to create backwards compatible epub3s without Usage messages.

Perhaps just ignoring all new epubcheck/epubveri usage messages since they are just informational is the best approach here, as surely backwards compatibility is more important to epub publishers and devs? They are just Usage messages!

[DiapDealer]

Especially considering you have to explicitly turn the usage messages on in the first place.

[Kayadelenium]

Originally Posted by KevinH

If these generate Usage messages, then pedantic users will not be able to create backwards compatible epub3s without Usage messages.

You are right, and the specification agrees with you. EPUB 3.4 says the NCX, the OPF 2 guide and the OPF 2 meta element are kept only to give "a measure of backwards compatibility" with reading systems that stop at EPUB 2 — that is the reason it gives for their still being there at all. So a book that is backwards compatible on purpose cannot be free of OBS-001. That is not a side effect of the rule, it is the rule's subject matter.

The Working Group saw it coming, too. The same appendix ends with a note advising conformance checkers not to raise alerts about the presence of outdated features, and when Matt Garrish, who edits the specification, asked EPUBCheck to report them he asked for usage or info severity specifically so they could never become warnings. So "this should not make you change your book" is not my reading of their decision — it is their decision.

One practical thing for today, since it is not well known: EPUBCheck can do this per message rather than all-or-nothing. -l checks.txt writes out every message id with its severity and -c checks.txt applies the file back, so setting OBS-001 to SUPPRESSED drops the outdated-features notes while HTM-062 and everything else keeps reporting. I tested it on a book carrying both. epubveri has no equivalent today.

Now the part I would rather ask than answer.

Between this thread and the Sigil one there are now several of you telling me useful and slightly different things about old hardware, and I am not at all sure you want the same thing. Rather than guess and build the wrong thing, I would like to hear it from you. I have measured what I can here, and it is thin: of the 474 books I test against, only 74 are EPUB 3, and of those 63 carry an NCX, 69 carry a cover meta, and not one has an SVG cover that uses plain href. Project Gutenberg accounts for most of them, so that sample is worth very little.

What you know that I cannot measure

1. Which devices are actually the floor? Right now I have "older RMSDK", "old Sony Readers", ADE 4.5 being fine and Readest 0.12.8 not. That is anecdote, not a target. If you had to name the oldest thing you genuinely need to keep working, what is it, and which version?

2. What breaks first? Navigation with no NCX, the cover, the SVG wrapper, HTML5 sectioning elements, CSS — which of these actually ruins a book on those devices, and which merely looks worse? I would rather cover two things that matter than eight that sound plausible.

3. What do you do today? Before any tool exists, what is your own routine for keeping an EPUB 3 usable on old hardware — a template, a checklist, a plugin, or just knowing what not to do? The real workflow will tell me more than any hypothetical I could put to you.

4. Has this been tried? This ecosystem is older than my involvement in it. If someone has already built a backwards-compatibility checker and it did not catch on, I would much rather learn why from you than rediscover it.

What I would rather have your judgement on

You have between you built and maintained the editors, the plugins and the conversion paths that this format actually runs on. I have built a validator and I have never shipped a reading system, so on the rest of these I am asking what you think, not what you know.

5. Is this a validator's job at all? "Is this book valid?" and "will this book open on a 2012 reader?" are different questions, and I can see the argument that the second belongs to the editor, or to a separate tool, or to nobody. If epubveri is the wrong home for it, now is a much cheaper time to tell me than later.

6. Who should decide the target — me or the user? A tool can ship a named opinion about which devices matter and check against it, or it can make the user declare their own floor and stay silent about what that floor should be. The first is easier to use and puts me in the business of curating a device list; the second is honest and probably gets ignored. Which would you actually use?

7. How do you keep something like this from going stale? KevinH and DiapDealer especially: a device compatibility table is exactly the kind of knowledge that is true when written and quietly wrong two years later. You have both dealt with that for a long time. Do you keep such things, date them, or refuse to own them at all?

8. What would make you say no to this? KevinH wrote in the Sigil thread that new features now have to help the majority of users and be impossible to do in a plugin. That is a harder test than any I apply to myself. Applied to this idea, where does it fail?

9. And the awkward one. I said at #306 that I will not drop a rule the specification and EPUBCheck agree on, and I meant it — but that is about taking things away. Is there a place where you think a tool should legitimately part company with the specification by saying something the specification does not say? JSWolf has been pushing at this from one side and I have been resisting from the other, and I notice neither of us has asked the rest of you. If several of you point at the same place, that carries far more weight than my opinion about it.

If anyone has a large EPUB 3 collection, the single most useful number you could give me is what fraction of it carries an NCX. Mine is too small and too skewed to trust.

I am not proposing anything yet, deliberately. I would rather find out whether you agree with each other first.

[JSWolf]

Originally Posted by Kayadelenium

3. What do you do today? Before any tool exists, what is your own routine for keeping an EPUB 3 usable on old hardware — a template, a checklist, a plugin, or just knowing what not to do? The real workflow will tell me more than any hypothetical I could put to you.

rem instead of em & figure instead of div in CSS, no xlink in SVG, no NCX all break an ePub that you plan to read on an old version of RMSDK. There could be others, but these are the ones I know off the top of my head.

[Doitsu]

Originally Posted by Kayadelenium

If anyone has a large EPUB 3 collection, the single most useful number you could give me is what fraction of it carries an NCX.

I don't have a very large epub3 collection either, but my English fiction books published by the big five publishers all have .ncx files.