iOfficeAI / iOfficeAI/OfficeCLI
Help text for pptx shape `spacing` states the wrong unit — following the documented example produces 200pt letter-spacing
- Dominant language
- C#
- Stars
- 30.7k
- Forks
- 2.1k
- Avg merge
- 9d 8h
- Merged PRs (30d)
- 5
Description
## Summary
`schemas/help/pptx/shape.json` documents the shape-level `spacing` property as taking
**hundredths of a point**, with the example `--prop spacing=200`. The code treats the
input as **points** and multiplies by 100. Following the documented example therefore
writes `spc="20000"` — 200pt of letter-spacing — which scatters the characters of a
text box across (and beyond) the slide.
The same property is documented correctly in `schemas/help/pptx/run.json`, so the
two help files contradict each other for the same OOXML attribute.
This is a documentation defect only; the code behaves consistently and correctly.
## Version
- `officecli 1.0.143`, built from source at `459b1a47` (current `main`)
- macOS 15 / arm64, .NET SDK 10.0.302
## Reproduction
```sh
officecli create repro.pptx
officecli add repro.pptx / --type slide --prop layout=blank
# Exactly the example printed by `officecli help pptx add shape`
officecli add repro.pptx '/slide[1]' --type shape \
--prop name=DocExample --prop text="DOC EXAMPLE" --prop size=18 --prop spacing=200
# The example printed for the run element, same OOXML attribute
officecli add repro.pptx '/slide[1]' --type shape \
--prop name=RunExample --prop text="RUN EXAMPLE" --prop size=18 --prop y=5cm --prop spacing=2
unzip -p repro.pptx ppt/slides/slide1.xml | grep -o 'spc="[-0-9]*"'
```
### Actual
```
spc="20000" # from spacing=200 -> 200pt tracking on 18pt text
spc="200" # from spacing=2 -> 2pt tracking
```
At 18pt, `spacing=200` renders one character per line, spread down and off the slide.
The two examples rendered side by side (documented example above, `run.json` example below):
### Expected
The documented example should produce a usable result. `spacing=200` under the
documented unit (1/100 pt) would mean 2pt, i.e. `spc="200"`.
## Why the documentation is the wrong side
Four independent write paths all treat the input as points and multiply by 100:
- `src/officecli/Handlers/Pptx/PowerPointHandler.Add.Text.cs:404`
- `src/officecli/Handlers/Pptx/PowerPointHandler.Add.Text.cs:951`
- `src/officecli/Handlers/Pptx/PowerPointHandler.Helpers.FindReplace.cs:727`
- `src/officecli/Handlers/Pptx/PowerPointHandler.Helpers.RunFormat.cs:511`
Three further signals agree that points is the intended unit:
1. The validation message two lines above the conversion in `Add.Text.cs` reads
`Expected a number in points.`
2. `schemas/help/pptx/run.json` documents the same attribute as
`character spacing in points. Stored as 1/100 pt in OOXML (a:rPr/@spc)`,
with examples `spacing=2`, `charspacing=-1`, `spacing=0.5`.
3. The `ST_TextPoint` range guard rejects `spacing=9999` as outside
`[-4000pt, 4000pt]`. If the input were hundredths, 9999 would be 99.99pt and
perfectly legal — so the guard, too, reads the input as points.
Readback confirms it round-trips as points: `get` returns `spacing=200` for
`spc="20000"`, i.e. it divides by 100.
## Also wrong in the same entry
`"readback": "integer"` — `get` emits the **point** value, which may be fractional
(`run.json` documents `"point value as decimal string (e.g. '2', '-1', '0.5')"`).
## Suggested fix
`schemas/help/pptx/shape.json`, the `spacing` property (~line 319) — align it with
`run.json`:
```json
"description": "character spacing in points. Stored as 1/100 pt in OOXML (a:rPr/@spc); readback is the point value. Negative values tighten.",
"examples": ["--prop spacing=2", "--prop charspacing=-1", "--prop spacing=0.5"],
"readback": "point value as decimal string (e.g. '2', '-1', '0.5')"
```
Note the neighbouring `kern` entry in the same file *is* correctly documented as
1/100 pt (it takes raw OOXML units), which may be where the phrasing was copied from.
## Origin
Introduced in `75695405` (2026-04-27, *fix(pptx): route shape-level spc/lang/kern to
first-run rPr*) and carried forward unchanged by `9c78827d` (2026-07-23), which
rewrote the surrounding property block. No test asserts the string — `git grep` finds
it in exactly one file — so the correction should not require test changes.
## Impact
The error is silently two orders of magnitude, and nothing downstream catches it:
`view issues` reports `Found 0 issue(s)` on the resulting deck, because 200pt
tracking is valid OOXML — just unusable.
This is the shape-add help, so it is what an LLM-driven caller reads before authoring a
slide; a caller that trusts the stated unit produces a broken deck and no error.
An optional second guard worth considering: warn when character spacing exceeds
roughly the run's font size, which no legitimate layout requires.
Contributor guide
Research direction
Open schemas/help/pptx/shape.json around the spacing property and compare it with the corresponding entry in schemas/help/pptx/run.json. Confirm the documented unit, examples, and readback type against the issue's reproduction and source references, then verify the help output reflects the corrected wording; the issue says no test changes are needed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100