SPB Git

Repository Public

docx.md 17.9 KB 211 lines markdown

1<!--2ORIX Docs3File: docs/compatibility/docx.md4Description: Honest feature matrix of the DOCX (WordprocessingML) engine: what is supported, approximated, preserved opaque or not supported, on import and on export, and what was validated against which tool.5Author: Simon-Pierre Boucher6Contact: contact@spboucher.ai7-->8# DOCX compatibility910This page describes what `DocDOCX` does with a Word document, feature by feature. It is not a claim of perfect compatibility.1112## How this was validated — and how it was not1314| Check | Tool | Where |15|---|---|---|16| Import of files written by another implementation | pandoc 3.9.0.2 (8 files), LibreOffice 26.8.2.2 (2 files) | `ImportCorpusTests` |17| Import of constructs no tool here can generate | hand-written OOXML (8 packages) | `ImportHandAuthoredTests` |18| Export → reimport equality of the model, per feature | ORIX Docs itself | `RoundTripTests` |19| Import → edit → export → reimport → export → reimport | ORIX Docs itself | `RoundTripTests`, `CompatibilityReportTests` |20| Our export read by another implementation: text, heading levels, table shape, footnotes, math, links, images, tracked changes, comments | pandoc | `ExternalValidationTests` |21| Our export read as text | macOS `textutil` | `ExternalValidationTests` |22| Our export converted to PDF and text, and re-saved as DOCX then reimported | LibreOffice headless (slow, `ORIX_SLOW_TESTS=1`) | `ExternalValidationTests` |23| Hostile input | generated in the tests | `SecurityTests` |24| Measured numbers on the whole corpus | all of the above | `docs/reports/docx-compatibility.md` |2526**Microsoft Word itself was not used in any automated test and was not launched during development.** The engine follows27ECMA-376 element order and Word's conventions as closely as its author knows them, but until the exported files are opened28in Word and checked by a person, "Word opens it correctly" is unverified for every row below. The same holds for Pages and29Google Docs. Layout (line breaks, pagination, exact fonts) is not compared by any test.3031There is no XML Schema validation of the exported parts: no OOXML schema validator is available offline on the build machine.3233## Legend3435* **Supported** — carried over both ways; export → reimport gives the same model (tested).36* **Approximated** — content kept, behaviour or appearance may differ; a `FormatWarning` of severity `approximated` is raised where the loss is detectable.37* **Preserved opaque** — not interpreted; kept byte for byte in `DocumentModel.preservedParts` and written back.38* **Not supported** — dropped with a `FormatWarning` of severity `dropped`; any text it contains is kept as plain text where there is some.3940## Text and character formatting4142| Feature | Import | Export | Notes |43|---|---|---|---|44| Text, Unicode (emoji, combining marks, astral, RTL scripts) | Supported | Supported | Offsets are UTF-16; characters XML 1.0 cannot carry are removed on export |45| Tab, forced line break (`w:br` ↔ U+2028), soft hyphen, non-breaking hyphen | Supported | Supported | |46| Font family | Supported | Supported | Theme font references (`asciiTheme`) are resolved from the theme part on import; export writes explicit names |47| Font size | Supported | Approximated | DOCX stores half points; other sizes are rounded (warning). The built-in ORIX theme has such sizes (e.g. 27.6 pt → 27.5 pt) |48| Bold, italic, underline, strikethrough | Supported | Supported | Underline styles other than single, and double strikethrough, become plain underline / strikethrough |49| Font weight (100…900) | — | Approximated | Word has regular and bold only (warning) |50| Colour, highlight | Supported | Supported | Named Word highlights use `w:highlight`, other colours `w:shd`; theme colours use the RGB value stored next to them |51| Superscript / subscript, baseline shift, tracking, kerning on/off | Supported | Supported | |52| Small caps, all caps, language | Supported | Supported | |53| Ligatures on/off | Supported | Supported | `w14:ligatures` |54| Character styles (`rStyle`) | Supported | Supported | |55| Hidden text | Approximated | — | Imported as visible text (warning) |56| Outline, shadow, emboss, text borders, character scaling, emphasis marks | Not supported | — | Warning; the text is kept |57| Symbol-font characters (`w:sym`) | Approximated | — | Mapped to the nearest Unicode character (warning) |5859## Paragraphs and styles6061| Feature | Import | Export | Notes |62|---|---|---|---|63| Alignment, indents, first-line / hanging indent, space before / after | Supported | Supported | Lengths are stored in twentieths of a point |64| Line spacing (multiple, exact, at least) | Supported | Supported | |65| Keep with next, keep lines, page break before, widow control | Supported | Supported | |66| Tab stops with alignment and leaders | Supported | Supported | Bar tabs are dropped (warning) |67| Outline level, shading, top / bottom / left borders, right-to-left, hyphenation flag | Supported | Supported | Right and between borders are dropped (warning) |68| Drop caps, text frames | Approximated | Not supported | Imported as ordinary paragraphs; `dropCapLines` is not exported (warning) |69| Contextual spacing, mirrored indents, text direction | Not supported | — | Warning |70| Paragraph and character styles, `basedOn`, `next`, document defaults | Supported | Supported | Built-in styles are recognised by their Word name, so localised style ids map to `Heading1`, `Title` … ; ORIX display names travel as `w:aliases` |71| Numbered headings (`Style.numbered`) | Approximated | Supported | Exported as a real multilevel numbering linked to the heading styles; on import any numbering attached to a heading style sets the flag, whatever its format |72| Table styles | Approximated | Supported | Borders, cell margins, header-row shading and text colour, banded rows ↔ `TableStyle`; other conditional formatting is not applied (warning) |73| List (numbering) styles, latent styles | Not supported | — | The lists that use them are imported |7475## Lists7677| Feature | Import | Export | Notes |78|---|---|---|---|79| Bullets, decimal, lower/upper alpha, lower/upper roman, none | Supported | Supported | Other number formats become decimal (warning) |80| Multilevel patterns (`%1.%2`), start values, start overrides, indents | Supported | Supported | |81| Numbering inherited from a paragraph style | Supported | Approximated | Exported as direct numbering on the paragraph |82| Picture bullets, symbol-font bullets | Approximated | — | Replaced by text bullets |83| Shared counters between several `w:num` of one abstract list | Approximated | — | Each `w:num` is its own list definition |8485## Tables8687| Feature | Import | Export | Notes |88|---|---|---|---|89| Grid, column widths, `gridSpan`, `vMerge`, legacy `hMerge` | Supported | Supported | |90| Table alignment, table borders, cell borders, cell shading, vertical alignment | Supported | Supported | A table frame that is not a full box becomes cell borders |91| Header rows, minimum row height, cell margins (table level) | Supported | Supported | |92| Cell formulas (`=SUM(ABOVE)`) | Supported | Supported | As a field around the cell text |93| Nested tables | Approximated | — | Flattened into the cell's paragraphs (warning): the model has no nested tables |94| Tables in headers, footers and notes | Approximated | — | Flattened into paragraphs (warning) |95| Rows that do not span the grid (`gridBefore` / `gridAfter`) | Approximated | — | Completed with empty cells (warning) |96| Floating tables, rotated cell text, diagonal borders, per-cell margins, table indent | Approximated / Not supported | — | Warning where detectable; per-cell margins and table indent are ignored without warning |97| Two adjacent tables, table at the end of the document | — | Supported | A hidden one-point paragraph is written (Word requires it) and recognised on import |9899## Images, shapes, drawings100101| Feature | Import | Export | Notes |102|---|---|---|---|103| Inline pictures (PNG, JPEG, GIF, TIFF, BMP) | Supported | Supported | Stored once in `DocumentModel.assets`; identified by content |104| Anchored pictures: wrap square / top-and-bottom / behind / in front, alignment, offsets | Supported | Supported | Positions relative to the page become relative to the column / paragraph (warning) |105| Alternative text (`wp:docPr descr`), crop (`a:srcRect`), rotation | Supported | Supported | |106| EMF / WMF pictures | Approximated | Supported as data | Kept; may not display on macOS (warning) |107| Linked (external) pictures | Not supported | — | Never fetched (warning) |108| Preset shapes: rectangle, rounded rectangle, ellipse, line, arrow, callout, with one-line label | Supported | Supported | `ShapeObject` ↔ `wps:wsp`; other presets are dropped or treated as text boxes |109| Text boxes | Approximated | — | Their paragraphs are placed after the anchoring paragraph (warning) |110| Charts, SmartArt, grouped shapes, WordArt, legacy VML drawings | Not supported | — | Warning; pictures and text inside groups are extracted |111| Picture effects (recolour, brightness) | Not supported | — | Warning |112113## Page setup, sections, headers and footers114115| Feature | Import | Export | Notes |116|---|---|---|---|117| Page size, orientation, margins, header / footer distance | Supported | Supported | Known paper sizes are matched within one point |118| Sections: next page, continuous, odd page, even page | Supported | Supported | Word keeps a section's properties in its last paragraph; the model keeps them on the break that starts the next section — converted both ways (tested on LibreOffice and hand-written files) |119| Columns, column gap, separator line | Supported | Supported | Unequal column widths become equal (warning) |120| Page number start and format | Supported | Supported | |121| Headers and footers: default, first page, even pages; `titlePg` | Supported | Supported | A section without its own header inherits the previous one on import; export always writes explicit references |122| Different odd and even pages | Approximated | Approximated | A document-wide setting in Word (warning when sections disagree) |123| Page border | Supported | Approximated | One line style for the four sides; inset limited to 31 pt (warning) |124| Page background colour | Approximated | Approximated | One colour per document in Word |125| Watermark text | Supported | Supported | Read from / written as the WordArt shape Word uses for text watermarks; colour, font and angle are not kept |126| Page and column breaks | Supported | Supported | A break in the middle of a paragraph splits the paragraph (warning) |127| Gutter, line numbering, vertical page alignment | Not supported | — | Warning |128| An empty paragraph that only carries section properties | Approximated | — | Dropped when it follows a table or a break, kept after a paragraph |129130## References, notes, fields131132| Feature | Import | Export | Notes |133|---|---|---|---|134| Hyperlinks (external through relationships, internal anchors) | Supported | Supported | Targets are kept as text and never opened |135| Bookmarks | Approximated | Supported | A bookmark is a position in the model; the extent of a Word bookmark is not kept. `_Toc…`, `_Hlk…`, `_GoBack` are discarded |136| Footnotes and endnotes | Supported | Supported | Custom marks, numbering format and restart rules are not kept |137| Fields PAGE, NUMPAGES, DATE (with picture), TITLE, AUTHOR, SEQ, STYLEREF of a heading level | Supported | Supported | Export writes computed cached results (`Numbering`, `options.pageOf`, `options.pageCount`); PAGE is cached as "1" |138| REF / PAGEREF ↔ `CrossRef` | Supported | Supported | Paragraph targets get hidden bookmarks `_ORIX_T_/L_/N_<id>` so the reference survives a round trip; for Word-written references the display (text, label and number, number) is inferred from what the bookmark covers |139| TOC field ↔ `TOCBlock` (contents, figures, tables) | Supported | Supported | Cached entries are generated content: discarded on import, regenerated on export (page numbers only when `options.pageOf` is given) |140| HYPERLINK fields | Supported | — | Exported as `w:hyperlink` |141| Other fields (MERGEFIELD, IF, form fields …) | Approximated | — | The last displayed text is kept (warning) |142| INCLUDEPICTURE, INCLUDETEXT, LINK, DDE | Not supported | — | Never followed (warning); displayed text kept |143144## Citations and bibliography145146The choice: a citation is exported as a field whose instruction is `ADDIN ORIX_CITATION {json}` (the JSON encoding of147`Citation`: keys, locators, prefixes, suffixes, suppress-author) with the formatted text as cached result — the mechanism148reference managers use, which Word displays and never rewrites. The bibliography database (`DocumentModel.bibliography`) and149the settings Word has no place for (citation style, smart quotes / dashes, theme name) travel in a custom XML data part150(`customXml/itemN.xml`, namespace `https://spboucher.ai/ns/orixdocs/docx/1`), which Word preserves. The generated151bibliography is a content control tagged `ORIX_BIBLIOGRAPHY` holding the formatted entries as ordinary paragraphs.152153| Feature | Import | Export | Notes |154|---|---|---|---|155| ORIX citations and bibliography data | Supported | Supported | Round trip keeps every `Citation` and `BibEntry` (tested) |156| `BibliographyBlock` | Supported | Supported | Entries are regenerated; without `options.citations` a plain list is written (info warning) |157| Word's own citations (`CITATION` fields, `b:Sources`) and bibliography | Approximated | Not supported | Imported as their displayed text (warning); the source list stays a preserved custom XML part |158| Reference-manager fields (Zotero, Mendeley, EndNote) | Approximated | — | Displayed text kept (warning) |159160## Review161162| Feature | Import | Export | Notes |163|---|---|---|---|164| Comments with ranges (within and across paragraphs, in tables and footnotes) | Supported | Supported | Authors and dates kept; comment text is plain (formatting inside comments is flattened) |165| Replies and resolved state (`commentsExtended.xml`) | Supported | Supported | |166| Comments without a range | Approximated | — | Anchored on the nearest run |167| Comments in headers and footers | — | Not supported | Word does not allow them (warning) |168| Tracked insertions and deletions, authors and dates | Supported | Supported | Pieces of one edit (same kind, author and time) inside a paragraph are one revision in the model |169| Tracked formatting (`w:rPrChange`) | Supported | Supported | |170| Tracked paragraph marks | Supported | Supported | |171| Tracked moves | Approximated | — | A deletion and an insertion (warning) |172| Tracked paragraph formatting, tracked table / section / numbering changes | Not supported | — | Current state kept (warning) |173| `trackRevisions` setting | Supported | Supported | |174175## Equations176177| Feature | Import | Export | Notes |178|---|---|---|---|179| `m:oMath` (inline), `m:oMathPara` (display) ↔ LaTeX | Supported | Supported | Fractions, radicals, scripts, n-ary operators, delimiters, accents, functions, limits, matrices, cases, aligned, styles; see `MathConverter` |180| LaTeX source fidelity | — | Approximated | The LaTeX is normalised (`E = mc^2` comes back as `E=mc^{2}`); stable from the second cycle on |181| OMML constructs without LaTeX equivalent | Approximated | — | Their content is kept as text inside the equation (warning) |182| LaTeX the converter cannot parse (user macros, `\color` …) | — | Approximated | Exported as text inside the equation (warning); comes back as `\text{…}` |183184## Package and metadata185186| Feature | Import | Export | Notes |187|---|---|---|---|188| Core properties (title, author, subject, keywords, language, created, modified) | Supported | Supported | |189| Theme, font table, web settings, `docProps/app.xml`, `docProps/custom.xml`, custom XML parts | Preserved opaque | Preserved opaque | Re-validated on export; a part with relationships that leave the preserved set is dropped (e.g. a font table with embedded fonts) |190| Other settings (compatibility options, zoom, default tab stop, attached template, protection) | Not supported | — | `settings.xml` is rewritten; protection and mail merge raise a warning |191| VBA projects, OLE objects, ActiveX, custom UI | Not supported | — | Never executed, never preserved (warning) |192| Digital signatures, glossary (building blocks), embedded fonts, thumbnails | Not supported | — | Warning (thumbnails silently) |193| Content controls (`w:sdt`) | Approximated | — | Content kept, control dropped (warning), except the TOC and ORIX bibliography controls |194| `altChunk`, subdocuments | Not supported | — | Warning |195| Strict (ISO 29500) namespaces, unusual prefixes | Supported | — | Export writes transitional markup |196197## Security behaviour198199* The archive is read with `ZipReader` limits (entry count, entry size, total size, compression ratio); ZIP64, encryption and unsafe entry names are refused.200* XML parts are limited in size (96 MB), depth (256) and element count; any `<!DOCTYPE` or `<!ENTITY` makes the part unreadable, so entity expansion and external entities are impossible.201* Relationship targets are resolved inside the package only; a target that climbs above the package root, is absolute, or has a scheme is ignored with a warning. (`../customXml/item1.xml` from `word/document.xml` is legal OPC and stays inside the package.) External targets are kept as strings and never opened; nothing is ever fetched.202* Import and export run on a thread with a 32 MB stack, so nesting up to the XML depth limit cannot overflow the 512 KB stacks of Swift concurrency threads.203* Corrupted, truncated and structurally mutated packages either import or throw `FormatError`; none crashed in the tests (198 corrupted archives, 200 mutated documents).204205## Known gaps worth knowing before relying on this206207* Nothing here was checked in Microsoft Word.208* Paragraph, table and other identifiers are regenerated on import; only cross-reference targets keep theirs.209* The corpus is small and synthetic; real-world documents will exercise combinations that are not covered.210* `DATE` fields are exported with the current date as cached text, so two exports of a document that contains one differ.211
Files main
Menu

Theme