MobileRead Forums - View Single Post - epubsana — automatic repair for what epubcheck reports (not an editor)

Kayadelenium · Yesterday, 08:45 PM

Thanks, both of you.

Doitsu — you're right, and the current output is a worse fit for your purpose than the docs make it look. Here is a real fix item from --format json as it stands today:

Code:

{
  "type": "fix",
  "outcome": "proposed",
  "code": "RSC-005",
  "rule": "opf.content_document.schema_violation",
  "severity": "error",
  "location": "Chapter-003.html",
  "message": "Wrap 3 runs of non-block content in <div> in Chapter-003.html",
  "data": {
    "fix_id": "fix.bare_text_in_body",
    "tier": "confirm_needed",
    "changes": [
      "wrap in <div>: \"<br />\"",
      "wrap in <div>: \"<br />\"",
      "wrap in <div>: \"<br /><br /><br /><br />\""
    ]
  }
}

Those changes entries are descriptions written for a person to read. Nothing downstream can render them or act on them — so for the consumer the JSON format exists to serve, they are not enough, exactly as you say.

I checked where a diff would have to live before replying. Our JSON contract makes items[].data tool-owned and requires consumers to ignore fields they don't recognise, so epubsana can add this on its own: no change to the shared spec, and no existing consumer breaks. The contract also already has the mode this belongs in — --dry-run emits the same envelope with every item marked "proposed", which is precisely the run a plugin would make to show someone a change before applying it.

Two issues are now open:

- #8 — Emit a unified diff per fix under items[].data: https://github.com/veripublica/epubsana/issues/8
- #7 — Workspace: a speculative apply: https://github.com/veripublica/epubsana/issues/7

The dependency between them is real rather than bureaucratic. Fixers currently write their edits straight into the in-memory container, so there is no way to ask what a fix would produce without producing it. That same missing piece is what per-fix rollback needs, so I would rather build it properly than bolt a diff onto the end.

Three questions where your answer is worth more than my guess:

1. One diff per fix, or one per file? Some fixes span files — renaming an invalid id rewrites every reference to it, across content documents and the NCX.
2. Diffs on applied fixes as well, or only under --dry-run?
3. Large diffs — cap them, and if so, how would you want a cap signalled? A fix over a big document can produce a lot of output, and I would rather settle that before someone's plugin runs into it.

One case has no text diff at all: the PKG-006 fix re-packages the container so the mimetype entry comes first and stored. Whatever gets emitted there has to say so, rather than showing an empty diff that reads as "nothing changed".

No timeline promised — I would rather land it correctly than quickly.

Yesterday, 08:45 PM	#4
Kayadelenium Connoisseur Posts: 57 Karma: 100000 Join Date: Jul 2026 Location: Planet Earth Device: Kobo Forma	Thanks, both of you. Doitsu — you're right, and the current output is a worse fit for your purpose than the docs make it look. Here is a real fix item from --format json as it stands today: Code: { "type": "fix", "outcome": "proposed", "code": "RSC-005", "rule": "opf.content_document.schema_violation", "severity": "error", "location": "Chapter-003.html", "message": "Wrap 3 runs of non-block content in <div> in Chapter-003.html", "data": { "fix_id": "fix.bare_text_in_body", "tier": "confirm_needed", "changes": [ "wrap in <div>: \"<br />\"", "wrap in <div>: \"<br />\"", "wrap in <div>: \"<br /><br /><br /><br />\"" ] } } Those changes entries are descriptions written for a person to read. Nothing downstream can render them or act on them — so for the consumer the JSON format exists to serve, they are not enough, exactly as you say. I checked where a diff would have to live before replying. Our JSON contract makes items[].data tool-owned and requires consumers to ignore fields they don't recognise, so epubsana can add this on its own: no change to the shared spec, and no existing consumer breaks. The contract also already has the mode this belongs in — --dry-run emits the same envelope with every item marked "proposed", which is precisely the run a plugin would make to show someone a change before applying it. Two issues are now open: - #8 — Emit a unified diff per fix under items[].data: https://github.com/veripublica/epubsana/issues/8 - #7 — Workspace: a speculative apply: https://github.com/veripublica/epubsana/issues/7 The dependency between them is real rather than bureaucratic. Fixers currently write their edits straight into the in-memory container, so there is no way to ask what a fix would produce without producing it. That same missing piece is what per-fix rollback needs, so I would rather build it properly than bolt a diff onto the end. Three questions where your answer is worth more than my guess: 1. One diff per fix, or one per file? Some fixes span files — renaming an invalid id rewrites every reference to it, across content documents and the NCX. 2. Diffs on applied fixes as well, or only under --dry-run? 3. Large diffs — cap them, and if so, how would you want a cap signalled? A fix over a big document can produce a lot of output, and I would rather settle that before someone's plugin runs into it. One case has no text diff at all: the PKG-006 fix re-packages the container so the mimetype entry comes first and stored. Whatever gets emitted there has to say so, rather than showing an empty diff that reads as "nothing changed". No timeline promised — I would rather land it correctly than quickly.