epubveri for Sigil 0.1.1

Validates the book open in Sigil with
epubveri — no Java, sub-second, and
reporting epubcheck's own message IDs. It reads your book and reports; it
changes nothing.

Install: Plugins → Manage Plugins → Add Plugin, choose
epubveri_v0.1.1.zip. Do not rename the file — Sigil takes the plugin's
folder name from the part before the first underscore. Then run it from
Plugins → Validation → epubveri.

On first use it downloads the epubveri binary for your platform (~3 MB) and
verifies it against that release's SHA256SUMS.txt. The zip contains no
binary.

Fixed since 0.1.0

• A result about the book as a whole no longer says "Invalid Book Path
  Provided". The summary line named no file by passing an empty string, and
  that is the one value Sigil's result table reads as a mistake rather than as
  an absence. It now passes a single space, so the File column comes out blank.
  Reported by DNSB on Windows, line found by Doitsu. The same empty
  string was in seven other places, including every finding epubveri makes
  about the container rather than about a file.
• Positions in content.opf land in the document Sigil is showing. The
  panel said line 95 and the cursor went to 96. The copied OPF was being
  overwritten with get_opf(), which is a rebuild from Sigil's model: it sorts
  the manifest by id and rewrites every entry. The line numbers were right
  for that rebuild and for nothing else — on the book that caught it the cover
  entry is at line 91 in the file, 95 in the rebuild, and 96 on screen. The
  substitution was never needed: readotherfile already returns the live
  rebuild when the OPF has unsaved edits and the file from the ebook root
  otherwise.
• The plugin has an icon, plugin.svg with a plugin.png beside it.
  Suggested by DNSB. A filled tile rather than an outline, because Sigil
  has a dark theme too.

Known limit

With unsaved OPF edits, positions in the OPF refer to Sigil's rebuild
rather than to the text on screen. A plugin cannot ask Code View what it is
holding. Every other file is unaffected, saved or not.

What it does

• Every finding in Sigil's validation panel with its file, line and character
  offset, so double-clicking lands on the character rather than the file.
• Validates what Sigil currently holds, including unsaved edits.
• Labels every line — ERROR, WARNING, USAGE, ADVISORY — and each
  advisory says epubcheck does not report it and the verdict is unaffected.
• Verifies the binary before every run, ~1.8 ms for 2.8 MB. If the file has
  changed since it was verified, nothing is run and the plugin says so.
• Keeps epubveri current, at most once an hour, by reading 842 bytes of
  checksums rather than asking an API. Turn it off with
  "autoupdate": false in plugins_prefs/epubveri/epubveri.json; then it
  never touches the network.
• Offline is silent. No error, nothing missing from the report.

How much it has been used

0.1.0 ran for one day. It has now been used on macOS, Windows (DNSB) and
Linux, the AppImage build (PeterT) — 0.1.0 shipped with none of the last
two tried. The calibre plugin in this repository is still unfinished; do not
package it.

Three defects were found on 0.1.0's first day by running it in Sigil, and
three more on its second, none of which 26 unit tests had caught and all of
which needed a real editor to see. That rate has not flattened, which is why
this is 0.1.1 and not 1.0.0.

Bug reports here. A wrong finding rather than a wrong plugin belongs in
epubveri — a wrong error on a
good book is the report we most want.

Credit

Doitsu wrote the first epubveri plugins for Sigil and calibre and proved the
idea; thiago.eec contributed to the calibre one. This is an independent
implementation rather than a fork — none of their code is used — but what it
needed to do was learned from theirs. autostart is his suggestion, and so is
the fix in the first item above.

epubveri for calibre 0.1.0

Validates the book open in calibre's Edit Book with
epubveri — no Java, sub-second, and
reporting epubcheck's own message IDs. It reads your book and reports; it
changes nothing.

Install: Preferences → Plugins → Load plugin from file, choose
epubveri_v0.1.0.zip, then restart calibre. The tool appears in the editor's
Plugins menu and toolbar as Validate with epubveri.

On first use it downloads the epubveri binary for your platform (~3 MB) into
<calibre config>/plugins/epubveri/ and verifies it against that release's
SHA256SUMS.txt. The zip contains no binary.

What it does

• Every finding in a panel with its file, line and message. Activating a
  row opens the file and puts the cursor on the line, the same way calibre's
  own Check Book results do.
