Commit 84f3748
authored
docs(changelog): rewrite the v2.1.0 section as release notes (#444)
* docs(changelog): rewrite the v2.1.0 section as release notes
The section read as the journal it was written as: 44 bullets in commit order,
17 of them consecutive PPTX implementation slices, several superseded by later
ones. It ships verbatim into the GitHub Release, so a reader met the backend's
history rather than what it does.
Restructure it around what a reader needs — Highlights, Public API, PPTX
backend, Fixed, Templates, Documentation and examples, Build and compatibility,
and a Known limitations section the notes previously had no equivalent of.
329 lines become 216 without dropping a shipped fact.
Three statements were wrong rather than merely verbose, and are corrected rather
than reworded:
- Determinism was advertised as "renders byte-identical decks across runs" with
no caveat. It is opt-in and off by default: the SPI provider that
buildPptx(Path) resolves never enables it, so the convenience methods stream
with live timestamps. The notes now say so, and Known limitations repeats it.
- "First capability slice: rectangle shapes, ellipses, and lines" described an
intermediate state that the following bullets already superseded with text,
tables, images, paths and transforms.
- A Tests bullet claimed a default-output-file failure mode whose test was
deleted with the no-arg buildPptx() overload.
Clipping was also split across a slice and its later correction; it is now one
statement about the shipped behaviour.
Every mechanism claim was verified against the code rather than carried over:
the decoration offsets (0.10 / 0.28 / 0.05 em) against PdfTextDecorations, the
once-per-family substitution warning against PptxRenderEnvironment, the
duplicate-handler rejection against Builder.addHandler, the 38/24/10/4
capability counts against the matrix, the record component counts against the
v2.0.0 tag, and every API name against source. The twin-output shape count (69
native, one picture) and the PDF/PPTX geometry match were measured from the
emitted artifacts.
Verified: full reactor clean verify green (1522 tests, 0 failures); the release
workflow's own awk extraction yields the 216-line section; both linked documents
resolve on disk.
* docs(changelog): stop overstating what a partial PPTX capability costs
The capability summary said 10 of the 38 tracked capabilities "render natively
with an approximated styling detail". Reading all ten rows rather than the count
shows only about half are that. The others lose something: inline SVG falls back
to a transparent PNG for arbitrary clips and off-viewBox art, bookmarks after the
first on a page are dropped because PPTX has no outline tree, and metadata's
producer value has no OPC field at all.
A reader with a bookmark-heavy document would have taken that sentence to mean
the only cost was styling, shipped a deck, and silently lost the navigation.
Split the sentence so the partial group is not characterised as one thing, and
add the three content-losing cases to Known limitations, which previously listed
only the cosmetic approximations.1 parent 9eedf39 commit 84f3748
1 file changed
Lines changed: 212 additions & 314 deletions
0 commit comments