iofficeai--officecli/examples/word/document-formatting.md

Document Formatting Showcase

Exercises the docx document property surface — the document-level settings that have no per-paragraph or per-run equivalent. Three files work together:

• document-formatting.py — builds the doc via the officecli Python SDK.
• document-formatting.docx — the generated document.
• document-formatting.md — this file.

The document container

document is a read-only container addressed at path / — you never add or remove it, only set/get its properties:

officecli set file.docx / --prop author="Jane" --prop title="Q3 Report"
officecli get file.docx /            # read the whole property bag back

Built on the officecli-sdk (one resident, writes shipped over the pipe); falls back to the in-repo SDK copy when the package isn't pip-installed.

Regenerate

cd examples/word
pip install officecli-sdk
python3 document-formatting.py
# → document-formatting.docx

Property groups

1. Metadata (core + extended properties)

officecli set file.docx / --prop author="Jane Author" --prop title="Q3 Field Report" \
  --prop subject=Finance --prop keywords="report,q3,finance" \
  --prop description="Quarterly field summary." --prop lastModifiedBy=Editorial
officecli set file.docx / --prop extended.company="Acme Corp" \
  --prop extended.manager="Dana Lead" --prop extended.template="Normal.dotm"

author ↔ creator (alias). A few keys are read-only metadata (category, revisionNumber, …) and only surface on get.

2. Page setup

officecli set file.docx / --prop pageWidth=21cm --prop pageHeight=29.7cm \
  --prop orientation=portrait \
  --prop marginTop=2.54cm --prop marginBottom=2.54cm \
  --prop marginLeft=3.18cm --prop marginRight=3.18cm \
  --prop marginHeader=1.5cm --prop marginFooter=1.75cm
officecli set file.docx / --prop mirrorMargins=true --prop gutterAtTop=false \
  --prop bookFoldPrinting=false

Lengths accept cm/in/pt or bare twips. orientation=landscape swaps width/height. These write the document's section properties (sectPr).

The bare sectPr=present toggle is intentionally not demonstrated: it's an internal dump→batch round-trip marker (forces an empty <w:sectPr/> to survive a rebuild), get-invisible and single-valued, never an interactive edit. Like a table's auto-assigned id, it's settable only for fidelity — the page-setup props above are how you actually shape a section.

3. docDefaults — document-wide run/paragraph defaults

The defaults an unstyled paragraph inherits. In the generated file the body paragraphs carry no run formatting, so they render in Georgia 12pt slate — straight from here, not from the runs:

officecli set file.docx / \
  --prop docDefaults.font=Georgia --prop docDefaults.font.eastAsia=SimSun \
  --prop docDefaults.fontSize=12 --prop docDefaults.color=2F3640 \
  --prop docDefaults.alignment=left \
  --prop docDefaults.spaceAfter=8pt --prop docDefaults.lineSpacing=1.15x

Also: docDefaults.bold, docDefaults.italic, docDefaults.rtl, docDefaults.font.hAnsi, docDefaults.font.complexScript, docDefaults.spaceBefore.

4. Theme — palette accents and major/minor fonts

Remapping the theme shifts every element that references it (styles, charts, shapes) by reference, not by value:

officecli set file.docx / \
  --prop theme.color.accent1=1F6FEB --prop theme.color.accent2=E3572A \
  --prop theme.color.accent3=2DA44E --prop theme.color.hlink=0969DA
officecli set file.docx / \
  --prop theme.font.major.latin=Georgia --prop theme.font.minor.latin=Calibri \
  --prop theme.font.major.eastAsia=SimHei --prop theme.font.minor.eastAsia=SimSun

Full palette keys: accent1..6, dk1/dk2, lt1/lt2, hlink/folHlink.

5. CJK grid & spacing

officecli set file.docx / \
  --prop docGrid.type=lines --prop docGrid.linePitch=312 \
  --prop charSpacingControl=compressPunctuation \
  --prop autoSpaceDE=true --prop autoSpaceDN=true \
  --prop kinsoku=true --prop overflowPunct=true

docGrid.charSpace sets the character grid pitch for docGrid.type=linesAndChars.

6. Font embedding

officecli set file.docx / --prop embedFonts=true --prop embedSystemFonts=false \
  --prop saveSubsetFonts=true

7. Display / print / privacy

officecli set file.docx / \
  --prop evenAndOddHeaders=true --prop autoHyphenation=false \
  --prop defaultTabStop=720 --prop displayBackgroundShape=true \
  --prop removePersonalInformation=false --prop removeDateAndTime=false \
  --prop printFormsData=false

Complete feature coverage

Group	Keys	Visible in render?
Metadata	author, title, subject, keywords, description, lastModifiedBy, extended.company/manager/template	No (file properties)
Page setup	pageWidth, pageHeight, orientation, marginTop/Bottom/Left/Right/Header/Footer/Gutter, mirrorMargins, gutterAtTop, bookFoldPrinting	Yes (geometry)
docDefaults	docDefaults.font[.eastAsia/hAnsi/complexScript], .fontSize, .color, .bold/.italic/.rtl, .alignment, .spaceBefore/.spaceAfter, .lineSpacing	Yes (unstyled text)
Theme	theme.color.accent1..6/dk1/dk2/lt1/lt2/hlink/folHlink, theme.font.major/minor.latin/eastAsia	Yes (themed elements)
CJK grid	docGrid.type/linePitch/charSpace, charSpacingControl, autoSpaceDE/DN, kinsoku, overflowPunct	Yes (CJK layout)
Fonts	embedFonts, embedSystemFonts, saveSubsetFonts	No (portability)
Display/privacy	evenAndOddHeaders, autoHyphenation, defaultTabStop, displayBackgroundShape, removePersonalInformation, removeDateAndTime, printFormsData	Partly

Full list: officecli help docx document.

Set → Get round-trip

The script ends by reading the container back and printing canonical keys:

author = Jane Author
pageWidth = 21cm
pageHeight = 29.7cm
docDefaults.font = Georgia
docDefaults.fontSize = 12pt
theme.color.accent1 = #1F6FEB
docGrid.type = lines

Note normalization on get: colours gain #, font sizes become pt-qualified.