pilcrow-docx 0.1.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pilcrow/__init__.py +3 -0
- pilcrow/__main__.py +3 -0
- pilcrow/cli.py +79 -0
- pilcrow/extract.py +365 -0
- pilcrow/files.py +152 -0
- pilcrow/prose.py +34 -0
- pilcrow_docx-0.1.1.dist-info/METADATA +218 -0
- pilcrow_docx-0.1.1.dist-info/RECORD +11 -0
- pilcrow_docx-0.1.1.dist-info/WHEEL +5 -0
- pilcrow_docx-0.1.1.dist-info/entry_points.txt +2 -0
- pilcrow_docx-0.1.1.dist-info/top_level.txt +1 -0
pilcrow/__init__.py
ADDED
pilcrow/__main__.py
ADDED
pilcrow/cli.py
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
"""Refresh files only. Git mutations intentionally do not exist here."""
|
|
2
|
+
|
|
3
|
+
import argparse
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
import sys
|
|
6
|
+
|
|
7
|
+
from . import __version__
|
|
8
|
+
from .extract import DocumentError, extract
|
|
9
|
+
from .files import companions, no_symlinks, orphaned, select, setup, write_if_changed
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def parser():
|
|
13
|
+
result = argparse.ArgumentParser(description="Generate readable DOCX companions for GitHub Desktop.")
|
|
14
|
+
result.add_argument("--version", action="version", version=__version__)
|
|
15
|
+
commands = result.add_subparsers(dest="command", required=True)
|
|
16
|
+
for name in ("export", "check"):
|
|
17
|
+
command = commands.add_parser(name, help="refresh companions" if name == "export" else "read-only freshness check")
|
|
18
|
+
command.add_argument("paths", nargs="*", help="DOCX paths, relative to current directory")
|
|
19
|
+
command.add_argument("--root", type=Path, default=Path.cwd(), help="scope and output root (default: current directory)")
|
|
20
|
+
command.add_argument("--all", action="store_true", help="discover DOCX files recursively within --root")
|
|
21
|
+
command = commands.add_parser("setup", help="opt in to LF text and conservative merge rules in .gitattributes")
|
|
22
|
+
command.add_argument("--root", type=Path, default=Path.cwd())
|
|
23
|
+
return result
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def main(argv=None):
|
|
27
|
+
args = parser().parse_args(argv)
|
|
28
|
+
root = args.root.resolve()
|
|
29
|
+
if not root.is_dir():
|
|
30
|
+
print(f"error: --root is not an existing directory: {root}", file=sys.stderr)
|
|
31
|
+
return 2
|
|
32
|
+
try:
|
|
33
|
+
if args.command == "setup":
|
|
34
|
+
changed = setup(root)
|
|
35
|
+
print(f"{'Updated' if changed else 'Unchanged'} {root / '.gitattributes'}; review and commit through Git.")
|
|
36
|
+
return 0
|
|
37
|
+
if bool(args.paths) == args.all:
|
|
38
|
+
raise ValueError("specify DOCX paths OR --all; use --root to choose discovery/output scope")
|
|
39
|
+
sources = select(root, args.paths, args.all)
|
|
40
|
+
status = 0
|
|
41
|
+
for source in sources:
|
|
42
|
+
label = source.relative_to(root).as_posix()
|
|
43
|
+
try:
|
|
44
|
+
no_symlinks(source, root)
|
|
45
|
+
result = extract(source)
|
|
46
|
+
changed = []
|
|
47
|
+
for path, content in zip(companions(root, source), result.outputs().values()):
|
|
48
|
+
no_symlinks(path, root)
|
|
49
|
+
if args.command == "export":
|
|
50
|
+
if write_if_changed(path, content, root):
|
|
51
|
+
changed.append(path.name)
|
|
52
|
+
elif not path.exists() or path.read_bytes() != content:
|
|
53
|
+
changed.append(path.name)
|
|
54
|
+
if args.command == "check" and changed:
|
|
55
|
+
print(f"STALE/MISSING {label}: {', '.join(changed)}; run pilcrow export with the same scope")
|
|
56
|
+
status = max(status, 1)
|
|
57
|
+
elif changed:
|
|
58
|
+
print(f"EXPORTED {label}: {', '.join(changed)}")
|
|
59
|
+
else:
|
|
60
|
+
print(f"FRESH {label}: no normalized prose/review changes detected (not a complete document comparison)")
|
|
61
|
+
for warning in result.metadata["warnings"]:
|
|
62
|
+
print(f"warning: {label}: {warning}", file=sys.stderr)
|
|
63
|
+
except (OSError, ValueError, DocumentError) as exc:
|
|
64
|
+
print(f"error: {label}: {exc}", file=sys.stderr)
|
|
65
|
+
status = 2
|
|
66
|
+
if args.all:
|
|
67
|
+
for path in orphaned(root):
|
|
68
|
+
print(f"ORPHAN {path.relative_to(root)}: source deleted or renamed; remove this companion manually if intentional", file=sys.stderr)
|
|
69
|
+
status = max(status, 1)
|
|
70
|
+
if not sources:
|
|
71
|
+
print("No DOCX documents selected within this scope.")
|
|
72
|
+
return status
|
|
73
|
+
except (OSError, ValueError) as exc:
|
|
74
|
+
print(f"error: {exc}", file=sys.stderr)
|
|
75
|
+
return 2
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
if __name__ == "__main__":
|
|
79
|
+
raise SystemExit(main())
|
pilcrow/extract.py
ADDED
|
@@ -0,0 +1,365 @@
|
|
|
1
|
+
"""Read WordprocessingML without modifying the package or requiring Word.
|
|
2
|
+
|
|
3
|
+
This is a prose view, not a Word renderer. All omissions are reported in metadata.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from collections import Counter
|
|
7
|
+
from dataclasses import dataclass
|
|
8
|
+
import hashlib
|
|
9
|
+
import json
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
import posixpath
|
|
12
|
+
import re
|
|
13
|
+
from zipfile import BadZipFile, ZipFile
|
|
14
|
+
|
|
15
|
+
from defusedxml import ElementTree as ET
|
|
16
|
+
|
|
17
|
+
from .prose import normalize, sentences
|
|
18
|
+
|
|
19
|
+
W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
|
|
20
|
+
R = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
|
|
21
|
+
NS = {"w": W}
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def w(name):
|
|
25
|
+
return f"{{{W}}}{name}"
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def attr(node, name, default=""):
|
|
29
|
+
return node.get(w(name), default)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class DocumentError(ValueError):
|
|
33
|
+
"""An input is unavailable or cannot be safely interpreted."""
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
@dataclass
|
|
37
|
+
class Extraction:
|
|
38
|
+
prose: str
|
|
39
|
+
metadata: dict
|
|
40
|
+
|
|
41
|
+
def outputs(self):
|
|
42
|
+
return {
|
|
43
|
+
".prose.md": self.prose.encode("utf-8"),
|
|
44
|
+
".meta.json": (json.dumps(self.metadata, ensure_ascii=False, indent=2,
|
|
45
|
+
sort_keys=True) + "\n").encode("utf-8"),
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
class Reader:
|
|
50
|
+
def __init__(self, package):
|
|
51
|
+
self.package = package
|
|
52
|
+
self.names = set(package.namelist())
|
|
53
|
+
self.warnings = {
|
|
54
|
+
"Formatting and page layout are not compared; unchanged prose is not an identical document."
|
|
55
|
+
}
|
|
56
|
+
self.review = []
|
|
57
|
+
self.links = []
|
|
58
|
+
self.fields = []
|
|
59
|
+
self.styles = {}
|
|
60
|
+
self.field_stack = []
|
|
61
|
+
self.part = "word/document.xml"
|
|
62
|
+
self.rels = {}
|
|
63
|
+
self.features = Counter()
|
|
64
|
+
|
|
65
|
+
def xml(self, name):
|
|
66
|
+
try:
|
|
67
|
+
return ET.fromstring(self.package.read(name))
|
|
68
|
+
except Exception as exc:
|
|
69
|
+
raise DocumentError(f"cannot parse {name}: {exc}") from exc
|
|
70
|
+
|
|
71
|
+
def relationships(self, part):
|
|
72
|
+
path = posixpath.join(posixpath.dirname(part), "_rels", posixpath.basename(part) + ".rels")
|
|
73
|
+
result = {}
|
|
74
|
+
if path not in self.names:
|
|
75
|
+
return result
|
|
76
|
+
for rel in self.xml(path):
|
|
77
|
+
target = rel.get("Target", "")
|
|
78
|
+
external = rel.get("TargetMode") == "External"
|
|
79
|
+
if not external:
|
|
80
|
+
target = posixpath.normpath(posixpath.join(posixpath.dirname(part), target))
|
|
81
|
+
target = target.lstrip("/")
|
|
82
|
+
if target.startswith("../"):
|
|
83
|
+
raise DocumentError(f"relationship escapes package: {path}")
|
|
84
|
+
result[rel.get("Id")] = (rel.get("Type", "").rsplit("/", 1)[-1], target, external)
|
|
85
|
+
return result
|
|
86
|
+
|
|
87
|
+
def warn(self, message):
|
|
88
|
+
self.warnings.add(message)
|
|
89
|
+
|
|
90
|
+
def raw_text(self, node):
|
|
91
|
+
return normalize("".join(
|
|
92
|
+
(n.text or "") if n.tag in {w("t"), w("delText")} else " "
|
|
93
|
+
for n in node.iter() if n.tag in {w("t"), w("delText"), w("tab"), w("br"), w("cr")}
|
|
94
|
+
))
|
|
95
|
+
|
|
96
|
+
def inline(self, node):
|
|
97
|
+
tag = node.tag
|
|
98
|
+
local = tag.rsplit("}", 1)[-1]
|
|
99
|
+
if tag in {w("del"), w("ins"), w("moveFrom"), w("moveTo")}:
|
|
100
|
+
self.review.append({"kind": local, "author": attr(node, "author"),
|
|
101
|
+
"text": self.raw_text(node), "part": self.part})
|
|
102
|
+
if local in {"del", "moveFrom"}:
|
|
103
|
+
return ""
|
|
104
|
+
if tag == w("t"):
|
|
105
|
+
# XML source line wrapping is whitespace, unlike Word's explicit w:br.
|
|
106
|
+
return re.sub(r"\s", " ", node.text or "")
|
|
107
|
+
if tag == w("delText"):
|
|
108
|
+
return ""
|
|
109
|
+
if tag in {w("br"), w("cr")}:
|
|
110
|
+
return "\n"
|
|
111
|
+
if tag == w("tab"):
|
|
112
|
+
return " "
|
|
113
|
+
if tag == w("noBreakHyphen"):
|
|
114
|
+
return "\u2011"
|
|
115
|
+
if tag == w("softHyphen"):
|
|
116
|
+
return "\u00ad"
|
|
117
|
+
if tag in {w("footnoteReference"), w("endnoteReference")}:
|
|
118
|
+
kind = "footnote" if tag == w("footnoteReference") else "endnote"
|
|
119
|
+
self.features[kind + " references"] += 1
|
|
120
|
+
return f"[^{kind}-{attr(node, 'id')}]"
|
|
121
|
+
if tag == w("hyperlink"):
|
|
122
|
+
rid = node.get(f"{{{R}}}id")
|
|
123
|
+
rel = self.rels.get(rid)
|
|
124
|
+
target = rel[1] if rel else "#" + attr(node, "anchor")
|
|
125
|
+
if rid and not rel:
|
|
126
|
+
self.warn("Some hyperlink relationships are missing; destinations may be incomplete.")
|
|
127
|
+
visible = "".join(self.inline(child) for child in node)
|
|
128
|
+
self.links.append({"text": normalize(visible), "target": target, "part": self.part})
|
|
129
|
+
return visible
|
|
130
|
+
if tag == w("fldChar"):
|
|
131
|
+
kind = attr(node, "fldCharType")
|
|
132
|
+
if kind == "begin":
|
|
133
|
+
self.field_stack.append([])
|
|
134
|
+
elif kind == "end" and self.field_stack:
|
|
135
|
+
self.record_field("".join(self.field_stack.pop()))
|
|
136
|
+
self.warn("Fields use saved display text, which can be stale; codes are fingerprinted, not evaluated (including Zotero).")
|
|
137
|
+
return ""
|
|
138
|
+
if tag == w("instrText"):
|
|
139
|
+
if self.field_stack:
|
|
140
|
+
self.field_stack[-1].append(node.text or "")
|
|
141
|
+
else:
|
|
142
|
+
self.record_field(node.text or "")
|
|
143
|
+
return ""
|
|
144
|
+
if tag == w("fldSimple"):
|
|
145
|
+
self.record_field(attr(node, "instr"))
|
|
146
|
+
self.warn("Fields use saved display text, which can be stale; codes are fingerprinted, not evaluated (including Zotero).")
|
|
147
|
+
if local in {"drawing", "pict", "object", "txbxContent", "oMath", "oMathPara", "AlternateContent", "altChunk", "sym"}:
|
|
148
|
+
self.warn(f"Unsupported {local}: content is not rendered in prose; inspect the DOCX in Word.")
|
|
149
|
+
self.features[local] += 1
|
|
150
|
+
return f"[Unsupported {local}]"
|
|
151
|
+
if tag in {w("pPr"), w("rPr"), w("sdtPr"), w("sdtEndPr")}:
|
|
152
|
+
return ""
|
|
153
|
+
return "".join(self.inline(child) for child in node)
|
|
154
|
+
|
|
155
|
+
def record_field(self, instruction):
|
|
156
|
+
value = normalize(instruction)
|
|
157
|
+
self.fields.append({"command": value.split(" ", 1)[0],
|
|
158
|
+
"sha256": hashlib.sha256(value.encode()).hexdigest(), "part": self.part})
|
|
159
|
+
|
|
160
|
+
def properties(self, paragraph):
|
|
161
|
+
direct = paragraph.find("w:pPr", NS)
|
|
162
|
+
style = direct.find("w:pStyle", NS) if direct is not None else None
|
|
163
|
+
style_id = attr(style, "val") if style is not None else ""
|
|
164
|
+
properties = []
|
|
165
|
+
if direct is not None:
|
|
166
|
+
properties.append(direct)
|
|
167
|
+
seen = set()
|
|
168
|
+
while style_id in self.styles and style_id not in seen:
|
|
169
|
+
seen.add(style_id)
|
|
170
|
+
current = self.styles[style_id]
|
|
171
|
+
prop = current.find("w:pPr", NS)
|
|
172
|
+
if prop is not None:
|
|
173
|
+
properties.append(prop)
|
|
174
|
+
based = current.find("w:basedOn", NS)
|
|
175
|
+
style_id = attr(based, "val") if based is not None else ""
|
|
176
|
+
return properties, attr(style, "val") if style is not None else ""
|
|
177
|
+
|
|
178
|
+
def paragraph(self, node):
|
|
179
|
+
text = self.inline(node)
|
|
180
|
+
lines = sentences(text)
|
|
181
|
+
if not lines:
|
|
182
|
+
return ""
|
|
183
|
+
props, style_id = self.properties(node)
|
|
184
|
+
outline = next((p.find("w:outlineLvl", NS) for p in props
|
|
185
|
+
if p.find("w:outlineLvl", NS) is not None), None)
|
|
186
|
+
heading = re.fullmatch(r"Heading([1-9])", style_id, flags=re.I)
|
|
187
|
+
if outline is not None and attr(outline, "val").isdigit() and int(attr(outline, "val")) < 9:
|
|
188
|
+
level = min(6, int(attr(outline, "val")) + 1)
|
|
189
|
+
else:
|
|
190
|
+
level = min(6, int(heading[1])) if heading else 0
|
|
191
|
+
num = next((p.find("w:numPr", NS) for p in props if p.find("w:numPr", NS) is not None), None)
|
|
192
|
+
if level:
|
|
193
|
+
return "#" * level + " " + normalize(text)
|
|
194
|
+
if num is not None:
|
|
195
|
+
num_id = num.find("w:numId", NS)
|
|
196
|
+
if num_id is None or attr(num_id, "val") != "0":
|
|
197
|
+
self.warn("List boundaries and indentation are retained; automatic numbering and bullet glyphs are not reconstructed.")
|
|
198
|
+
ilvl = num.find("w:ilvl", NS)
|
|
199
|
+
depth = attr(ilvl, "val", "0") if ilvl is not None else "0"
|
|
200
|
+
indent = " " * min(20, int(depth)) if depth.isdigit() else ""
|
|
201
|
+
return indent + "- " + ("\n" + indent + " ").join(lines)
|
|
202
|
+
return "\n".join(lines)
|
|
203
|
+
|
|
204
|
+
def blocks(self, node):
|
|
205
|
+
parts = []
|
|
206
|
+
for child in node:
|
|
207
|
+
if child.tag == w("p"):
|
|
208
|
+
value = self.paragraph(child)
|
|
209
|
+
elif child.tag == w("tbl"):
|
|
210
|
+
value = self.table(child)
|
|
211
|
+
elif child.tag in {w("sectPr"), w("tcPr"), w("trPr"), w("tblPr"), w("tblGrid"), w("sdtPr"), w("sdtEndPr")}:
|
|
212
|
+
continue
|
|
213
|
+
elif child.tag in {w("del"), w("moveFrom")}:
|
|
214
|
+
self.inline(child) # record review, omit deleted blocks
|
|
215
|
+
continue
|
|
216
|
+
elif child.tag in {w("altChunk"), w("drawing"), w("pict"), w("object")}:
|
|
217
|
+
value = self.inline(child)
|
|
218
|
+
else:
|
|
219
|
+
if child.tag in {w("ins"), w("moveTo")}:
|
|
220
|
+
self.review.append({"kind": child.tag.rsplit("}", 1)[-1], "author": attr(child, "author"),
|
|
221
|
+
"text": self.raw_text(child), "part": self.part})
|
|
222
|
+
value = self.blocks(child)
|
|
223
|
+
if value:
|
|
224
|
+
parts.append(value)
|
|
225
|
+
return "\n\n".join(parts)
|
|
226
|
+
|
|
227
|
+
def table_items(self, node, tag):
|
|
228
|
+
"""Unwrap content controls without descending into nested tables."""
|
|
229
|
+
for child in node:
|
|
230
|
+
if child.tag == w(tag):
|
|
231
|
+
yield child
|
|
232
|
+
elif child.tag in {w("sdt"), w("sdtContent"), w("customXml"), w("ins"), w("moveTo")}:
|
|
233
|
+
if child.tag in {w("ins"), w("moveTo")}:
|
|
234
|
+
self.warn("Tracked table structure changes are only partially represented; inspect the DOCX.")
|
|
235
|
+
yield from self.table_items(child, tag)
|
|
236
|
+
elif child.tag in {w("del"), w("moveFrom")}:
|
|
237
|
+
self.inline(child)
|
|
238
|
+
|
|
239
|
+
def table(self, node):
|
|
240
|
+
self.features["tables"] += 1
|
|
241
|
+
lines = ["[Table]"]
|
|
242
|
+
# Explicit cells avoid Markdown pipe escaping and ambiguity for multi-paragraph cells.
|
|
243
|
+
for row in self.table_items(node, "tr"):
|
|
244
|
+
if row.find("w:trPr/w:del", NS) is not None:
|
|
245
|
+
self.warn("Tracked table structure changes are only partially represented; inspect the DOCX.")
|
|
246
|
+
continue
|
|
247
|
+
lines.append("[Row]")
|
|
248
|
+
for cell in self.table_items(row, "tc"):
|
|
249
|
+
span = cell.find("w:tcPr/w:gridSpan", NS)
|
|
250
|
+
merge = cell.find("w:tcPr/w:vMerge", NS)
|
|
251
|
+
label = "[Cell"
|
|
252
|
+
if span is not None:
|
|
253
|
+
label += " span=" + attr(span, "val")
|
|
254
|
+
if merge is not None:
|
|
255
|
+
label += " vertical-merge=" + attr(merge, "val", "continue")
|
|
256
|
+
lines.extend([label + "]", self.blocks(cell) or "(empty)"])
|
|
257
|
+
lines.append("[/Row]")
|
|
258
|
+
lines.append("[/Table]")
|
|
259
|
+
return "\n\n".join(lines)
|
|
260
|
+
|
|
261
|
+
def audit(self, tree):
|
|
262
|
+
# This small allowlist is intentionally conservative: unknown constructs warn.
|
|
263
|
+
known = set("document body p r t delText tab br cr noBreakHyphen softHyphen pPr rPr sectPr tbl tr tc tblPr trPr tcPr tblGrid gridCol sdt sdtContent sdtPr sdtEndPr customXml smartTag ins del moveFrom moveTo hyperlink bookmarkStart bookmarkEnd proofErr permStart permEnd commentRangeStart commentRangeEnd commentReference footnoteReference endnoteReference footnotes footnote endnotes endnote footnoteRef endnoteRef comments comment hdr ftr fldChar instrText fldSimple lastRenderedPageBreak moveFromRangeStart moveFromRangeEnd moveToRangeStart moveToRangeEnd".split())
|
|
264
|
+
def visit(node):
|
|
265
|
+
local = node.tag.rsplit("}", 1)[-1]
|
|
266
|
+
if node.tag.startswith("{" + W + "}") and local not in known:
|
|
267
|
+
self.warn(f"Unsupported Word construct {local}; its semantics are not fully compared.")
|
|
268
|
+
if local.endswith("Pr") or local in {"tblGrid", "sdtEndPr"}:
|
|
269
|
+
for descendant in node.iter():
|
|
270
|
+
name = descendant.tag.rsplit("}", 1)[-1]
|
|
271
|
+
if name in {"vanish", "webHidden", "specVanish"}:
|
|
272
|
+
self.warn("Hidden text is included; visibility formatting is not applied.")
|
|
273
|
+
if name.endswith("Change") or name in {"ins", "del", "cellIns", "cellDel", "cellMerge"}:
|
|
274
|
+
self.warn("Tracked formatting or structure changes are not fully represented; inspect the DOCX.")
|
|
275
|
+
return
|
|
276
|
+
if not node.tag.startswith("{" + W + "}"):
|
|
277
|
+
self.warn(f"Unsupported XML construct {local}; content may be omitted or approximate.")
|
|
278
|
+
for child in node:
|
|
279
|
+
visit(child)
|
|
280
|
+
visit(tree)
|
|
281
|
+
|
|
282
|
+
def render_part(self, part, tree):
|
|
283
|
+
self.part, self.rels = part, self.relationships(part)
|
|
284
|
+
self.audit(tree)
|
|
285
|
+
value = self.blocks(tree)
|
|
286
|
+
if self.field_stack:
|
|
287
|
+
self.warn("Unclosed field codes found; saved display text may be incomplete.")
|
|
288
|
+
while self.field_stack:
|
|
289
|
+
self.record_field("".join(self.field_stack.pop()))
|
|
290
|
+
return value
|
|
291
|
+
|
|
292
|
+
def extract(self):
|
|
293
|
+
if "word/document.xml" not in self.names:
|
|
294
|
+
raise DocumentError("missing word/document.xml; expected a standard DOCX package")
|
|
295
|
+
main = self.xml("word/document.xml")
|
|
296
|
+
if main.tag != w("document") or main.find("w:body", NS) is None:
|
|
297
|
+
raise DocumentError("unsupported Word XML dialect or missing document body (Strict OOXML is not supported)")
|
|
298
|
+
main_rels = self.relationships("word/document.xml")
|
|
299
|
+
supported = {"word/document.xml"}
|
|
300
|
+
for kind, target, external in main_rels.values():
|
|
301
|
+
if kind == "styles" and not external:
|
|
302
|
+
if target not in self.names:
|
|
303
|
+
raise DocumentError(f"missing related part {target}")
|
|
304
|
+
self.styles = {attr(s, "styleId"): s for s in self.xml(target)}
|
|
305
|
+
supported.add(target)
|
|
306
|
+
prose = [self.render_part("word/document.xml", main.find("w:body", NS))]
|
|
307
|
+
# All supported related stories are distinct; never combine headers with body prose.
|
|
308
|
+
stories = sorted({(kind, target) for kind, target, external in main_rels.values()
|
|
309
|
+
if kind in {"footnotes", "endnotes", "comments", "header", "footer"} and not external})
|
|
310
|
+
for kind, part in stories:
|
|
311
|
+
if part not in self.names:
|
|
312
|
+
raise DocumentError(f"missing related part {part}")
|
|
313
|
+
supported.add(part)
|
|
314
|
+
tree = self.xml(part)
|
|
315
|
+
if kind == "comments":
|
|
316
|
+
self.audit(tree)
|
|
317
|
+
for comment in tree:
|
|
318
|
+
self.review.append({"kind": "comment", "author": attr(comment, "author"),
|
|
319
|
+
"text": self.raw_text(comment), "part": part})
|
|
320
|
+
self.warn("Comment text and authors are recorded; anchors, threads, dates, and resolution status are not compared.")
|
|
321
|
+
elif kind in {"footnotes", "endnotes"}:
|
|
322
|
+
for note in tree:
|
|
323
|
+
if attr(note, "type") in {"separator", "continuationSeparator", "continuationNotice"}:
|
|
324
|
+
continue
|
|
325
|
+
singular = kind[:-1]
|
|
326
|
+
prose.append(f"[^{singular}-{attr(note, 'id')}]:\n\n" + self.render_part(part, note))
|
|
327
|
+
else:
|
|
328
|
+
prose.append(f"## {kind.title()} ({part})\n\n" + self.render_part(part, tree))
|
|
329
|
+
self.warn("Headers and footers are shown by part; page/section placement is not reconstructed.")
|
|
330
|
+
for name in sorted(self.names):
|
|
331
|
+
if name in supported or name.endswith("/") or name.endswith(".rels") or name == "[Content_Types].xml" or name.startswith("docProps/"):
|
|
332
|
+
continue
|
|
333
|
+
if name in {"word/settings.xml", "word/webSettings.xml", "word/fontTable.xml", "word/numbering.xml"} or name.startswith("word/theme/"):
|
|
334
|
+
continue
|
|
335
|
+
self.warn(f"Unrendered package part: {name}; changes to its content are not compared.")
|
|
336
|
+
if self.features["footnote references"] and not any(k == "footnotes" for k, _ in stories):
|
|
337
|
+
self.warn("Footnote references have no related footnotes part.")
|
|
338
|
+
if self.features["endnote references"] and not any(k == "endnotes" for k, _ in stories):
|
|
339
|
+
self.warn("Endnote references have no related endnotes part.")
|
|
340
|
+
metadata = {"schema": 1, "view": "accept-insertions-omit-deletions",
|
|
341
|
+
"coverage": "partial-prose", "warnings": sorted(self.warnings),
|
|
342
|
+
"review": self.review, "hyperlinks": self.links, "fields": self.fields}
|
|
343
|
+
return Extraction("\n\n".join(p for p in prose if p).rstrip() + "\n", metadata)
|
|
344
|
+
|
|
345
|
+
|
|
346
|
+
def extract(path: Path) -> Extraction:
|
|
347
|
+
try:
|
|
348
|
+
before = path.stat()
|
|
349
|
+
with ZipFile(path) as package:
|
|
350
|
+
infos = package.infolist()
|
|
351
|
+
if len(infos) > 4096 or sum(i.file_size for i in infos) > 64 * 1024 * 1024:
|
|
352
|
+
raise DocumentError("package exceeds safety limits (4096 entries / 64 MiB uncompressed)")
|
|
353
|
+
if any(i.file_size > 16 * 1024 * 1024 for i in infos):
|
|
354
|
+
raise DocumentError("package part exceeds 16 MiB safety limit")
|
|
355
|
+
if len({i.filename for i in infos}) != len(infos):
|
|
356
|
+
raise DocumentError("duplicate ZIP entries")
|
|
357
|
+
result = Reader(package).extract()
|
|
358
|
+
after = path.stat()
|
|
359
|
+
if (before.st_ino, before.st_size, before.st_mtime_ns) != (after.st_ino, after.st_size, after.st_mtime_ns):
|
|
360
|
+
raise DocumentError("document changed while reading; finish saving and retry")
|
|
361
|
+
return result
|
|
362
|
+
except (OSError, BadZipFile, RuntimeError, ValueError) as exc:
|
|
363
|
+
if isinstance(exc, DocumentError):
|
|
364
|
+
raise
|
|
365
|
+
raise DocumentError(f"cannot read DOCX: {exc}; finish saving, check permissions, and retry") from exc
|
pilcrow/files.py
ADDED
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
"""Explicit scope, Git-aware discovery, and atomic companion writes."""
|
|
2
|
+
|
|
3
|
+
import os
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
import subprocess
|
|
6
|
+
import tempfile
|
|
7
|
+
|
|
8
|
+
OUTPUT = ".pilcrow"
|
|
9
|
+
EXCLUDED = {OUTPUT, ".git", ".venv", "venv", "env", "node_modules", "__pycache__", ".tox", ".nox", "build", "dist"}
|
|
10
|
+
SUFFIXES = (".prose.md", ".meta.json")
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def git(root, *args):
|
|
14
|
+
try:
|
|
15
|
+
return subprocess.run(["git", "-C", str(root), *args], capture_output=True, check=False)
|
|
16
|
+
except FileNotFoundError:
|
|
17
|
+
return None
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def eligible(path):
|
|
21
|
+
return (path.suffix.lower() == ".docx" and not path.name.startswith("~$")
|
|
22
|
+
and not any(p in EXCLUDED for p in path.parts))
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def no_symlinks(path, root):
|
|
26
|
+
"""Do not follow inputs or outputs outside scope through symlink components."""
|
|
27
|
+
relative = path.relative_to(root)
|
|
28
|
+
current = root
|
|
29
|
+
for component in relative.parts:
|
|
30
|
+
current = current / component
|
|
31
|
+
if current.is_symlink():
|
|
32
|
+
raise ValueError(f"symlink paths are not supported: {current}")
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def discover(root):
|
|
36
|
+
probe = git(root, "rev-parse", "--is-inside-work-tree")
|
|
37
|
+
has_git = any((p / ".git").exists() for p in (root, *root.parents))
|
|
38
|
+
if has_git and (probe is None or probe.returncode != 0):
|
|
39
|
+
raise ValueError("Git discovery unavailable in this repository; install/check Git or select explicit paths")
|
|
40
|
+
if probe and probe.returncode == 0 and probe.stdout.strip() == b"true":
|
|
41
|
+
listing = git(root, "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", ".")
|
|
42
|
+
if listing.returncode:
|
|
43
|
+
raise ValueError("Git discovery failed: " + os.fsdecode(listing.stderr).strip())
|
|
44
|
+
paths = {Path(os.fsdecode(p)) for p in listing.stdout.split(b"\0") if p}
|
|
45
|
+
# Deleted tracked inputs are handled by the orphan scan, not resurrected.
|
|
46
|
+
selected = []
|
|
47
|
+
for path in sorted(paths):
|
|
48
|
+
if not eligible(path):
|
|
49
|
+
continue
|
|
50
|
+
source = root / path
|
|
51
|
+
no_symlinks(source, root)
|
|
52
|
+
try:
|
|
53
|
+
source.stat()
|
|
54
|
+
except FileNotFoundError:
|
|
55
|
+
continue
|
|
56
|
+
selected.append(source)
|
|
57
|
+
return selected
|
|
58
|
+
paths = []
|
|
59
|
+
def onerror(error):
|
|
60
|
+
raise error
|
|
61
|
+
for directory, dirs, files in os.walk(root, onerror=onerror, followlinks=False):
|
|
62
|
+
dirs[:] = sorted(d for d in dirs if d not in EXCLUDED and not (Path(directory) / d).is_symlink())
|
|
63
|
+
paths.extend(Path(directory) / f for f in files if eligible(Path(f)))
|
|
64
|
+
return sorted(paths, key=str)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def select(root, paths, all_documents):
|
|
68
|
+
if all_documents:
|
|
69
|
+
return discover(root)
|
|
70
|
+
selected = []
|
|
71
|
+
for raw in paths:
|
|
72
|
+
path = Path(os.path.abspath(raw)) # lexical path: do not resolve a hidden symlink
|
|
73
|
+
try:
|
|
74
|
+
relative = path.relative_to(root)
|
|
75
|
+
except ValueError as exc:
|
|
76
|
+
raise ValueError(f"{raw}: outside --root {root}") from exc
|
|
77
|
+
if not eligible(relative):
|
|
78
|
+
raise ValueError(f"{raw}: expected a DOCX outside lock/output/environment paths")
|
|
79
|
+
selected.append(path)
|
|
80
|
+
return sorted(set(selected), key=str)
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def companions(root, source):
|
|
84
|
+
stem = root / OUTPUT / source.relative_to(root)
|
|
85
|
+
return [Path(str(stem) + suffix) for suffix in SUFFIXES]
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def orphaned(root):
|
|
89
|
+
base = root / OUTPUT
|
|
90
|
+
no_symlinks(base, root)
|
|
91
|
+
if not base.exists():
|
|
92
|
+
return []
|
|
93
|
+
result = []
|
|
94
|
+
for directory, dirs, files in os.walk(base, followlinks=False):
|
|
95
|
+
for name in dirs:
|
|
96
|
+
no_symlinks(Path(directory) / name, root)
|
|
97
|
+
for name in files:
|
|
98
|
+
path = Path(directory) / name
|
|
99
|
+
for suffix in SUFFIXES:
|
|
100
|
+
if name.endswith(suffix):
|
|
101
|
+
source = root / str(path.relative_to(base))[:-len(suffix)]
|
|
102
|
+
if not source.exists():
|
|
103
|
+
result.append(path)
|
|
104
|
+
return sorted(result, key=str)
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def write_if_changed(path, content, root):
|
|
108
|
+
no_symlinks(path, root)
|
|
109
|
+
if path.exists() and path.read_bytes() == content:
|
|
110
|
+
return False
|
|
111
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
112
|
+
temporary = None
|
|
113
|
+
try:
|
|
114
|
+
with tempfile.NamedTemporaryFile(dir=path.parent, prefix=".pilcrow-tmp-", delete=False) as handle:
|
|
115
|
+
temporary = Path(handle.name)
|
|
116
|
+
handle.write(content)
|
|
117
|
+
handle.flush()
|
|
118
|
+
os.fsync(handle.fileno())
|
|
119
|
+
os.replace(temporary, path)
|
|
120
|
+
finally:
|
|
121
|
+
if temporary is not None:
|
|
122
|
+
temporary.unlink(missing_ok=True)
|
|
123
|
+
return True
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
START = b"# BEGIN Pilcrow generated review rules"
|
|
127
|
+
END = b"# END Pilcrow generated review rules"
|
|
128
|
+
RULES = b"\n".join([
|
|
129
|
+
START,
|
|
130
|
+
b"*.[dD][oO][cC][xX] -merge",
|
|
131
|
+
b".pilcrow/** text eol=lf -merge",
|
|
132
|
+
END,
|
|
133
|
+
]) + b"\n"
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def setup(root):
|
|
137
|
+
path = root / ".gitattributes"
|
|
138
|
+
no_symlinks(path, root)
|
|
139
|
+
old = path.read_bytes() if path.exists() else b""
|
|
140
|
+
if START in old or END in old:
|
|
141
|
+
if old.count(START) != 1 or old.count(END) != 1 or old.index(END) < old.index(START):
|
|
142
|
+
raise ValueError("malformed Pilcrow block in .gitattributes; repair it before setup")
|
|
143
|
+
start = old.index(START)
|
|
144
|
+
end = old.index(END) + len(END)
|
|
145
|
+
if old[end:end+2] == b"\r\n":
|
|
146
|
+
end += 2
|
|
147
|
+
elif old[end:end+1] == b"\n":
|
|
148
|
+
end += 1
|
|
149
|
+
new = old[:start] + RULES + old[end:]
|
|
150
|
+
else:
|
|
151
|
+
new = old + (b"\n" if old and not old.endswith(b"\n") else b"") + RULES
|
|
152
|
+
return write_if_changed(path, new, root)
|
pilcrow/prose.py
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
"""Deliberately small English-oriented sentence segmentation, not an NLP model."""
|
|
2
|
+
|
|
3
|
+
import re
|
|
4
|
+
|
|
5
|
+
ABBREVIATIONS = frozenset(
|
|
6
|
+
"mr mrs ms dr prof sr jr st vs etc e.g i.e fig figs eq eqs ref refs vol no pp al".split()
|
|
7
|
+
)
|
|
8
|
+
# Split only after terminal punctuation followed by whitespace. Keep closing quotes
|
|
9
|
+
# and reference brackets with the sentence. Decimal points have no following space.
|
|
10
|
+
BOUNDARY = re.compile(r'''[.!?]+[”’"')\]]*\s+''')
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def normalize(text: str) -> str:
|
|
14
|
+
return " ".join(text.split())
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def sentences(text: str) -> list[str]:
|
|
18
|
+
"""Keep explicit Word line breaks; normalize other whitespace after joining runs."""
|
|
19
|
+
result = []
|
|
20
|
+
for line in text.split("\n"):
|
|
21
|
+
line = normalize(line)
|
|
22
|
+
start = 0
|
|
23
|
+
for match in BOUNDARY.finditer(line):
|
|
24
|
+
end = match.end()
|
|
25
|
+
prefix = line[:match.start() + 1]
|
|
26
|
+
token = re.search(r"([\w.]+)\.$", prefix)
|
|
27
|
+
if token and (token[1].lower() in ABBREVIATIONS
|
|
28
|
+
or re.fullmatch(r"(?:[A-Za-z]\.)*[A-Za-z]", token[1])):
|
|
29
|
+
continue
|
|
30
|
+
result.append(line[start: end].strip())
|
|
31
|
+
start = end
|
|
32
|
+
if line[start:]:
|
|
33
|
+
result.append(line[start:])
|
|
34
|
+
return result
|
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pilcrow-docx
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: Readable DOCX companion diffs for ordinary Git workflows
|
|
5
|
+
Requires-Python: >=3.10
|
|
6
|
+
Description-Content-Type: text/markdown
|
|
7
|
+
Requires-Dist: defusedxml<1,>=0.7.1
|
|
8
|
+
|
|
9
|
+
# Pilcrow
|
|
10
|
+
|
|
11
|
+
Pilcrow makes Word text changes reviewable in GitHub Desktop. Keep editing the
|
|
12
|
+
`.docx`; export readable companion files and commit both through your normal Git
|
|
13
|
+
workflow. **The DOCX is authoritative.** The prose is a generated review artifact,
|
|
14
|
+
not an editable replacement or a round-trip format.
|
|
15
|
+
|
|
16
|
+
This is an independent, small Python implementation, conceptually inspired by the
|
|
17
|
+
companion-file approach of stet. No source or tests were copied from that project.
|
|
18
|
+
|
|
19
|
+
## Install locally
|
|
20
|
+
|
|
21
|
+
Requires Python 3.10 or later. Git is needed for repository discovery and the Git
|
|
22
|
+
workflow. Word is not required to export. From this project's directory:
|
|
23
|
+
|
|
24
|
+
```sh
|
|
25
|
+
python -m pip install .
|
|
26
|
+
pilcrow --help
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Use `python3` instead of `python` on systems where needed. A virtual environment
|
|
30
|
+
is recommended (`python -m venv .venv`); activate it before installing:
|
|
31
|
+
|
|
32
|
+
- macOS/Linux: `source .venv/bin/activate`
|
|
33
|
+
- Windows PowerShell: `.venv\Scripts\Activate.ps1`
|
|
34
|
+
- Windows Command Prompt: `.venv\Scripts\activate.bat`
|
|
35
|
+
|
|
36
|
+
If activation is unavailable, invoke `.venv/bin/python` or
|
|
37
|
+
`.venv\Scripts\python.exe` directly with `-m pip install .`, then `-m pilcrow`.
|
|
38
|
+
For development, use `python -m pip install -e .`.
|
|
39
|
+
|
|
40
|
+
Pilcrow uses Python's ZIP reader and `defusedxml` for XML parsing. There is no Word
|
|
41
|
+
process, cloud service, AI connection, watcher, or background service. Extraction
|
|
42
|
+
never writes to the DOCX.
|
|
43
|
+
|
|
44
|
+
## Baseline, then review a change
|
|
45
|
+
|
|
46
|
+
In **your document repository**, choose an explicit scope. For example:
|
|
47
|
+
|
|
48
|
+
```sh
|
|
49
|
+
pilcrow export --all --root .
|
|
50
|
+
pilcrow check --all --root .
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Or select documents (paths are relative to your current directory):
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
pilcrow export "report.docx" "chapters/Methods and results.docx" --root .
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Outputs retain the complete source-relative filename:
|
|
60
|
+
|
|
61
|
+
```text
|
|
62
|
+
report.docx
|
|
63
|
+
chapters/Methods and results.docx
|
|
64
|
+
.pilcrow/report.docx.prose.md
|
|
65
|
+
.pilcrow/report.docx.meta.json
|
|
66
|
+
.pilcrow/chapters/Methods and results.docx.prose.md
|
|
67
|
+
.pilcrow/chapters/Methods and results.docx.meta.json
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
1. Export a baseline. In GitHub Desktop, review and commit the DOCX and its two
|
|
71
|
+
companion files together. Do not put `.pilcrow/` in `.gitignore`.
|
|
72
|
+
2. Edit and save the DOCX in Word, or use a separate document-editing tool.
|
|
73
|
+
3. Run the same `pilcrow export` command again.
|
|
74
|
+
4. In Desktop's **Changes** view, select the `.prose.md` file to read the text diff;
|
|
75
|
+
inspect `.meta.json` for review/coverage changes. The DOCX may still say binary
|
|
76
|
+
changed. Review formatting/images in Word when relevant.
|
|
77
|
+
5. Commit the DOCX and both companions together through Desktop, then push and
|
|
78
|
+
branch normally. Desktop's **History** view can show committed companion diffs.
|
|
79
|
+
|
|
80
|
+
Pilcrow never stages, commits, pushes, switches branches, or merges. No direct
|
|
81
|
+
DOCX text converter is installed. The CLI and an ordinary Git diff have been
|
|
82
|
+
tested; **the Microsoft Word / GitHub Desktop GUI workflow has not been tested in
|
|
83
|
+
this Linux environment**. See [manual validation](docs/manual-validation.md).
|
|
84
|
+
See an [actual generated prose and Git diff example](docs/example.md).
|
|
85
|
+
Old commits without companions will not gain prose diffs automatically; there is
|
|
86
|
+
no backfill or history rewriting.
|
|
87
|
+
|
|
88
|
+
## Scope and discovery
|
|
89
|
+
|
|
90
|
+
- `--root` defaults to the **current directory**, never an automatically detected
|
|
91
|
+
repository top. It controls both discovery and the location of `.pilcrow/`.
|
|
92
|
+
Use the same root each time. From a subdirectory, pass `--root ..` deliberately
|
|
93
|
+
if the output belongs at the parent. Explicit paths remain relative to the
|
|
94
|
+
current directory, not to `--root`.
|
|
95
|
+
- Supply paths **or** `--all`. No arguments does not silently scan the machine.
|
|
96
|
+
Passing a directory as a document is an error; use `--all --root directory`.
|
|
97
|
+
- Inside Git, `--all` uses `git ls-files` for tracked and nonignored untracked
|
|
98
|
+
files within the selected root. Tracked files remain included even if an ignore
|
|
99
|
+
rule matches. An explicitly selected ignored DOCX is allowed.
|
|
100
|
+
- Outside Git, `--all` recursively walks the selected directory. Git ignore rules
|
|
101
|
+
only apply inside a Git worktree; there is no separate ignore syntax.
|
|
102
|
+
- Both modes exclude Word lock files (`~$…`), `.pilcrow`, `.git`, `.venv`, `venv`,
|
|
103
|
+
`env`, `node_modules`, `__pycache__`, `.tox`, `.nox`, `build`, and `dist`.
|
|
104
|
+
Extension matching is case-insensitive. Unicode and spaces are supported.
|
|
105
|
+
- Symlink files/paths are rejected; directory walking does not follow symlink
|
|
106
|
+
directories. Submodule documents are not recursively discovered from the parent
|
|
107
|
+
repository: select a root inside the submodule.
|
|
108
|
+
- `--all` reports orphan companions after source deletion/rename. Remove the old
|
|
109
|
+
companion files manually if the deletion was intentional and commit those
|
|
110
|
+
deletions together. Export never automatically deletes review history files.
|
|
111
|
+
Explicit-file mode checks only selected inputs, not unrelated orphans.
|
|
112
|
+
|
|
113
|
+
## Check before committing
|
|
114
|
+
|
|
115
|
+
```sh
|
|
116
|
+
pilcrow check --all --root .
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
`check` is read-only, even when files are missing. It recomputes expected prose and
|
|
120
|
+
metadata and compares bytes, tolerating ZIP order/compression, run boundaries,
|
|
121
|
+
save timestamps, and other ignored Word metadata. It does not use a DOCX-byte hash.
|
|
122
|
+
|
|
123
|
+
| Exit | Meaning |
|
|
124
|
+
| --- | --- |
|
|
125
|
+
| 0 | Successful export, or companions match the supported normalized view |
|
|
126
|
+
| 1 | Missing/stale companions in `check`, or orphan companions in either command |
|
|
127
|
+
| 2 | Invalid selection, unreadable/malformed input, unsafe path, or write failure |
|
|
128
|
+
|
|
129
|
+
Errors identify the file; remaining selected documents are processed after a
|
|
130
|
+
per-document error. Retry after Word has finished saving if a file is temporarily
|
|
131
|
+
unreadable or changes during extraction. A fresh result means **no supported
|
|
132
|
+
prose/review changes detected**, never that the complete document is identical.
|
|
133
|
+
Warnings appear on stderr and in metadata even for fresh results. Known coverage
|
|
134
|
+
limitations do not themselves cause a nonzero exit.
|
|
135
|
+
|
|
136
|
+
Writes use a temporary file and atomic replacement in the destination directory.
|
|
137
|
+
Byte-identical outputs keep their existing modification times. Each file is
|
|
138
|
+
atomic, **not the whole pair or batch**: if interrupted between files, run `check`
|
|
139
|
+
and export again. Avoid concurrent exports into the same root.
|
|
140
|
+
|
|
141
|
+
## Branches and conflicts
|
|
142
|
+
|
|
143
|
+
Opt in to conservative merge rules once, from your document repository root:
|
|
144
|
+
|
|
145
|
+
```sh
|
|
146
|
+
pilcrow setup --root .
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
This appends a managed block to `.gitattributes`, preserving other rules. Repeating
|
|
150
|
+
it is harmless. Review and commit the file through Desktop. Rules mark DOCX and
|
|
151
|
+
all `.pilcrow/` files `-merge` (Git's binary merge driver), and companion files as
|
|
152
|
+
`text eol=lf`. Both-sided modifications conflict instead of automatically merging
|
|
153
|
+
prose into a document that never existed. Normal one-sided changes still merge.
|
|
154
|
+
More-specific nested attributes can override these rules; inspect with
|
|
155
|
+
`git check-attr merge -- "report.docx" ".pilcrow/report.docx.prose.md"` if needed.
|
|
156
|
+
|
|
157
|
+
When branches conflict:
|
|
158
|
+
|
|
159
|
+
1. Preserve copies of both versions of the DOCX outside the conflicted path.
|
|
160
|
+
2. Choose the authoritative version or reconcile the documents manually in Word.
|
|
161
|
+
If using Git commands to select a side, make sure you understand that side in
|
|
162
|
+
the current merge/rebase. Pilcrow does not make this choice.
|
|
163
|
+
3. Put the resolved DOCX at its repository path. Regenerate its companions, even
|
|
164
|
+
if Git did not flag them as conflicted. Never independently accept a merged
|
|
165
|
+
prose artifact as the Word document.
|
|
166
|
+
4. Run `pilcrow check --all --root .`. Inspect the resulting text and Word file,
|
|
167
|
+
then mark resolutions and commit using your normal Git workflow.
|
|
168
|
+
|
|
169
|
+
Git commit identity attributes a snapshot, not every contributor between saves.
|
|
170
|
+
For basic snapshot attribution:
|
|
171
|
+
|
|
172
|
+
```sh
|
|
173
|
+
git blame -- ".pilcrow/report.docx.prose.md"
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Word tracked-change authors (included in review metadata) are separate from Git
|
|
177
|
+
authors. Neither proves an edit came from an AI. Companion metadata can contain
|
|
178
|
+
comment authors and deleted text: review it before sharing, just as you would the
|
|
179
|
+
DOCX. No automatic OOXML merging or sentence-lineage system is provided.
|
|
180
|
+
|
|
181
|
+
## Coverage and maintenance
|
|
182
|
+
|
|
183
|
+
See [coverage, normalization, and backlog](docs/limitations.md). The prose retains
|
|
184
|
+
common headings, list indentation, tables, notes, headers, and footers. Tracked
|
|
185
|
+
insertions/move destinations are included and deletions/move sources omitted.
|
|
186
|
+
Complex tracked structure/layout is limited and reported. Images, equations,
|
|
187
|
+
text boxes, and embedded objects are not rendered. Formatting-only edits can
|
|
188
|
+
leave both companions unchanged and still matter in Word.
|
|
189
|
+
|
|
190
|
+
Run the generated-fixture suite:
|
|
191
|
+
|
|
192
|
+
```sh
|
|
193
|
+
python -m unittest discover -s tests -v
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
The implementation has four small modules: `prose.py` (segmentation), `extract.py`
|
|
197
|
+
(OOXML coverage), `files.py` (scope and writes), and `cli.py` (commands). Tests
|
|
198
|
+
include temporary Git repositories and failure cases. Generated fixtures do not
|
|
199
|
+
establish complete Microsoft Word compatibility. No real/private document corpus
|
|
200
|
+
was available for this implementation.
|
|
201
|
+
|
|
202
|
+
## Releases
|
|
203
|
+
|
|
204
|
+
Every push to `main` runs `.github/workflows/publish.yml`. Release runs are queued
|
|
205
|
+
and each checks out the current `main`, including previous release version bumps.
|
|
206
|
+
The workflow increments the patch version in `pyproject.toml` and
|
|
207
|
+
`src/pilcrow/__init__.py`, builds and validates the distributions, runs the test
|
|
208
|
+
suite, and verifies the installed CLI version. It then commits the version bump, pushes
|
|
209
|
+
the commit and tag atomically, and creates a GitHub release with the wheel and
|
|
210
|
+
source archive. Release commits use `chore(release): ... [skip ci]` to avoid loops.
|
|
211
|
+
If `main` advances during a build, the push fails safely before publishing; the
|
|
212
|
+
queued run checks out the newer `main`.
|
|
213
|
+
|
|
214
|
+
A separate job uploads those same release files to PyPI using Trusted Publishing.
|
|
215
|
+
Configure the PyPI publisher for owner `omertekin2002`, repository `Pilcrow`,
|
|
216
|
+
workflow `publish.yml`, and GitHub environment `pypi`. No PyPI API token is needed.
|
|
217
|
+
If only the PyPI upload fails, fix its configuration and use **Re-run failed jobs**
|
|
218
|
+
on that workflow run to retry the existing release without bumping the version.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
pilcrow/__init__.py,sha256=SHxFEmR686sCnhCyRPpfstKSXZgHkZSFE4KLot0OaiU,87
|
|
2
|
+
pilcrow/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
|
|
3
|
+
pilcrow/cli.py,sha256=8D9z4Vze4Uve1-x8yuQUEspXWhvR-8KFDOc2P7VkZQ4,3838
|
|
4
|
+
pilcrow/extract.py,sha256=xHE0FknzDGidJDs-hCZ4x9ArZhCXt6hN-OCev0cgPUk,18015
|
|
5
|
+
pilcrow/files.py,sha256=TwIm_w-l0vEAfWHbASCsHSF3KdKhrciFMpsNPDbDNJ4,5480
|
|
6
|
+
pilcrow/prose.py,sha256=5SwTG5B2Em_QytDSLz2Py1m_vufEIlM1CT7aVLSmxuU,1240
|
|
7
|
+
pilcrow_docx-0.1.1.dist-info/METADATA,sha256=zEv5Ks5du1Mb8WgrGAN94jLzx9VxBAUri3UppPYuw8E,10319
|
|
8
|
+
pilcrow_docx-0.1.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
9
|
+
pilcrow_docx-0.1.1.dist-info/entry_points.txt,sha256=V0Bl0qhFOwa5rlCckMTrPka1c5B7WcIrQn9OFd8bYXY,45
|
|
10
|
+
pilcrow_docx-0.1.1.dist-info/top_level.txt,sha256=QhsgKd8tPgpmf1BAxLKPhxS75oH-GVQAYibYvTbSNn8,8
|
|
11
|
+
pilcrow_docx-0.1.1.dist-info/RECORD,,
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
pilcrow
|