# Track Changes Guide ## Overview Track Changes in OpenXML uses revision markup elements to record insertions, deletions, and formatting changes. Each revision has a unique ID, author, and timestamp. --- ## Insertion: `` Wraps runs that were inserted during tracking: ```xml This text was inserted. ``` - `w:id` — unique revision ID (integer, must be unique across document) - `w:author` — free text string identifying the author - `w:date` — ISO 8601 format with timezone: `YYYY-MM-DDTHH:MM:SSZ` - Content inside is normal runs (`w:r`) with optional formatting --- ## Deletion: `` Wraps runs that were deleted during tracking: ```xml This text was deleted. ``` **CRITICAL**: Inside ``, text MUST use ``, NOT ``. Using `` inside a deletion is invalid and will cause corruption or unexpected behavior. Word may silently repair it, but other consumers will fail. --- ## Formatting Change: `` Records that a run's formatting was changed. Placed inside `w:rPr`, it stores the **previous** formatting: ```xml This text was made bold. ``` The outer `w:rPr` holds the **new** (current) formatting. The `w:rPrChange` child holds the **old** (previous) formatting. --- ## Paragraph Property Change: `` Records paragraph-level formatting changes (alignment, spacing, style): ```xml ``` --- ## Revision ID Management - Every revision element (`w:ins`, `w:del`, `w:rPrChange`, `w:pPrChange`, `w:tblPrChange`, etc.) requires a `w:id` attribute - IDs must be **unique integers** across the entire document - IDs should be **monotonically increasing** (not strictly required, but expected by Word) - When adding revisions, scan for the current maximum `w:id` and increment from there ``` Existing max ID: 47 New insertion: w:id="48" New deletion: w:id="49" ``` --- ## Author and Date - **Author**: Free text. Use consistent strings (e.g., `"MiniMaxAI"` for all automated edits) - **Date**: ISO 8601 with UTC timezone marker: `2026-03-21T10:30:00Z` - Must include the `T` separator and `Z` suffix (or `+HH:MM` offset) - Omitting the date is allowed but not recommended --- ## Operations ### Propose Insertion Add `` wrapper around new content at the target location: ```xml Existing text. Proposed new text. More existing text. ``` ### Propose Deletion Wrap existing content in `` and change `` to ``: ```xml Keep this. Remove this. Keep this too. ``` ### Accept a Tracked Change - **Accept insertion**: Remove the `` wrapper, keep the inner runs as normal content - **Accept deletion**: Remove the entire `` element and its content ### Reject a Tracked Change - **Reject insertion**: Remove the entire `` element and its content - **Reject deletion**: Remove the `` wrapper, change `` back to `` --- ## Cross-Paragraph Operations ### Deleting a Paragraph Break (Merging Paragraphs) When tracked deletion spans a paragraph boundary, use `` on the merged paragraph: ```xml First paragraph text. Second paragraph text (now merged). ``` ### Inserting a New Paragraph The entire new paragraph is wrapped in ``: ```xml Entirely new paragraph. ``` The paragraph mark itself is marked as inserted via `w:ins` inside `w:pPr > w:rPr`.