docs: announce the docxdiff engine and tabulate the three engine choices#26
Open
JSv4 wants to merge 1 commit into
Open
docs: announce the docxdiff engine and tabulate the three engine choices#26JSv4 wants to merge 1 commit into
JSv4 wants to merge 1 commit into
Conversation
The docxdiff engine shipped in 0.3.0 but the README buried it. Announce it directly under the Quick Start: what it is, that it is off by default, the one-argument opt-in, and a request for feedback on real documents. Replace the two-engine narrative with a table of the three actual choices -- Docxodus/wmlcomparer, Docxodus/docxdiff, and the legacy XmlPowerToolsEngine -- and disambiguate the naming, since two of the three descend from WmlComparer and only one of those is maintained. Split the settings section into what each setting does and which engine accepts it. The per-engine matrix records that docxdiff raises ValueError for the three settings it cannot honour, and that XmlPowerToolsEngine silently discards every keyword argument, including engine -- previously undocumented. Do not claim upgrading leaves output unchanged. The docxdiff flag is opt-in, but the Docxodus binary moved v5.4.2 -> v7.0.0 and carries upstream WmlComparer fixes, so default-path output can differ from 0.2.1 on its own.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
docxdiffshipped in 0.3.0, but you had to read to the bottom of the README to learn it existed. This surfaces it, and reorganizes the engine documentation around the three choices users actually have.Announce the new engine up top
A callout now sits directly under the Quick Start: what
docxdiffis, that it is off by default, the one-argument opt-in, and an explicit ask for feedback on real documents.Three choices, one table
The README described "two comparison engines." There are really three ways to compare, across two engine classes:
wmlcomparerDocxodusEngine()WmlComparerdocxdiffDocxodusEngine()+engine="docxdiff"XmlPowerToolsEngine()WmlComparerChoices 1 and 3 are both called "WmlComparer," which is genuinely confusing, so the text now says which is the maintained fork and which is the archived original.
Settings, split into two tables
One table for what each setting does; a second for which engine accepts it —
✅,❌ ValueError, or— ignored.The matrix was derived by calling
_build_commandfor every kwarg against both algorithms rather than transcribed by hand, and cross-checked againstDocxodusEngine._WMLCOMPARER_ONLY. It documents one thing that was previously unstated anywhere:XmlPowerToolsEnginesilently discards every keyword argument, includingengine.One correction
An earlier draft of this change claimed upgrading to 0.3.0 "will not change a single byte of your existing output." That is false and has been removed. The
docxdiffflag is opt-in, but the Docxodus binary itself moved v5.4.2 → v7.0.0 in that release and carries upstreamWmlComparerfixes (header references, table anchoring), so default-path output can differ from 0.2.1 independently of the new flag. The README now says so and suggests diffing a representative document if byte-level stability matters.Notes
#choosing-an-engine, whichpackages/core/README.mdlinks to and which is already live on PyPI for 0.3.0.packages/core/README.mdis the PyPI long description and is frozen at what 0.3.0 shipped; it would only refresh on a future release.