Skip to content

docs(fonts): record what a PPTX font container names a face by - #1068

Merged
DemchaAV merged 2 commits into
developfrom
fix/docx-typeface-name-readers
Nov 15, 2026
Merged

DemchaAV merged 2 commits into
developfrom
fix/docx-typeface-name-readers

Conversation

@DemchaAV

@DemchaAV DemchaAV commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Why

A font file states its own names. The family lives in name id 1, which the four-style model
groups by; a face that model cannot hold — one of six weights, or a width — states its real family
in id 16, and then id 1 carries whatever made the pair fit four styles. Two places in this
repository meet a face like that, and neither was written down.

One bundled face states an id 1 that reads oddly: AsapCondensed-Italic gives
Asap Condensed Condensed Regular where its three siblings give Asap Condensed. Everything else
it states is right — full name Asap Condensed Italic, PostScript name AsapCondensed-Italic,
id 16 Asap Condensed — which is why a reader following the format arrives at the family anyway.
The file is the one Google Fonts publishes, byte for byte (git hash-object matches the blob their
main serves), and no corrected version is published upstream, so it ships as it is rather than as
a rebuilt binary of ours. A system that reads id 1 alone lists that string beside Asap Condensed:
fontconfig, which LibreOffice builds its font list from on Linux, lists both and puts
Asap Condensed first.

Nothing GraphCompose writes into a PDF or a DOCX comes from that record — a document names the
family its caller registered, and a PDF names each face by its PostScript name. One place does read
it: the PPTX font container, whose family and style fields come from id 1 and id 2 because the
header read it is built from keeps ids 1, 2 and 6 only, so a typographic name is discarded before
it can be asked for. Nothing in the engine compares those fields with the typeface a deck declares,
and no refusal is keyed on them — but the refusals added around that container recently do key on
container fields, so the next author needs to know which of them mean anything.

Reading the typographic names there instead was tried on both faces here that state them: it
changes both fields and changes nothing PowerPoint 16 draws, to the hundredth of a point. No other
viewer was measured. Two symptoms were measured along the way in decks whose faces are of this
kind, and the container's names are not their cause; they are being looked for separately.

What changed

Prose, and one case that pins what the prose says. Every line this adds to src/main is inside a
javadoc comment, which the diff shows line by line; no behaviour changes and no exported byte
moves.

  • docs/font-coverage.md gains a section on what a bundled face calls itself: the two family
    names a file can state, the one bundled face whose id 1 reads oddly, why it ships unchanged, and
    what a reader of id 1 alone will show.
  • The PPTX font-portability entry in the backend capability details records that a container names
    its face by id 1 and id 2 rather than the typographic names, why the header read cannot offer
    them, that nothing compares them with the declared typeface, and that what a viewer makes of a
    container naming one family under a declaration of another is not a thing this backend has been
    shown to decide.
  • PptxEmbeddedFont.metadata() says the same where it is written, names the bundled face whose
    id 1 is built wrong as the example, and says plainly not to key a guard on what those two fields
    say — the one refusal in that class which touches them reads how long they are, since the
    presentation reads the header itself, and the slot collisions a presentation can suffer are
    keyed on the weight and italic flags instead.
  • PptxEmbeddedFontTest gains a case that wraps that face and reads the container back: its
    family field is the name the face states for the four styles, its style field Italic, and its
    full name the two joined. That is the sentence the javadoc makes, and without it a later author
    could prefer the typographic names — changing the bytes of every deck carrying such a face — with
    nothing going red.

Verification

./mvnw -B -ntp clean test -pl :graph-compose-render-pptx -am — 184 tests, none skipped, and the
documentation guards in qa — 1926 tests, one skipped — as part of the gate below.
PptxEmbeddedFontTest holds 3, one of them new, reading the container it just wrote rather than
the names it was built from.

One sabotage, on the rule that case pins: preferring the typographic family over the one the face
states for four styles turned that case red and nothing else was selected (tests=1 failures=1),
and the file came back byte-identical to the copy taken at the start of the run.

The 105-document corpus, exported from this head and from develop: unchanged — 105 documents
byte-identical, with the same 1718 report notes, none added and none removed. This change cannot
move them, every src/main line of it being a comment, which is why the export is reported rather
than assumed.

The full reactor gate ran on this branch's final head: GATE PASS — core, the three render
backends, templates, testing, qa and coverage, the four knowledge-pack checks, core javadoc, then
the install and the examples suite (93 tests, CommittedAssetDriftTest among them).

A font file states its family in `name` id 1, and a face the four-style model
cannot hold states its real family in id 16, leaving id 1 to carry whatever made
the pair fit. Two things in this repository meet such a face and neither was
written down.

One bundled face states an id 1 that simply reads wrong: `AsapCondensed-Italic`
gives `Asap Condensed Condensed Regular` — a doubled width word and a `Regular`
on an italic — where its full name, its PostScript name and its id 16 all give
the family correctly. The file is the one Google Fonts publishes, byte for
byte, with no corrected version published upstream, so it ships as it is rather
than as a rebuilt binary; a system reading id 1 alone lists that string beside
`Asap Condensed`. The font-coverage page now says where that record does and does not travel: a
PDF names each face by its PostScript name, a DOCX names the family its caller
registered while reading these records to tell a family's typefaces apart, and a
PPTX carries id 1 in its font container.

The PPTX font container does read it: its family and style fields come from id 1
and id 2, because the header read the container is built from keeps ids 1, 2 and
6 only and discards a typographic name before it can be asked for. Nothing in
the engine compares those fields with the typeface a deck declares, and no
refusal is keyed on what they say — the one in that class which touches them
reads how long they are. Preferring the typographic names was tried on both
faces here that state them, and PowerPoint 16 drew those decks the same to the
hundredth of a point either way, so the capability details and the javadoc of
the method writing them now say not to key a guard on them.

Every line added to `src/main` is inside a comment and no behaviour changes. One
case pins what the javadoc says: it wraps that face and reads the container back,
so preferring the typographic names — which would change the bytes of every deck
carrying such a face — cannot pass unnoticed.
…llbacks

The javadoc said the typographic names were tried on "both bundled faces that
state them". The bundle holds one such face, `AsapCondensed-Italic`; the other
is the `Oswald-SemiBold` a preset pairs, which lives in the example and test
resources. It now names both and says which is which, so it no longer counts
differently from the capability details beside it.

Three more sentences there were wider than the code. The family and the style
fall back independently — the PostScript name for one, `Regular` for the other —
where the earlier wording made one condition of both. "Nothing but a test reads
them back" is not true of the header: the presentation reads it, which is the
whole reason this class measures its length, so the sentence now says nothing in
the engine reads what the fields *say*. And the capability details are the whole
account of the arrangement, not of a cost, nothing measurable having been shown
to be one.

On the font-coverage page, a PDF names a face by its PostScript name behind the
six-letter tag every subset carries, which is what a reader comparing the page
against their own file will see. The recipe index now summarises the page by its
fourth topic as the documentation index already did.

The container case drops an assertion that the container it read was the one
written: its sibling case above already pins that, and this one is about the
names.
@DemchaAV
DemchaAV marked this pull request as ready for review November 15, 2026 09:22
@DemchaAV
DemchaAV merged commit 1cc7684 into develop Nov 15, 2026
13 checks passed
@DemchaAV
DemchaAV deleted the fix/docx-typeface-name-readers branch November 15, 2026 09:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant