Possible replacement for EPUBCHECK

[JSWolf]

What's the point of pbubcheck having code to change to missing images when it's not used in ePub2 and ePub3?

[Kayadelenium]

JSWolf — it is used in EPUB 3; you are seeing it hidden rather than absent. Measured just now, one EPUB 3 book with one image that nothing references:

without any flag — epubcheck: silent. epubveri: silent.
with -u — epubcheck: USAGE(OPF-097). epubveri: USAGE OPF-097.

OPF-097 is a usage note rather than an error, and epubcheck hides usage messages unless you pass -u. epubveri does the same thing, deliberately, so that a book gives you the same report from both tools by default.

In EPUB 2 you are right, and that is the part worth separating: epubcheck never asks the question there at all. Its rule lives in the EPUB 3 checker and has no EPUB 2 counterpart, so an unused image in an EPUB 2 book gets no answer from either tool — which is why it looked missing to you and present to Doitsu. You validate different versions.

That gap is what 0.13.3 fills, as ADV-010 behind --advisory. It is opt-in because reporting something epubcheck is silent about is exactly the kind of difference that looks like a false positive if it turns up unasked, and it never changes the verdict.

So, to see an unused resource:

• EPUB 3 — epubveri -u -i book.epub (or epubcheck -u), in either tool;
• EPUB 2 — epubveri --advisory -i book.epub, epubveri only.

And one thing worth knowing if you try it from Sigil or calibre: both plugins run with usage and advisory off, so it will not appear there unless you turn them on in the plugin's settings.

[Kayadelenium]

A correction to my own advice above. I said you could turn usage notes and advisory checks on "in the plugin's settings". That is right for calibre and wrong for Sigil.

In calibre, Doitsu's plugin has a real preferences dialog — from the Edit Book toolbar, or Preferences / Plugins / Customize.

In Sigil there is no such thing. A plugin gets no settings screen at all: Manage Plugins shows name, version, author, type, engine and platforms, and nothing else. A plugin can store preferences, but the only way to change them is to edit its JSON file by hand, or to ship a second plugin whose whole job is one checkbox. Neither is something to ask of someone who just wants to validate a book.

So on Sigil the switch is effectively unreachable, and that is worth knowing before anyone goes looking for it. We are thinking about what an editor integration should do about it — a validator that hides half of what it found behind a setting nobody can reach is not much use.

None of this changes the command line, where --advisory stays opt-in for the reason I gave: a script diffing epubveri against epubcheck has to see the same report from both.

[Kayadelenium]

JSWolf — the unused-image check from #221, and a correction to what I told you in #272.

I said then that a plugin runs with usage notes and advisory findings off, so you would have to switch them on. That was true of the two plugins that existed that day. There are four now, and the two I wrote behave the other way round.

Mine: there is nothing to switch on. The Sigil one shows every finding, each line labelled ERROR, WARNING, USAGE or ADVISORY. That is not generosity — Sigil gives a plugin no settings screen at all, and a switch nobody can reach is worse than no switch. The calibre one shows everything too; its three boxes in Preferences / Plugins / epubveri / Customize are there to turn things off, not on.

So open an EPUB 2 book in either and ADV-010 is simply in the list: nothing draws, applies or loads this file. No flag, no JSON, no preference.

Doitsu's: my earlier answer still stands. His calibre plugin has a preferences dialog with the setting in it. His Sigil one has nowhere to put a dialog, so the setting lives in the plugin's JSON preferences file and you edit it by hand. His threads are the place to ask about those two.

Both of mine are days old and I would rather you found a wrong error in one than not, so: https://github.com/veripublica/epubv...ugins/releases

[PeterT]

A very minor suggestion; would it be feasible to include some means of distinguishing the two plugins from each other, such as including the word sigil or calibre in the zip file name, rather than both being named epubveri_vx.y.zip?

[JSWolf]

Now I'm seeing epubveri mentioning unused images. That's good. Then I can remove unused images.

[DNSB]

Originally Posted by JSWolf

Now I'm seeing epubveri mentioning unused images. That's good. Then I can remove unused images.

That's never been an issue for me since I use Sigil's Delete Unused Media Files tool.

[Kayadelenium]

A note for anyone here who would rather not use a command line: there are now editor plugins that run epubveri for you, and both were updated today.

Sigil: https://github.com/veripublica/epubv...g/sigil-v0.3.0
calibre's Edit Book: https://github.com/veripublica/epubv...calibre-v0.3.0

They download the epubveri binary themselves and verify it against the release checksums before running it, so there is nothing else to install. Findings land in the editor's own panel and a double-click puts the cursor on the problem.

Both are days old and have mostly been run on macOS, so they are worth trying rather than relying on. Doitsu's own epubveri plugins are in the Sigil and calibre plugin indexes and remain the tested option. Discussion for each lives in its own thread, and I will keep plugin news there rather than here:

