SPB Git

Repository Public

docx.md 17.9 KB

# DOCX compatibility

This page describes what DocDOCX does with a Word document, feature by feature. It is not a claim of perfect compatibility.

# How this was validated — and how it was not

Check Tool Where
Import of files written by another implementation pandoc 3.9.0.2 (8 files), LibreOffice 26.8.2.2 (2 files) ImportCorpusTests
Import of constructs no tool here can generate hand-written OOXML (8 packages) ImportHandAuthoredTests
Export → reimport equality of the model, per feature ORIX Docs itself RoundTripTests
Import → edit → export → reimport → export → reimport ORIX Docs itself RoundTripTests, CompatibilityReportTests
Our export read by another implementation: text, heading levels, table shape, footnotes, math, links, images, tracked changes, comments pandoc ExternalValidationTests
Our export read as text macOS textutil ExternalValidationTests
Our export converted to PDF and text, and re-saved as DOCX then reimported LibreOffice headless (slow, ORIX_SLOW_TESTS=1) ExternalValidationTests
Hostile input generated in the tests SecurityTests
Measured numbers on the whole corpus all of the above docs/reports/docx-compatibility.md

Microsoft Word itself was not used in any automated test and was not launched during development. The engine follows ECMA-376 element order and Word's conventions as closely as its author knows them, but until the exported files are opened in Word and checked by a person, "Word opens it correctly" is unverified for every row below. The same holds for Pages and Google Docs. Layout (line breaks, pagination, exact fonts) is not compared by any test.

There is no XML Schema validation of the exported parts: no OOXML schema validator is available offline on the build machine.

# Legend

  • Supported — carried over both ways; export → reimport gives the same model (tested).
  • Approximated — content kept, behaviour or appearance may differ; a FormatWarning of severity approximated is raised where the loss is detectable.
  • Preserved opaque — not interpreted; kept byte for byte in DocumentModel.preservedParts and written back.
  • Not supported — dropped with a FormatWarning of severity dropped; any text it contains is kept as plain text where there is some.

# Text and character formatting

Feature Import Export Notes
Text, Unicode (emoji, combining marks, astral, RTL scripts) Supported Supported Offsets are UTF-16; characters XML 1.0 cannot carry are removed on export
Tab, forced line break (w:br ↔ U+2028), soft hyphen, non-breaking hyphen Supported Supported
Font family Supported Supported Theme font references (asciiTheme) are resolved from the theme part on import; export writes explicit names
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)
Bold, italic, underline, strikethrough Supported Supported Underline styles other than single, and double strikethrough, become plain underline / strikethrough
Font weight (100…900) — Approximated Word has regular and bold only (warning)
Colour, highlight Supported Supported Named Word highlights use w:highlight, other colours w:shd; theme colours use the RGB value stored next to them
Superscript / subscript, baseline shift, tracking, kerning on/off Supported Supported
Small caps, all caps, language Supported Supported
Ligatures on/off Supported Supported w14:ligatures
Character styles (rStyle) Supported Supported
Hidden text Approximated — Imported as visible text (warning)
Outline, shadow, emboss, text borders, character scaling, emphasis marks Not supported — Warning; the text is kept
Symbol-font characters (w:sym) Approximated — Mapped to the nearest Unicode character (warning)

# Paragraphs and styles

Feature Import Export Notes
Alignment, indents, first-line / hanging indent, space before / after Supported Supported Lengths are stored in twentieths of a point
Line spacing (multiple, exact, at least) Supported Supported
Keep with next, keep lines, page break before, widow control Supported Supported
Tab stops with alignment and leaders Supported Supported Bar tabs are dropped (warning)
Outline level, shading, top / bottom / left borders, right-to-left, hyphenation flag Supported Supported Right and between borders are dropped (warning)
Drop caps, text frames Approximated Not supported Imported as ordinary paragraphs; dropCapLines is not exported (warning)
Contextual spacing, mirrored indents, text direction Not supported — Warning
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
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
Table styles Approximated Supported Borders, cell margins, header-row shading and text colour, banded rows ↔ TableStyle; other conditional formatting is not applied (warning)
List (numbering) styles, latent styles Not supported — The lists that use them are imported

# Lists

Feature Import Export Notes
Bullets, decimal, lower/upper alpha, lower/upper roman, none Supported Supported Other number formats become decimal (warning)
Multilevel patterns (%1.%2), start values, start overrides, indents Supported Supported
Numbering inherited from a paragraph style Supported Approximated Exported as direct numbering on the paragraph
Picture bullets, symbol-font bullets Approximated — Replaced by text bullets
Shared counters between several w:num of one abstract list Approximated — Each w:num is its own list definition

# Tables

Feature Import Export Notes
Grid, column widths, gridSpan, vMerge, legacy hMerge Supported Supported
Table alignment, table borders, cell borders, cell shading, vertical alignment Supported Supported A table frame that is not a full box becomes cell borders
Header rows, minimum row height, cell margins (table level) Supported Supported
Cell formulas (=SUM(ABOVE)) Supported Supported As a field around the cell text
Nested tables Approximated — Flattened into the cell's paragraphs (warning): the model has no nested tables
Tables in headers, footers and notes Approximated — Flattened into paragraphs (warning)
Rows that do not span the grid (gridBefore / gridAfter) Approximated — Completed with empty cells (warning)
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
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

# Images, shapes, drawings

