Skip to content

docs(docx): scope the shared-font-name rule to differing typefaces - #1066

Merged
DemchaAV merged 2 commits into
developfrom
fix/docx-font-table-one-family-per-name
Nov 14, 2026
Merged

DemchaAV merged 2 commits into
developfrom
fix/docx-font-table-one-family-per-name

Conversation

@DemchaAV

@DemchaAV DemchaAV commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

Why

A DOCX export ships one face set per declared font-table name: a family asking to travel under a
name another one already ships under is given up whole, a face bound for a slot the holder left
empty included. That face is the only one the refusal could cost anything — where the two families
are set in text in the same slot, a w:font has one child for it and an editor has one program to
draw from whatever the two are. The ground for giving up the free slot too was that a second
program under the name is not read — measured as a second w:font element, which is how the export
would have written it.

A w:font holds one child per face, so there is a second shape the format allows: the given-up
family's face as another child of the holder's element, which is the shape a per-slot rule like
the PPTX backend's would need. That shape had never been measured. The export cannot reach it from
two registrations — the colliding family is given up before any of its faces is read, Embedded is
built in one place out of one family's fontSourceSet(), and toXml writes one element per
Embedded — but it is writable, and the document an editor reads does not say where it came from:
one registration whose regular and bold slots hold programs of different typefaces writes exactly
one w:font with w:embedRegular from one and w:embedBold from the other, and the two
paragraphs' runs carry one w:rFonts name and differ only in w:b.

Measured in Word 16.0.20527 and LibreOffice 24.2, each document converted in a process of its own,
a 45-character line at 14pt, as the right edge of the drawn line. LibreOffice names the face in
its PDF, so its column is read off the output rather than inferred from a width:

under one name Word: regular / bold LibreOffice: regular / bold
one element: Lato regular, Plex Mono bold 392.94 / 393.42 Lato-Regular / Lato-Regular
the same two parts as two elements 392.94 / 393.42 Lato-Regular / Lato-Regular
the same element, children reversed 392.94 / 393.42 Lato-Regular / Lato-Regular
one element: Lato regular, Lato bold 392.94 / 399.12 Lato-Regular / Lato-Bold
the same two parts as two elements 392.94 / 399.12 Lato-Regular / Lato-Bold

The same text alone under a name of its own is drawn at 406.53 from the Plex Mono Bold program, at
399.12 from Lato Bold, at 393.42 by a bold run over the Lato program and at 392.94 from Lato
regular; LibreOffice draws those at 398.10, 395.41, 389.31 and 389.31.

For a free slot, the shape is not what either editor goes by; the pair of typefaces is. With
Lato regular in w:embedRegular and IBM Plex Mono bold in w:embedBold, both paragraphs were
drawn from the Lato program and the Plex Mono one was used by neither — as two elements and as two
children of one element alike, and whichever of the two children was written first. With Lato
regular and Lato bold, both programs were read in either shape, each paragraph drawn from its own.

That narrows the recorded ground rather than removing it. Giving the family up whole, rather than
only the slot it clashes on, costs nothing more except in one case: the given-up face is bound for
a slot the holder left empty and is a face of the same typeface as the holder's program — a
family declaring a bundled family's Word name and built from that same typeface's files. There it
gives up a program both editors would have read. Whether to keep the refusal whole there is a
behaviour question this PR does not answer.

What the editors read the sameness off — the programs' own name table, or something else — was
not measured. Which program sat in w:embedRegular was never swapped either, so for two elements
"survived because its element came first" and "survived because it is the regular face" stay
unseparated; within one element the two children's order was swapped and did not decide.

What changed

Nothing in what an export writes. Every line of src/main in this change is inside a javadoc
comment.

  • The measurement is recorded where the rule is stated — DocxFontTable's class javadoc, the
    javadoc of refuseForASharedName, the backend capability details, the DOCX recipe and the
    CHANGELOG — and each of those now scopes "an editor reads only one of them" to a pair of
    different typefaces, says what the same-typeface pair did, and says that the refusal gives up a
    readable program there. The two that gave the shape as the reason — the CHANGELOG's bullet on a
    free slot and the javadoc of refuseForASharedName — no longer do.
  • DocxFontTableTest.anElementDeclaresOnlyTheFacesOfTheFamilyItIsNamedFor pins what the export
    writes, now that the editors' answer no longer rests on it: it reads the table's elements, ties
    each child to the part the child's own relationship names, and asserts that each element declares
    the faces of its own family and no others, that the holder declares only the slot it filled, and
    that neither file of the family given up is in any font part, whose count is pinned too. A second element stands
    beside the contended name, and the family under its own name is built from a third typeface, so a
    face bound into the wrong element fails as well as an extra child in the right one. The given-up
    family is set in text in both of its slots, so that neither of its files could reach a part by
    any route and both halves of the closing check can fail. The case is
    keyed on the refusal having happened, because without that it passes on a document where the two
    families never contended for the name.

Verification

