Skip to content

Commit d7310f0

Browse files
JSv4claude
andcommitted
docs: document the Clippit engine in READMEs
These README edits failed to land in the original commit alongside the ci/publish/contract edits. Add Clippit to the engine list, install examples, monorepo table, and stdout-format table. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent da1f887 commit d7310f0

2 files changed

Lines changed: 25 additions & 8 deletions

File tree

‎README.md‎

Lines changed: 23 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,8 @@ comparison settings, and how the packages are built and distributed.
4040

4141
## Comparison Engines
4242

43-
Python-Redlines provides **two comparison engines**. `DocxodusEngine` is the default and
44-
recommended choice; `XmlPowerToolsEngine` remains available as a legacy option.
43+
Python-Redlines provides **three comparison engines**. `DocxodusEngine` is the default and
44+
recommended choice; `ClippitEngine` and `XmlPowerToolsEngine` are also available.
4545

4646
### `DocxodusEngine` — Default (Recommended)
4747

@@ -61,6 +61,19 @@ engine = DocxodusEngine()
6161
redline_bytes, stdout, stderr = engine.run_redline("AuthorName", original_bytes, modified_bytes)
6262
```
6363

64+
### `ClippitEngine`
65+
66+
Wraps [Clippit](https://github.com/sergey-tihon/Clippit), an actively-maintained .NET 8 fork of
67+
Open-XML-PowerTools. It uses the same `WmlComparer` API as `XmlPowerToolsEngine` (same options and
68+
`Revisions found: N` stdout) but rides a maintained, modern dependency.
69+
70+
```python
71+
from python_redlines import ClippitEngine
72+
73+
engine = ClippitEngine()
74+
redline_bytes, stdout, stderr = engine.run_redline("AuthorName", original_bytes, modified_bytes)
75+
```
76+
6477
### `XmlPowerToolsEngine` — Legacy
6578

6679
Wraps the original [Open-XML-PowerTools](https://github.com/OpenXmlDev/Open-Xml-PowerTools) `WmlComparer`. This
@@ -76,7 +89,7 @@ redline_bytes, stdout, stderr = engine.run_redline("AuthorName", original_bytes,
7689
> **Note:** Open-XML-PowerTools was archived by Microsoft and is no longer maintained. It uses an older
7790
> version of the Open XML SDK. While it works for many purposes, Docxodus is the recommended engine going forward.
7891
79-
Both engines share the same API — the only difference is the class you instantiate and the stdout format
92+
All engines share the same API — the only difference is the class you instantiate and the stdout format
8093
(see [Stdout Differences](#stdout-differences) below).
8194

8295
## Getting Started
@@ -92,8 +105,9 @@ as extras:
92105

93106
```commandline
94107
pip install python-redlines[docxodus] # Docxodus engine
108+
pip install python-redlines[clippit] # Clippit engine (maintained OOXML PowerTools fork)
95109
pip install python-redlines[ooxmlpowertools] # Open-XML-PowerTools engine
96-
pip install python-redlines[all] # both engines
110+
pip install python-redlines[all] # all engines
97111
```
98112

99113
Prebuilt wheels are available for Linux, macOS, and Windows (x64 and arm64); `pip`
@@ -146,12 +160,13 @@ redline_bytes, stdout, stderr = engine.run_redline(
146160

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

149-
The repository is a **monorepo of three separately-published packages**:
163+
The repository is a **monorepo of four separately-published packages**:
150164

151165
| Package | PyPI name | Contents |
152166
|---|---|---|
153167
| `packages/core` | `python-redlines` | Pure-Python wrapper; no binaries |
154168
| `packages/ooxmlpowertools` | `python-redlines-ooxmlpowertools` | Open-XML-PowerTools engine binary |
169+
| `packages/clippit` | `python-redlines-clippit` | Clippit engine binary |
155170
| `packages/docxodus` | `python-redlines-docxodus` | Docxodus engine binary |
156171

157172
The core package's `[docxodus]` / `[ooxmlpowertools]` / `[all]` extras pull in the
@@ -189,6 +204,7 @@ The two engines produce slightly different stdout messages:
189204
| Engine | Example stdout |
190205
|---|---|
191206
| `XmlPowerToolsEngine` | `Revisions found: 9` |
207+
| `ClippitEngine` | `Revisions found: 9` |
192208
| `DocxodusEngine` | `Redline complete: 9 revision(s) found` |
193209

194210
## Development
@@ -211,8 +227,8 @@ git submodule update --init --recursive
211227
# Build the engine binaries for your platform (RIDs: linux-x64, win-x64, osx-arm64, ...)
212228
python build_differ.py linux-x64
213229

214-
# Install all three packages editable
215-
pip install -e packages/core -e packages/ooxmlpowertools -e packages/docxodus pytest
230+
# Install all packages editable
231+
pip install -e packages/core -e packages/ooxmlpowertools -e packages/clippit -e packages/docxodus pytest
216232
```
217233

218234
### Commands

‎packages/core/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,9 @@ the one(s) you need as extras:
88

99
```bash
1010
pip install python-redlines[docxodus] # Docxodus engine
11+
pip install python-redlines[clippit] # Clippit engine
1112
pip install python-redlines[ooxmlpowertools] # Open-XML-PowerTools engine
12-
pip install python-redlines[all] # both
13+
pip install python-redlines[all] # all
1314
```
1415

1516
Binaries are prebuilt for each platform and embedded in the companion package's

0 commit comments

Comments
 (0)