Update README with DocxodusEngine as recommended engine

JSv4 · JSv4 · commit 0cbc2fafe1b2 · 2026-02-10T00:55:59.000-05:00
Rewrite README to prominently feature Docxodus as the recommended comparison
engine, with a link back to the Docxodus repo. Reorganize sections around the
dual-engine architecture and add a quick example.
diff --git a/README.md b/README.md
@@ -3,156 +3,180 @@
 ## Project Goal - Democratizing DOCX Comparisons
 
 The main goal of this project is to address the significant gap in the open-source ecosystem around `.docx` document
-comparison tools. Currently, the process of comparing and generating redline documents (documents that highlight 
-changes between versions) is complex and largely dominated by commercial software. These 
-tools, while effective, often come with cost barriers and limitations in terms of accessibility and integration 
+comparison tools. Currently, the process of comparing and generating redline documents (documents that highlight
+changes between versions) is complex and largely dominated by commercial software. These
+tools, while effective, often come with cost barriers and limitations in terms of accessibility and integration
 flexibility.
 
-`Python-redlines` aims to democratize the ability to run tracked change redlines for .docx, providing the 
+`Python-redlines` aims to democratize the ability to run tracked change redlines for .docx, providing the
 open-source community with a tool to create `.docx` redlines without the need for commercial software. This will let
 more legal hackers and hobbyist innovators experiment and create tooling for enterprise and legal.
 
-## Project Roadmap
+## Comparison Engines
 
-### Step 1. Open-XML-PowerTools `WmlComparer` Wrapper
+Python-Redlines ships with **two comparison engines** — choose the one that best fits your needs:
 