./mvnw -B -ntp clean test -pl :graph-compose-render-docx -am — 2775 tests, one skipped, and
./mvnw -B -ntp test -f qa/pom.xml — 1926 tests, one skipped, the second of those holding the documentation
guards, the DOCX capability-matrix guard among them. DocxFontTableTest holds 25, one of them
new, reading the artefact: which elements the table declares, which slots each holds, and which
font each child's own part carries past its scrambled 32-byte header.

Three sabotages, one per rule the new case pins, each run selecting exactly that one test and each
required to turn it red:

  • writing the given-up family's free slot as another child of the holder's element — red on the
    holder's declared slots;
  • making the walk over the written families find no holder, so nothing is ever refused — red on the
    refusal's own note, which is the assertion that stops the case passing on a document where the
    collision never happened;
  • pointing every child at the first face's part — red on the own-name family's first program, which
    is the assertion the third typeface makes discriminating.

Each reported tests=1 failures=1, and the file came back byte-identical to the copy taken at the
start of the run.

No corpus export: the only src/main edit is javadoc, so no export writes a different byte, which
the diff shows line by line — every changed line there is a javadoc line.

The full reactor gate ran once, 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).

A DOCX export gives up a whole family that asks to travel under a name another
one already ships under, on the ground that a second program under the name is
not read. That was measured as a second `w:font` element. A `w:font` holds one
child per face, so the format allows a second shape — the given-up family's
face as another child of the holder's element, which a per-slot rule would need
— and that shape had never been measured.

Two registrations cannot reach it: the colliding family is given up before any
of its faces is read, `Embedded` is built in one place out of one family's
`fontSourceSet()`, and `toXml` writes one element per `Embedded`. One
registration whose regular and bold slots hold programs of different typefaces
writes it, and an editor cannot tell the two apart — the runs carry one
`w:rFonts` name and differ only in `w:b`.

Measured in Word 16.0.20527 and LibreOffice 24.2, a 45-character line at 14pt
with a regular and a bold paragraph: the shape is not what either editor goes by,
the pair of typefaces is. With Lato regular in `w:embedRegular` and IBM Plex Mono
bold in `w:embedBold`, both paragraphs were drawn from the Lato program and the
Plex Mono one was used by neither — as two elements and as two children of one
element alike, and whichever of the two children was written first. With Lato
regular and Lato bold, both programs were read in either shape, each paragraph
drawn from its own. So giving up a whole family costs nothing where the two
families' programs are faces of different typefaces, and gives up a program both
editors would have read where the two families are built from one typeface's
files. What the editors read that off was not measured; only whether the two
programs are faces of one typeface was varied, and in each different-typeface
arrangement the program that survived was also the one in `w:embedRegular`, so
which of those two facts kept it was not separated.

The class javadoc, the refusal's javadoc, the capability details, the DOCX
recipe and the CHANGELOG now scope "an editor reads only one of them" to a pair
of different typefaces and say what the refusal costs for a pair of one.

`anElementDeclaresOnlyTheFacesOfTheFamilyItIsNamedFor` pins what the export
writes, now that the editors' answer does not rest on it: it reads the table's
elements, ties each child to the part the child's own relationship names, and
asserts that each element declares the faces of its own family and no others,
that the holder declares only the slot it filled, and that neither file of the
family given up is in any part of the package. A second element stands beside
the contended name and the family under its own name is built from a third
typeface, so a face bound into the wrong element fails as well as an extra child
in the right one. The given-up family is set in text in both of its slots, so
that neither of its files could reach a part by any route. The case is keyed on
the refusal having happened, so it cannot pass on a document where the two
families never contended.
A `w:font` holds one child per slot, so where two families declaring one name
are set in text in the same slot an editor has one program to draw from
whatever the two are. A face bound for a slot the holder left empty is the only
one giving up the whole family can cost anything, and only there does the pair
of typefaces decide: Lato regular beside Lato bold had both programs read, Lato
regular beside IBM Plex Mono bold had the second used by neither.

So the cost of the refusal needs both conditions, and the class javadoc, the
refusal's javadoc, the capability details, the DOCX recipe and the CHANGELOG
now give both: the given-up face is bound for a slot the holder left empty and
is a face of the same typeface as the holder's program. The CHANGELOG entry's
heading claims nothing about what an editor reads, since what it states is what
the export no longer writes.

Two further things those five now say. The document with two children of one
element is not one two registrations can write, the refusal coming first, so it
was written by one registration whose two slots hold programs of two typefaces
— which an editor cannot tell from the other, the runs carrying one name and
differing only in `w:b`. And the order of the two children was swapped within
one element and did not decide, while which program sat in `w:embedRegular` was
never swapped, so for two elements "survived because its element came first"
and "survived because it is the regular face" stay unseparated.

`fontElements` asserts it read as many elements as the part declares, since the
pattern it walks matches an element with children and `families` is built on
it; the new case pins the number of font parts, so one no element points at
would be seen; and `assertCarries` reports a length mismatch as itself.
@DemchaAV
DemchaAV marked this pull request as ready for review November 14, 2026 17:40
@DemchaAV
DemchaAV merged commit 0ee8d28 into develop Nov 14, 2026
13 checks passed
@DemchaAV
DemchaAV deleted the fix/docx-font-table-one-family-per-name branch November 14, 2026 21:11
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