Feature Import Export Notes
Inline pictures (PNG, JPEG, GIF, TIFF, BMP) Supported Supported Stored once in DocumentModel.assets; identified by content
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)
Alternative text (wp:docPr descr), crop (a:srcRect), rotation Supported Supported
EMF / WMF pictures Approximated Supported as data Kept; may not display on macOS (warning)
Linked (external) pictures Not supported — Never fetched (warning)
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
Text boxes Approximated — Their paragraphs are placed after the anchoring paragraph (warning)
Charts, SmartArt, grouped shapes, WordArt, legacy VML drawings Not supported — Warning; pictures and text inside groups are extracted
Picture effects (recolour, brightness) Not supported — Warning

# Page setup, sections, headers and footers

Feature Import Export Notes
Page size, orientation, margins, header / footer distance Supported Supported Known paper sizes are matched within one point
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)
Columns, column gap, separator line Supported Supported Unequal column widths become equal (warning)
Page number start and format Supported Supported
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
Different odd and even pages Approximated Approximated A document-wide setting in Word (warning when sections disagree)
Page border Supported Approximated One line style for the four sides; inset limited to 31 pt (warning)
Page background colour Approximated Approximated One colour per document in Word
Watermark text Supported Supported Read from / written as the WordArt shape Word uses for text watermarks; colour, font and angle are not kept
Page and column breaks Supported Supported A break in the middle of a paragraph splits the paragraph (warning)
Gutter, line numbering, vertical page alignment Not supported — Warning
An empty paragraph that only carries section properties Approximated — Dropped when it follows a table or a break, kept after a paragraph

# References, notes, fields

Feature Import Export Notes
Hyperlinks (external through relationships, internal anchors) Supported Supported Targets are kept as text and never opened
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
Footnotes and endnotes Supported Supported Custom marks, numbering format and restart rules are not kept
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"
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
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)
HYPERLINK fields Supported — Exported as w:hyperlink
Other fields (MERGEFIELD, IF, form fields …) Approximated — The last displayed text is kept (warning)
INCLUDEPICTURE, INCLUDETEXT, LINK, DDE Not supported — Never followed (warning); displayed text kept

# Citations and bibliography

The choice: a citation is exported as a field whose instruction is ADDIN ORIX_CITATION {json} (the JSON encoding of Citation: keys, locators, prefixes, suffixes, suppress-author) with the formatted text as cached result — the mechanism reference managers use, which Word displays and never rewrites. The bibliography database (DocumentModel.bibliography) and the settings Word has no place for (citation style, smart quotes / dashes, theme name) travel in a custom XML data part (customXml/itemN.xml, namespace https://spboucher.ai/ns/orixdocs/docx/1), which Word preserves. The generated bibliography is a content control tagged ORIX_BIBLIOGRAPHY holding the formatted entries as ordinary paragraphs.

Feature Import Export Notes
ORIX citations and bibliography data Supported Supported Round trip keeps every Citation and BibEntry (tested)
BibliographyBlock Supported Supported Entries are regenerated; without options.citations a plain list is written (info warning)
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
Reference-manager fields (Zotero, Mendeley, EndNote) Approximated — Displayed text kept (warning)

# Review

Feature Import Export Notes
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)
Replies and resolved state (commentsExtended.xml) Supported Supported
Comments without a range Approximated — Anchored on the nearest run
Comments in headers and footers — Not supported Word does not allow them (warning)
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
Tracked formatting (w:rPrChange) Supported Supported
Tracked paragraph marks Supported Supported
Tracked moves Approximated — A deletion and an insertion (warning)
Tracked paragraph formatting, tracked table / section / numbering changes Not supported — Current state kept (warning)
trackRevisions setting Supported Supported

# Equations

Feature Import Export Notes
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
LaTeX source fidelity — Approximated The LaTeX is normalised (E = mc^2 comes back as E=mc^{2}); stable from the second cycle on
OMML constructs without LaTeX equivalent Approximated — Their content is kept as text inside the equation (warning)
LaTeX the converter cannot parse (user macros, \color …) — Approximated Exported as text inside the equation (warning); comes back as \text{…}

# Package and metadata

Feature Import Export Notes
Core properties (title, author, subject, keywords, language, created, modified) Supported Supported
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)
Other settings (compatibility options, zoom, default tab stop, attached template, protection) Not supported — settings.xml is rewritten; protection and mail merge raise a warning
VBA projects, OLE objects, ActiveX, custom UI Not supported — Never executed, never preserved (warning)
Digital signatures, glossary (building blocks), embedded fonts, thumbnails Not supported — Warning (thumbnails silently)
Content controls (w:sdt) Approximated — Content kept, control dropped (warning), except the TOC and ORIX bibliography controls
altChunk, subdocuments Not supported — Warning
Strict (ISO 29500) namespaces, unusual prefixes Supported — Export writes transitional markup

# Security behaviour

  • The archive is read with ZipReader limits (entry count, entry size, total size, compression ratio); ZIP64, encryption and unsafe entry names are refused.
  • 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.
  • 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.
  • 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.
  • Corrupted, truncated and structurally mutated packages either import or throw FormatError; none crashed in the tests (198 corrupted archives, 200 mutated documents).

# Known gaps worth knowing before relying on this

  • Nothing here was checked in Microsoft Word.
  • Paragraph, table and other identifiers are regenerated on import; only cross-reference targets keep theirs.
  • The corpus is small and synthetic; real-world documents will exercise combinations that are not covered.
  • DATE fields are exported with the current date as cached text, so two exports of a document that contains one differ.
Files main
Menu

Theme