-The [Open-XML-PowerTools](https://github.com/OpenXmlDev/Open-Xml-PowerTools) project historically offered a solid 
-foundation for working with `.docx` files and has an excellent (if imperfect) comparison engine in its `WmlComparer` 
-class. However, Microsoft archived the repository almost five years ago, and a forked repo is not being actively 
-maintained, as its most recent commits dates from 2 years ago and the repo issues list is disabled.
+### `DocxodusEngine` — Recommended
 
-As a first step, our project aims to bring the existing capabilities of WmlCompare into the Python world. Thankfully, 
-XML Power Tools is full cross-platform as it is written in .NET and compiles with the still-maintained .NET 8. The
-resulting binaries can be compiled for the latest versions of Windows, OSX and Linux (Ubuntu specifically, though other
-distributions should work fine too). We have included an OSX build but do not have an OSX machine to test on. Please 
-report an issues by opening a new Issue.
+**[Docxodus](https://github.com/JSv4/Docxodus)** is a modernized .NET 8.0 fork of Open-XML-PowerTools with
+significant improvements:
 
-The initial release has a single engine `XmlPowerToolsEngine`, which is just a Python wrapper for a simple C# utility
-written to leverage WmlComparer for 1-to-1 redlines. We hope this provides a stop-gap capability to Python developers 
-seeking .docx redline capabilities. 
+- **Move detection** — identifies content that was moved rather than deleted and re-inserted
+- **Format change detection** — detects changes to bold, italic, font size, and other run properties
+- **Better table handling** — LCS-based row matching for large tables
+- **Actively maintained** — regular bug fixes and new features
+- **Open XML SDK 3.x compatible** — uses the latest SDK version
 
-**Note**, we don't plan to fork or maintain Open-XML-PowerTools. [Version 4.4.0](https://www.nuget.org/packages/Open-Xml-PowerTools/), 
-which appears to only be compatible with [Open XML SDK < 3.0.0](https://www.nuget.org/packages/DocumentFormat.OpenXml) works
-for now, it needs to be made compatible with the latest versions of the Open XML SDK to extend its life. **There are 
-also some [issues](https://github.com/dotnet/Open-XML-SDK/issues/1634)**, and it seems the only maintainer of 
-Open-XML-PowerTools probably won't fix, and understanding the existing code base is no small task. Please be aware that
-**Open XML PowerTools is not a perfect comparison engine, but it will work for many purposes. Use at your own risk.**
+```python
+from python_redlines import DocxodusEngine
 
-### Step 2. Pure Python Comparison Engine
-
-Looking towards the future, rather than reverse engineer `WmlComparer` and maintain a C# codebase, we envision a 
-comparison engine written in python. We've done some experimentation with [`xmldiff`](https://github.com/Shoobx/xmldiff)
-as the engine to compare the underlying xml of docx files. Specifically, we've built a prototype to unzip `.docx` files, 
-execute an xml comparison using `xmldiff`, and then reconstructed a tracked changes docx with the proper Open XML
-(ooxml) tracked change tags. Preliminary experimentation with this approach has shown promise, indicating its 
-feasibility for handling modifications such as simple span inserts and deletes.
-
-However, this ambitious endeavor is not without its challenges. The intricacies of `.docx` files and the potential for 
-complex, corner-case scenarios necessitate a thoughtful and thorough development process. In the interim, `WmlComparer`
-is a great solution as it has clearly been built to account for many such corner cases, through a development process
-that clearly was influenced by issues discovered by a large user base. The XMLDiff engine will take some time to reach
-a level of maturity similar to WmlComparer. At the moment it is NOT included.
+engine = DocxodusEngine()
+redline_bytes, stdout, stderr = engine.run_redline("AuthorName", original_bytes, modified_bytes)
+```
 
-## Getting started
+### `XmlPowerToolsEngine` — Legacy
 
-### Install .NET Core 8
+Wraps the original [Open-XML-PowerTools](https://github.com/OpenXmlDev/Open-Xml-PowerTools) `WmlComparer`. This
+engine remains available for backward compatibility and for users who prefer the original comparison behavior.
 
-The Open-XML-PowerTools engine we're using in the initial releases requires .NET to run (don't worry, this is very 
-well-supported cross-platform at the moment). Our builds are targeting x86-64 Linux and Windows, however, so you'll 
-need to modify the build script and build new binaries if you want to target another runtime / architecture.
+```python
+from python_redlines import XmlPowerToolsEngine
 
-#### On Linux
+engine = XmlPowerToolsEngine()
+redline_bytes, stdout, stderr = engine.run_redline("AuthorName", original_bytes, modified_bytes)
+```
 
-You can follow [Microsoft's instructions for your Linux distribution](https://learn.microsoft.com/en-us/dotnet/core/install/linux)
+> **Note:** Open-XML-PowerTools was archived by Microsoft and is no longer maintained. It uses an older
+> version of the Open XML SDK. While it works for many purposes, Docxodus is the recommended engine going forward.
 
-#### On Windows
+Both engines share the same API — the only difference is the class you instantiate and the stdout format
+(see [Stdout Differences](#stdout-differences) below).
 
-You can follow [Microsoft's instructions for your Windows vesrion](https://learn.microsoft.com/en-us/dotnet/core/install/windows?tabs=net80)
+## Getting Started
 
 ### Install the Library
 
-At the moment, we are not distributing via pypi. You can easily install directly from this repo, however. 
-
 ```commandline
 pip install git+https://github.com/JSv4/Python-Redlines
 ```
 
-You can add this as a dependency like so
+You can add this as a dependency like so:
 
 ```requirements
-python_redlines @ git+https://github.com/JSv4/Python-Redlines@v0.0.1
+python_redlines @ git+https://github.com/JSv4/Python-Redlines@v0.0.4
 ```
 
 ### Use the Library
 
 If you just want to use the tool, jump into our [quickstart guide](docs/quickstart.md).
 
-## Architecture Overview
+### Quick Example
+
+```python
+from python_redlines import DocxodusEngine
 
-`XmlPowerToolsEngine` is a Python wrapper class for the `redlines` C# command-line tool, source of which is available in 
-[./csproj/Program.cs](./csproj/Program.cs). The redlines utility and wrapper let you compare two docx files and 
-show the differences in tracked changes (a "redline" document).
+# Load your documents as bytes
+with open("original.docx", "rb") as f:
+    original = f.read()
+with open("modified.docx", "rb") as f:
+    modified = f.read()
 
-### C# Functionality
+# Generate a redline document
+engine = DocxodusEngine()
+redline_bytes, stdout, stderr = engine.run_redline("Reviewer", original, modified)
 
-The `redlines` C# utility is a command line tool that requires four arguments:
-1. `author_tag` - A tag to identify the author of the changes.
-2. `original_path.docx` - Path to the original document.
-3. `modified_path.docx` - Path to the modified document.
-4. `redline_path.docx` - Path where the redlined document will be saved.
+# Save the result
+with open("redline.docx", "wb") as f:
+    f.write(redline_bytes)
 
-The Python wrapper, `XmlPowerToolsEngine` and its main method `run_redline()`, simplifies the use of `redlines` by 
-orchestrating its execution with Python and letting you pass in bytes or file paths for the original and modified 
-documents.
+print(stdout)  # e.g. "Redline complete: 9 revision(s) found"
+```
+
+## Architecture Overview
 
-### Packaging
+Both engines follow the same pattern: a Python wrapper class invokes a self-contained C# binary via subprocess.
+The binary takes four arguments: `<author_tag> <original.docx> <modified.docx> <output.docx>`.
 
-The project is structured as follows:
 ```
 python-redlines/
 │
-├── csproj/
-│   ├── bin/
-│   ├── obj/
+├── csproj/                          # XmlPowerTools C# source
 │   ├── Program.cs
-│   ├── redlines.csproj
-│   └── redlines.sln
+│   └── redlines.csproj
 │
-├── docs/
-│   ├── developer-guide.md
-│   └── quickstart.md
+├── docxodus/                        # Docxodus git submodule
+│   └── tools/redline/
+│       ├── Program.cs
+│       └── redline.csproj
 │
 ├── src/
 │   └── python_redlines/
-│       ├── bin/
-│       │   └── .gitignore
-│       ├── dist/
-│       │   ├── .gitignore
-│       │   ├── linux-x64-0.0.1.tar.gz
-│       │   └── win-x64-0.0.1.zip
+│       ├── engines.py               # BaseEngine, XmlPowerToolsEngine, DocxodusEngine
+│       ├── dist/                    # XmlPowerTools compressed binaries
+│       ├── dist_docxodus/           # Docxodus compressed binaries
+│       ├── bin/                     # XmlPowerTools extracted binaries (runtime)
+│       ├── bin_docxodus/            # Docxodus extracted binaries (runtime)
 │       ├── __about__.py
-│       ├── __init__.py
-│       └── engines.py
+│       └── __init__.py
 │
 ├── tests/
-|   ├── fixtures/
-|   ├── test_openxml_differ.py
-|   └── __init__.py
-|
-├── .gitignore
-├── build_differ.py
-├── extract_version.py
-├── License.md
+│   ├── fixtures/
+│   ├── test_openxml_differ.py       # XmlPowerTools integration test
+│   ├── test_docxodus_engine.py      # Docxodus integration test
+│   └── test_engine_contract.py      # Shared contract tests for both engines
+│
+├── build_differ.py                  # Builds both engines for all platforms
 ├── pyproject.toml
 └── README.md
 ```
 
-- `src/your_package/`: Contains the Python wrapper code.
-- `dist/`: Contains the zipped C# binaries for different platforms.
-- `bin/`: Target directory for extracted binaries.
-- `tests/`: Contains test cases and fixtures for the wrapper.
+Pre-compiled binaries for 6 platform targets (linux/win/osx x x64/arm64) are bundled in the wheel for each engine.
+On first use, the appropriate binary is extracted and cached.
+
+### Stdout Differences
+
+The two engines produce slightly different stdout messages:
+
+| Engine | Example stdout |
+|---|---|
+| `XmlPowerToolsEngine` | `Revisions found: 9` |
+| `DocxodusEngine` | `Redline complete: 9 revision(s) found` |
+
+## Development
+
+### Prerequisites
+
+- Python 3.8+
+- .NET 8.0 SDK (for building C# binaries)
+
+### Setup
+
+```bash
+# Clone with submodules
+git clone --recurse-submodules https://github.com/JSv4/Python-Redlines
+cd Python-Redlines
+
+# If you already cloned without submodules
+git submodule update --init --recursive
+```
+
+### Commands
+
+```bash
+# Run tests
+hatch run test
+
+# Run a single test
+hatch run test tests/test_openxml_differ.py::test_run_redlines_with_real_files
+
+# Build C# binaries for all platforms
+hatch run build
+
+# Build Python package
+hatch build
+```
 
-### Detailed Explanation and Dev Setup
+### Detailed Dev Setup
 
 If you want to contribute to the library or want to dive into some of the C# packaging architecture, go to our
 [developer guide](docs/developer-guide.md).
