Skip to content

Commit bbc829e

Browse files
committed
docs: scope the move-detection warning to WmlComparer; strengthen a test
The warning told every caller to pair detect_moves with simplify_move_markup, but docxdiff honours the former and rejects the latter, so a docxdiff user following the docs hit a ValueError with no available mitigation. Scope the warning and say what docxdiff does instead -- without claiming it is free of the Word bug, which is untested. test_docxodus_explicit_wmlcomparer_matches_default now parses and compares the two revision counts rather than asserting each contains "9" independently, so the test checks the equivalence its name promises.
1 parent 85361d5 commit bbc829e

2 files changed

Lines changed: 20 additions & 3 deletions

File tree

README.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,7 @@ redline_bytes, stdout, stderr = engine.run_redline(
136136
| `conflate_spaces` | bool | True | Treat breaking/non-breaking spaces the same |
137137
| `date_time` | str | now | Custom ISO 8601 timestamp for revisions |
138138

139-
> **Warning:** Move detection can cause Word to display "unreadable content" warnings due to a known
139+
> **Warning:** (WmlComparer only) Move detection can cause Word to display "unreadable content" warnings due to a known
140140
> ID collision bug. When using `detect_moves=True`, always set `simplify_move_markup=True` as well.
141141
> This converts move markup to regular del/ins (loses green move styling but ensures Word compatibility).
142142
@@ -159,6 +159,12 @@ engine.run_redline("Reviewer", original, modified, engine="docxdiff")
159159
rather than silently ignoring them. It does honour `detect_moves`, `case_insensitive`,
160160
`conflate_spaces`, `move_similarity_threshold`, `move_minimum_word_count`, and `date_time`.
161161

162+
Move markup differs between the two. `docxdiff` renders moves natively and rejects
163+
`simplify_move_markup`, so the Word-compatibility mitigation described in the warning above is
164+
unavailable there; whether Word's ID-collision warning affects DocxDiff's native move markup is
165+
untested. If you need moves lowered to plain del/ins for maximum Word compatibility, use
166+
`engine="wmlcomparer"` with `simplify_move_markup=True`.
167+
162168
## Architecture Overview
163169

164170
Both engines follow the same pattern: a Python wrapper class invokes a self-contained C# binary via subprocess.

tests/test_docxodus_engine.py

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
import re
2+
13
import pytest
24

35
from python_redlines.engines import DocxodusEngine
@@ -18,6 +20,13 @@ def modified_docx():
1820
return load_docx_bytes('tests/fixtures/modified.docx')
1921

2022

23+
def revision_count(stdout):
24+
"""The integer revision count from a Docxodus 'Redline complete: N revision(s) found' line."""
25+
match = re.search(r"Redline complete: (\d+) revision\(s\) found", stdout)
26+
assert match, f"no revision count in stdout: {stdout!r}"
27+
return int(match.group(1))
28+
29+
2130
def test_run_docxodus_with_real_files(original_docx, modified_docx):
2231
wrapper = DocxodusEngine()
2332

@@ -314,8 +323,10 @@ def test_docxodus_explicit_wmlcomparer_matches_default(original_docx, modified_d
314323
_, explicit_stdout, _ = engine.run_redline(
315324
"TestAuthor", original_docx, modified_docx, engine="wmlcomparer",
316325
)
317-
assert "9 revision(s) found" in default_stdout
318-
assert "9 revision(s) found" in explicit_stdout
326+
default_count = revision_count(default_stdout)
327+
explicit_count = revision_count(explicit_stdout)
328+
assert explicit_count == default_count
329+
assert default_count == 9
319330

320331

321332
def test_docxdiff_output_is_a_valid_docx_with_tracked_changes(original_docx, modified_docx):

0 commit comments

Comments
 (0)