Common Gotchas
Real-world implementation issues and how to solve them.
Lessons learned from building SuperDoc — DOCX editing and tooling.
Word-Specific Issues
tblGrid is required (Word)
Despite the spec marking it optional, Word crashes without w:tblGrid in tables.
sectPr placement matters (Word)
Section properties (w:sectPr) must be the last child of w:body. Word may corrupt the document otherwise.
rsid attributes (Word)
Word adds w:rsid* attributes everywhere for revision tracking. They're optional but Word regenerates them on save.
Cross-Application Issues
Font substitution
If a font isn't available, each application substitutes differently. Embed fonts or stick to common ones.
Measurement units
OOXML uses multiple units: twips (1/20 pt), EMUs (914400/inch), half-points. Be careful with conversions.
Unit Conversion Reference
| Unit | Full Name | Conversion |
|---|---|---|
| twip | Twentieth of a point | 20 twips = 1 pt |
| dxa | Twip (alternate name) | Same as twip |
| EMU | English Metric Unit | 914400 EMU = 1 inch |
| half-point | Half a point | 2 half-points = 1 pt |