• Validates what calibre currently holds, including unsaved edits.
• Labels every line — ERROR, WARNING, USAGE, ADVISORY — and each
  advisory says epubcheck does not report it and the verdict is unaffected.
  Only errors, fatals and warnings decide VALID/NOT VALID, exactly as in
  epubcheck.
• A settings page (Preferences → Plugins → epubveri → Customize) with
  three switches: automatic updates, show usage notes, show advisory findings.
  All three start on, so out of the box calibre and Sigil report a book
  identically. Whenever a switch hides something the summary says how many
  findings are not listed and where the setting is — never a silently shorter
  report.
• Verifies the binary before every run (~1.8 ms for 2.8 MB) and keeps it
  current at most once an hour by reading 842 bytes of checksums rather than
  asking an API. Turn that off in the settings and it never touches the
  network. Offline is silent.

It does not touch your book, and that is measured

calibre keeps unsaved edits in the open editors, so they are committed to the
container first. The container is then cloned and the clone written out,
because EpubContainer.commit calls update_modified_timestamp() — committing
the real container would rewrite an EPUB 3 book's dcterms:modified, so
validating would edit the book.

Cloning alone was not enough: the timestamp update dirties the OPF, and a
dirtied file is re-serialised rather than copied. calibre's serialiser is not
byte-preserving, so the OPF gained a line and every finding below it was
reported one line off. That is now neutralised on the clone, and a test asserts
that every file in the packaged copy is byte-identical to the container's.

How much it has been used

calibre 9.14, macOS, one day. Nothing has run on Windows or Linux, and no
other calibre release has loaded it — minimum_calibre_version is 6.0 because
that is when qt.core replaced PyQt5.Qt, which is the oldest it can load
on, not the oldest it has been run on.

Five defects were found on its first day by running it inside calibre, and a
sixth by its own tests; the suite is 24 tests, run with
calibre-debug plugins/calibre/tests/test_plugin.py. That rate has not
flattened, which is why this is 0.1.0.

Bug reports here. A wrong finding rather than a wrong plugin belongs in
epubveri — a wrong error on a
good book is the report we most want.

Credit

Doitsu wrote the first epubveri plugin for calibre and proved the idea;
thiago.eec contributed to it. This is an independent implementation rather than
a fork — none of their code is used — but what it needed to do was learned from
theirs, and his is the one that has been in users' hands.

epubveri for Sigil 0.1.0

Validates the book open in Sigil with
epubveri — no Java, sub-second, and
reporting epubcheck's own message IDs. It reads your book and reports; it
changes nothing.

Install: Plugins → Manage Plugins → Add Plugin, choose
epubveri_v0.1.0.zip. Do not rename the file — Sigil takes the plugin's
folder name from the part before the first underscore. Then run it from
Plugins → Validation → epubveri.

On first use it downloads the epubveri binary for your platform (~3 MB) and
verifies it against that release's SHA256SUMS.txt. The zip contains no
binary.

What it does

• Every finding in Sigil's validation panel with its file, line and character
  offset, so double-clicking lands on the character rather than the file.
• Validates what Sigil currently holds, including unsaved edits.
• Labels every line — ERROR, WARNING, USAGE, ADVISORY — and each
  advisory says "epubcheck does not report this; the verdict is unaffected".
  Only errors, fatals and warnings decide the verdict. A book that passes
  epubcheck passes epubveri.
• Verifies the binary before every run, not only when it was downloaded —
  1.8 ms for 2.8 MB. If the file has changed since it was verified, nothing is
  run and the plugin says so.
• Keeps epubveri current, at most once an hour, by reading 842 bytes of
  checksums rather than asking an API. Turn it off with
  "autoupdate": false in plugins_prefs/epubveri/epubveri.json; then it
  never touches the network.
• Offline is silent. No error, nothing missing from the report.

What has not been tested

Two people, macOS, one day. Nothing has been run on Windows, which is
where about three quarters of epubveri's users are, and the calibre plugin in
this repository is not finished — do not package it.

Three defects were found today by running it in Sigil that 26 unit tests did
not catch: the zip's filename contract, Sigil's unescaped result XML, and an
off-by-one in the cursor position. That rate has not flattened, which is why
this is 0.1.0 and not 1.0.0.

Bug reports here. A wrong finding rather than a wrong plugin belongs in
epubveri — a wrong error on a
good book is the report we most want.

Credit

Doitsu wrote the first epubveri plugins for Sigil and calibre and proved the
idea; thiago.eec contributed to the calibre one. This is an independent
implementation rather than a fork — none of their code is used — but what it
needed to do was learned from theirs. autostart is his suggestion.