From 043057adaf793594e2e0956c59899edf7dae6c31 Mon Sep 17 00:00:00 2001 From: tannevaled Date: Tue, 10 Nov 2026 08:58:11 +0100 Subject: [PATCH] docs: saying what changed between two versions of a document MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ops v0.37.0's ops.Compare and `pdfops compare`, on the ribbon from app v0.53.0 as `Compare with a file`. Two pages: the library verb on "Rearranging a file", the control on "The workbench". ⛔ Both say THE PAGES ARE PAIRED BY WHAT THEY SAY, NOT BY THEIR NUMBERS, which is the whole design: a page inserted in the middle moves nothing after it, and pairing by number would report every page from there to the end as changed. ⛔ And the workbench page says THE DIRECTION, because a reader who has it backwards reads every addition as a deletion: the file chosen is the earlier version, the document open is the later one, and the report says so in those words. Co-Authored-By: Claude Opus 5 --- content/working-with-a-file/operations.md | 40 ++++++++++++++++++++++- content/working-with-a-file/workbench.md | 23 +++++++++++++ 2 files changed, 62 insertions(+), 1 deletion(-) diff --git a/content/working-with-a-file/operations.md b/content/working-with-a-file/operations.md index b210676..4e2ff40 100644 --- a/content/working-with-a-file/operations.md +++ b/content/working-with-a-file/operations.md @@ -22,7 +22,8 @@ pages and `1,1` gives two copies. ## The verbs -Merge, select, delete, reverse, move, rotate, turn by any angle, crop, resize, split; n-up, +Merge, select, delete, reverse, move, rotate, turn by any angle, compare two +versions, crop, resize, split; n-up, booklet, overlay and underlay, blank pages; watermarks, page numbers, Bates stamps and free stamps; placing a picture — a signature, a logo, a seal; sanitize, flatten, strip; compress, encrypt, decrypt and permissions; @@ -32,6 +33,43 @@ straightening a scan; and reading a page back as text or as pictures. a signature, put where you say. It is not cryptography and does not claim to be — a drawn squiggle proves nothing about who drew it. +## Saying what changed between two versions + +`compare` reads two documents against each other. + +```sh +pdfops compare draft1.pdf draft2.pdf +``` + +```text +- -> 2 page added +2 -> 3 text removed zeta +2 -> 3 text added theta +2 of 3 page(s) changed +``` + +⛔ **The pages are paired by what they say, not by their numbers.** A page +inserted in the middle moves nothing after it: the pages that follow are still +paired with the pages they came from, and the insertion is one *page added*. +Pairing by number would report that page as an edit of the next, that one as an +edit of the one after, and so on to the end — every page of the document +changed, which is both useless and false. + +A pair has to share **half its words**, or it is one page removed and another +added: without that floor a replaced chapter reads as a rewrite of the one +before it. + +Inside a pair the diff is **Myers** (*An O(ND) Difference Algorithm and Its +Variations*, Algorithmica **1** (1986) 251–266) over words, and words that +changed together are reported together — *"quick brown fox"* → *"slow grey +mole"* is two changes, not six. Pictures are told apart by a **hash of their +samples**, so a swapped logo of the same size is a change; annotations by their +subtype and their text. + +⛔ `compare` **exits 0 whether or not the documents differ**, unlike `diff`: in +this command an exit of 1 means the work could not be done, and a document that +changed is the work being done. The answer is in the last line, in words. + ## Turning a page by any angle `rotate` writes a number on the page — `/Rotate`, a multiple of ninety — and diff --git a/content/working-with-a-file/workbench.md b/content/working-with-a-file/workbench.md index ffb36e9..61cc402 100644 --- a/content/working-with-a-file/workbench.md +++ b/content/working-with-a-file/workbench.md @@ -145,6 +145,29 @@ Beside the page rather than over it, because nearly every verb changes the document and the document is drawn from what would be saved — typing a crop box and watching the page come back cropped is the whole point. +### Comparing this document with an earlier version + +**Compare with a file**, on the Read tab, asks for another version and reads +what changed between it and the one on the screen: pages added or dropped, +words, pictures and comments. It is a **reading**, like the text and the grids +— it replaces the picture of the page, and pressing the verb again puts the +page back. + +⛔ **The direction is said out loud, in the report.** A comparison has two +documents in it, and a reader who has the order backwards reads every addition +as a deletion. The file chosen is the **earlier** version, the document open is +the later one, and the heading says *"the left page is draft1.pdf; the right +page is this document"* rather than leaving it to be worked out from the page +numbers. + +⛔ **Any change to the document drops the report.** It names pages and +differences; after a page is dropped it names pages that are not there, while +looking exactly as authoritative as it did a second earlier. + +What it compares is what **Save** would write — a form that has been filled in +is saved as the file it came from with the answers appended, and those are not +the same bytes as the rebuilt document. + ### Turning by an angle that is not a quarter **Turn them by an angle**, beside *Turn them*, takes the angles the cycle