aiturk-hermes-ide/skills/productivity/docx/references/revisions-and-comments.md

Revisions and Comments — XML details

Deep reference for docx_revisions.py and docx_comments.py. Read this when you need to reason about the raw WordprocessingML, extend the scripts, or debug an unusual document. Everyday use only needs SKILL.md.

Tracked changes (w:ins / w:del)

Word records run-level tracked changes as wrapper elements inside a paragraph (w:p), in the w namespace http://schemas.openxmlformats.org/wordprocessingml/2006/main:

<w:p>
  <w:r><w:t>Base </w:t></w:r>
  <w:ins w:id="1" w:author="Editor" w:date="2026-01-02T03:04:05Z">
    <w:r><w:t>inserted text</w:t></w:r>
  </w:ins>
  <w:del w:id="2" w:author="Editor" w:date="2026-01-02T03:04:05Z">
    <w:r><w:delText>deleted text</w:delText></w:r>
  </w:del>
</w:p>

Key facts the script relies on:

• Deleted text lives in w:delText, not w:t — that is why plain text extraction naturally shows the "accepted" view (insertions visible, deletions hidden).
• Resolution semantics:
  • accept w:ins → unwrap (move child runs up, drop the wrapper)
  • reject w:ins → remove the wrapper and its contents
  • accept w:del → remove the wrapper and its contents
  • reject w:del → rename each w:delText to w:t, then unwrap
• Revisions can appear anywhere block content is allowed: body, table cells (nested tables too), headers, footers, text boxes. The script iterates the body root plus every header/footer part root with root.iter(W+"ins", W+"del"), which finds them at any depth.
• w:id values are unique per revision element, but one logical edit session may produce several elements. accept/reject --id acts on exactly the element(s) carrying that id.

Not handled by the script (detected by docx_read.py --revisions but left alone): paragraph-mark revisions (w:rPr/w:ins on w:pPr), table row insertions/deletions (w:trPr/w:ins), format-change records (w:rPrChange, w:pPrChange), and moves (w:moveFrom/w:moveTo). Moves are rare from typical editors; if present, treat the file with Word itself rather than guessing.

Comments

Three cooperating pieces:

1. word/comments.xml — one w:comment element per comment, carrying w:id, w:author, w:initials, w:date, and body paragraphs. Related from document.xml via the relationship type .../comments and content type application/vnd...wordprocessingml.comments+xml (also needs a [Content_Types].xml override — python-docx's part machinery adds it when the part is registered).
2. Range markers in the story — w:commentRangeStart w:id="N" before the anchored runs, w:commentRangeEnd w:id="N" after them.
3. The reference run — a w:r containing w:commentReference w:id="N", placed right after the range end; it ties the balloon to the location.

docx_comments.py behavior:

• list / delete always work at the XML level, so they handle files from any producer. anchored_text is reconstructed by walking each part root in document order and collecting w:t text between the start and end markers for each id.
• add first isolates the target text into whole runs. If the match starts or ends mid-run, the run is split at the boundary (the split copies w:rPr, so formatting is preserved). Then:
  • python-docx >= 1.2: the native document.add_comment(runs, ...) API is used (it creates the comments part, markers, and reference run itself).
  • older versions or --xml: the script builds word/comments.xml, registers the part + relationship through the opc layer, and inserts the markers/reference manually.
• Deleting a comment removes the w:comment element and all three marker kinds for that id; the anchored document text is untouched.

Modern Word also writes commentsExtended.xml (threading/resolved state). The scripts neither read nor produce it: replies and "resolved" flags are invisible here, and comments added by this skill are plain top-level comments.