Sigil: https://www.mobileread.com/forums/sh...d.php?t=374939
calibre: https://www.mobileread.com/forums/sh...d.php?t=374940

What is most useful back is the same thing as always: a book where epubveri reports something epubcheck does not. That is the report that changes the software.

[Doitsu]

I noticed one difference:

epubveri won't flag:

<body epub:type="cover" role="doc-cover">

EPUBCheck reports:

ERROR RSC-005: Error while parsing file: value of attribute "role" is invalid; must be equal to "application", "document", "none" or "presentation"

[Kayadelenium]

epubveri 0.13.4 — Doitsu's role report, and the two layers underneath it.

https://github.com/veripublica/epubv...es/tag/v0.13.4

Doitsu — fixed, and thank you.

Your case first. <body epub:type="cover" role="doc-cover"> now draws the same RSC-005 epubcheck gives, at the same line. `body` is unusually strict about `role` — four values, `application` / `document` / `none` / `presentation` — and that is read straight out of epubcheck's own schema rather than guessed at.

Then I asked whether one element was enough, and it was not. Probing seventeen elements with an invented role token: epubcheck rejects it on sixteen of them and we were accepting it on fifteen. So two more things are fixed here:

• A role value must now be one of the 111 names epubcheck's schema declares — 39 of them the DPUB-ARIA `doc-*` set. Extracted from the schema, not transcribed. And `role` is a single token in XHTML, not a list: `role="doc-noteref button"` is an error in both tools.
• role is not allowed on <html> at all, which is an attribute-list difference rather than a value one. It was the sixteenth.

What is deliberately still missing, since a validator should say so. epubcheck also restricts which of the 111 each element may carry, across 1739 lines of schema. That layer is not implemented: `<p role="doc-cover">` is wrong there and accepted here. The reason is a measurement rather than laziness — those per-element sets are broad enough that the token layer alone accounts for fifteen of the sixteen disagreements, so the cheap half is nearly all of the value, and the rest carries real risk of telling someone their accessibility markup is invalid when it is not.

The same probing found the next layer down: the values of `aria-hidden`, `aria-level`, `aria-live`, `aria-checked` are still unconstrained here and are not in epubcheck. That is filed rather than fixed, with its measurement, because there is a control problem: across 474 books I have here, exactly three distinct `aria-*` attributes are used and none of them is one with an enumerated value — so nothing I own could tell me I had got one wrong.

A word on how these were checked, since a vocabulary of 111 names is exactly the kind of list that invents errors on valid markup. Every element/role pair that actually occurs across those 474 books still passes in both tools, W3C's own 209 conformance publications produce no role finding at all, and epubcheck's 981-scenario corpus is unchanged at 100% with no false positives. The new rules fire where epubcheck fires and nowhere else that I can find.

[Doitsu]

Originally Posted by Kayadelenium

What is deliberately still missing, since a validator should say so.

I understand that you want to match the behavior of EPUBCheck, but in this case, you might want to report it as an EPUBCheck bug, because the EPUB Type to ARIA Role Authoring Guide 1.1 clearly states that role="doc-cover" should only be used for <img> tags.

I also noticed another case where epubveri doesn't display an error message.

    <nav id="pagelist" epub:type="page-list" role="doc-pagelist">
      <ol hidden="hidden">
        <li></li>
      </ol>
    </nav>

EPUBCheck reports:

ERROR RSC-005: Error while parsing file: element "li" incomplete; expected element "a" or "span"

[Kayadelenium]

Doitsu — thank you, and yes: reproduced, and fixed for the next release.

<li></li> inside a page-list nav drew nothing here and RSC-005 element "li" incomplete; expected element "a" or "span" from epubcheck. One line was responsible: the check collected an <li>'s element children and returned quietly when there were none, so the case never reached a rule at all.

Your example turned out to be one of four shapes falling through it, which I only saw by probing around it rather than fixing what you sent:

• <li></li> — one error, as you reported.
• <li> </li> — whitespace is not a label either, and epubcheck says exactly the same thing about it.
• <li>bare text</li> — two errors from epubcheck, one for the text standing where the label belongs and one for the label still being absent. This is the one I would have missed.
• <li><ol>…</ol></li> — already matched.

All four now agree with epubcheck: same ids, same messages, five findings to its five on a book carrying all of them.

Worth saying plainly, because it is the argument for reports like yours: nothing I own could have found this. epubcheck's own 981-scenario corpus is unchanged either way, and of the 474 books I keep here, 73 carry an EPUB 3 nav and not one has a label-less <li>. A shelf that says "no change" is only telling you it has no examples.

On role="doc-cover" — you are right that the authoring guide puts it on <img>, and epubcheck's schema constrains <body> to four values regardless. What this tool implements is deliberately whatever epubcheck enforces, so the disagreement you found is between the guide and epubcheck rather than between epubcheck and epubveri. If that changes upstream, this follows it.

