Import AITURK IDE 1.0.0-beta.1 from Hermes 63279301; preserve MIT license
This commit is contained in:
@@ -0,0 +1,88 @@
|
||||
# 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`:
|
||||
|
||||
```xml
|
||||
<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.
|
||||
Reference in New Issue
Block a user