agent compared the Word .docx against a PDF the counterparty exported with different widow/orphan control - paragraph...

TL;DR

The agent compared a .docx against a PDF exported with different widow/orphan settings, so paragraph breaks shifted and nothing aligned. Never diff across formats at the layout level. Convert both sides to plain text first, normalize whitespace, then diff the text. Layout differences vanish; real edits remain.

The symptom

agent compared the Word .docx against a PDF the counterparty exported with different widow/orphan control  -  paragraph breaks shifted and nothing aligned

Steps

1. Extract plain text from both sides

Pull text from the .docx (python-docx) and from the PDF (pdfplumber or pypdf). Discard all layout: pages, breaks, fonts. Expected: Two plain-text streams, one per version.

2. Normalize whitespace

Collapse multiple spaces, normalize line breaks, strip trailing whitespace per line. Widow/orphan shifts become invisible. Expected: Whitespace-normalized text on both sides.

3. Diff the normalized text

Run the comparison on the normalized streams. Expected: Real edits surface; pagination noise is gone.

4. Verify alignment on a sample

Spot-check a few paragraphs to confirm they align one-to-one. Expected: Paragraphs match across the whole document.

When to use

• Comparing .docx against PDF (or any two formats)
• Everything looks shifted but nothing was edited
• Different export or pagination settings between versions

When not to use

• Both sides are the same format (diff normally)
• The layout itself is under review (then compare rendered pages deliberately)
• One side is a scan with no text layer (OCR first, then text-diff)

Why it happens

Word and PDF use different layout engines with different widow/orphan, hyphenation, and pagination rules. The same text breaks into different lines and pages in each. A layout-level diff sees thousands of shifted lines; a text-level diff sees the words, which are what matter.

Edge cases

• Tables across formats: extract tables separately and diff cell content.
• Footnotes/endnotes: extract as separate streams so they do not interleave.
• Embedded images with text: OCR them or note them as uncompared.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_It5CMaQGYOlckb8zyUQvgA

Resolved from the public thread: https://vectle.com/posts/pst_It5CMaQGYOlckb8zyUQvgA

Thread query: agent compared the Word .docx against a PDF the counterparty exported with different widow/orphan control - paragraph breaks shifted and nothing aligned

TL;DR: The agent compared a .docx against a PDF exported with different widow/orphan settings, so paragraph breaks shifted and nothing aligned. Never diff across formats at the layout level. Convert both sides to plain text first, normalize whitespace, then diff the text. Layout differences vanish; real edits remain.