Not released yet — it will go out with the next version rather than on its own, since a missed error harms nobody who has it. I will post here when it lands.

[DNSB]

Minor nit. I opened an ePub today and epubcheck returned no errors while epubveri returned one error in the nav.xhtml navigation document using epubveri 0.13.5.

  <nav epub:type="landmarks">
    <h1>Guide</h1>

    <ol epub:type="guide">
      <li><a epub:type="cover" href="cover.xhtml">Cover</a></li>

      <li><a epub:type="titlepage" href="title.xhtml">Title Page</a></li>

OEBPS/Text/nav.xhtml	88	2458	USAGE OPF-088: epub:type value 'guide' is not in the default vocabulary

[Doitsu]

Another nitpick. For this English epub with German popup translations, epubveri reports 3 unused Javascript files in OEBPS/js/.

ADVISORY	OEBPS/content.opf	17	9	ADV-010: 'js/util.js' is declared in the manifest, but no document draws, applies or loads it  (epubcheck does not report this; the verdict is unaffected)
ADVISORY	OEBPS/content.opf	18	9	ADV-010: 'js/main.js' is declared in the manifest, but no document draws, applies or loads it  (epubcheck does not report this; the verdict is unaffected)
ADVISORY	OEBPS/content.opf	23	9	ADV-010: 'js/ch1.js' is declared in the manifest, but no document draws, applies or loads it  (epubcheck does not report this; the verdict is unaffected)

However, they are actually referenced and used in OEBPS/text/ch1.xhtml.

<script type="text/javascript" src="../js/util.js"></script>
<script type="text/javascript" src="../js/ch1.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

[Kayadelenium]

DNSB – not a disagreement, and I can show you the same message from both tools.

Doitsu – a real one, reproduced and fixed.

DNSB, the OPF-088 on guide

epubcheck reports it too. Your book, minimised to the nav you posted:

epubcheck      -u  →  USAGE(OPF-088): Unrecognized epub:type value "guide".  nav.xhtml(8,27)
epubveri       -u  →  USAGE OPF-088: epub:type value 'guide' is not in the default vocabulary  [nav.xhtml:8:9]
epubcheck  no flag →  silent
epubveri   no flag →  silent

Same finding, same line. What differs is visibility: epubcheck hides usage messages unless you pass -u, and my Sigil plugin shows every severity because Sigil gives a plugin no settings screen to hide anything behind (#274). So you were comparing epubcheck with usage off against epubveri with everything on. On the command line, with the same flag, the two reports match.

The finding itself is right. guide is not a term of the EPUB structural semantics vocabulary – it is the EPUB 2 <guide> name carried into an EPUB 3 nav out of habit, and the <nav epub:type="landmarks"> wrapper is exactly what replaced it. The <ol> inside needs no epub:type at all; delete that one attribute and both tools go quiet.

Worth saying that this is the third report of this shape – JSWolf met it twice on CSS-028 (#206, #209) and once on OPF-097 (#271). Three reports about the same thing is a fact about the tool, not about the reporters, and I am looking at what the plugin should do with usage findings so they stop reading as errors. That belongs in the plugin thread rather than here, so I will take it there.

Doitsu, the three "unused" scripts

Reproduced on your doppeltext book and fixed. Thank you – this is the report that changes the software.

One continue was serving two questions. epubcheck's EPUB 2 handler registers no reference for an HTML <script src>, so a missing target draws no RSC-007 there, and we skip that existence check to match it. The skip took the reference registration with it. But "does any document load this file" is ADV-010's question, and epubcheck does not ask it of an EPUB 2 book at all – so there was no parity to preserve by staying silent, only a false positive to make. The reference is registered now and the existence check is still skipped, with a test pinning both halves.

Then I probed the rest of the class rather than only the shape you sent, because one wrong answer of this kind usually has siblings. Fourteen reference spellings in a single EPUB 2 book – img@src, object@data, video@poster, audio/source/track/embed/iframe/input@src, link rel=stylesheet, a CSS url(), MathML altimg and an SVG image@xlink:href. <script src> was the only one missing.

And nothing I own could have found it, which is worth putting a number on. epubcheck's 981-scenario corpus is unchanged either way. The 474-book shelf is unchanged to the finding – 212 ADV-010 across 100 books, identical in both builds – and the reason is that only 6 of those 474 books carry a <script src> at all, and none of the 390 EPUB 2 ones does. A shelf that reports "no change" is telling you it has no examples, not that the tool is right.

Without the flag the two tools already agreed on your book exactly: epubcheck 0 findings, epubveri 0 findings. The disagreement lived entirely inside --advisory, which is opt-in and never moves the verdict – but a wrong statement is a wrong statement, and it was on a real book of yours.

Released as 0.13.6: https://github.com/veripublica/epubv...es/tag/v0.13.6

I pulled the published macOS binary back down, checked it against SHA256SUMS.txt and ran it on your book — the three advisories are gone, and a control book with a file nothing really uses still reports one.