Skip to content

fix(docx): name the face an editor will not draw in a two-typeface family - #1067

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

DemchaAV merged 2 commits into
developfrom
fix/docx-mixed-typeface-family

Conversation

@DemchaAV

@DemchaAV DemchaAV commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

Why

A font family's slots are filled one file at a time, so a caller can build one family out of two
typefaces — classpath(name, "…/Lato-Regular.ttf").boldResource("…/IBMPlexMono-Bold.ttf"). The
DOCX export writes one w:font with both children, and the PDF backend draws each paragraph in the
program its slot holds: measured on the engine's own render, the bold paragraph of such a document
ends at 398.00pt in IBMPlexMono-Bold.

An editor does not. 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:

regular paragraph bold paragraph
the engine's own PDF Lato, 389.53pt IBM Plex Mono Bold, 398.00pt
Word, from the DOCX Lato, 392.94pt Lato, 393.42pt
LibreOffice, from the DOCX Lato-Regular, 389.31pt Lato-Regular, 389.31pt

Both editors draw the bold paragraph from the regular program — to the hundredth of a point where
the same document ships no bold program at all, while this one sits in the package at 137,784
bytes. Where the line is the face's own, the paragraph keeps the one its own face measured (364
twips against the regular paragraph's 336), so it is drawn 1.4pt shorter than the line reserved for
it, and its line ends 13.11pt short of where Word itself draws that program and 8.79pt short of
where LibreOffice does — each editor against its own rendering of the same program under a name of
its own, which is the gap the family costs rather than a difference between renderers. The export
said nothing: there is no refusal here to report — both children were written, exactly as asked.

It is not a limit of the format. Declared under a name of its own, the same program is drawn by
both editors — Word 406.53pt, LibreOffice IBMPlexMono-Bold 398.10pt, against the page's own
398.00pt — with the run's w:b kept or dropped. Carrying a mixed family that way would change the
bytes of every such document and the Word name a bold run carries, and was decided against; so what
the export can do without writing different bytes is say so.

What changed

  • DocxFontTable.nameTheFacesAnEditorWillNotDraw: for a family that ships a regular face, every
    other face whose program is of a different typeface is named in the report — embedded font,
    APPROXIMATED, with the typeface each of the two programs states and what a reader sees instead.
    APPROXIMATED rather than DROPPED because nothing was refused: both faces are written and the
    family travels whole. Said only where the family ships a regular face and both programs name
    their typeface — that is what was measured, and a program whose name cannot be read is one this
    cannot compare, so silence there is a missing warning rather than a false one. Said for every
    other slot the family ships and every pair of typefaces it holds, on the strength of the one slot
    and the one pair measured: what the editors read the sameness off was not measured, so neither
    the slot nor the two names can be the thing that decides what is said. The note says as much.
  • Whether two programs are of one typeface is read off the programs, as the format means it: the
    typographic family (name id 16) where a face states one, the family (id 1) otherwise — both
    from the Windows en-US record and only that one, so that two faces are never compared across two
    namings of one typeface, which taking whichever id 16 a file states first, or falling back to
    NamingTable.getFontFamily() and its search of the Unicode and Macintosh platforms, would both
    do. Id 1 alone would be wrong on a face this engine bundles and on a preset it ships:
    AsapCondensed-Italic states Asap Condensed Condensed Regular there where its three siblings
    state Asap Condensed, and it is the one face of the 130 bundled that states an id 16; the
    OrangeOps preset pairs Oswald-Regular, which states Oswald, with Oswald-SemiBold, which
    states Oswald SemiBold as its family and Oswald as its typographic one. Read as the format
    means it, all 188 pairs of faces inside the 35 bundled families match exactly and so does that
    pair, so no family a document here is set in draws this note — and the corpus, which exports that
    preset, measures it rather than arguing it. The comparison is String.equalsIgnoreCase, which
    folds the same way wherever the export runs, unlike toLowerCase() and its default locale.
  • The limit is recorded in the backend capability details, its note in the report's own table, and
    in the DOCX recipe beside the other rules on what travels.
  • One pre-existing case changed its fixture rather than its subject:
    aFamilyReachedByBothItsFamilyNameAndAFaceNameOfItWritesOneElement needed two files it could
    tell apart and had used Lato and IBM Plex Mono, which is itself a family of two typefaces and now
    draws the note. It uses Poppins regular and bold — two files of one typeface — and still pins
    what it was written for.

Verification

./mvnw -B -ntp clean test -pl :graph-compose-render-docx -am — 2779 tests, one skipped, and
./mvnw -B -ntp test -f qa/pom.xml — 1926 tests, one skipped, the second of those holding the
documentation guards. DocxFontTableTest holds 29, four of them new: the note read off the artefact and the
report, a family of one typeface drawing no note, a family that ships two faces of two typefaces
and no regular one drawing none either, and the bundled Asap family, which a reading of the family
record alone would tell — falsely — that its italic face is of another typeface. Each reads the two
programs' stated typefaces against the names the files actually hold rather than taking them from
the note.

Five sabotages, one per rule, each run selecting exactly the one case that rule's fixture belongs
to, each required to turn it red and each reporting tests=1 failures=1: the note never said; the
typeface read off the family record alone, which the bundled Asap family catches; any two different
programs drawing the note rather than two typefaces; DROPPED in place of APPROXIMATED; and a
family with no regular face being named all the same. The last of those first passed green, which
said the case it belongs to was reaching the guard against having nothing to compare rather than
the one it claimed — its fixture now ships two faces of two typefaces and no regular one. 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. That is the
check that this changes only what the export says — the note never reaches a document's bytes, and
no corpus document pairs two typefaces in one family.

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.

…mily

A font family's slots are filled one file at a time, so a caller can build one
family out of two typefaces — `classpath(n, Lato-Regular).boldResource(
IBMPlexMono-Bold)`. The export writes one `w:font` with both children, and the
PDF backend draws each paragraph in the program its slot holds.

An editor draws the family from the program in `embedRegular` and leaves the
other unread. Measured with a bold run in Word 16.0.20527 and LibreOffice 24.2,
each document converted in a process of its own, a 45-character line at 14pt:
both paragraphs came from the Lato program, to the hundredth of a point where
the same document ships no bold program at all, while that program sat in the
package at 137,784 bytes. Where the line is the face's own, the bold paragraph
keeps the one its own face measured, so it is drawn 1.4pt shorter than the line
reserved for it, and its line ends 13.11pt short of where Word itself draws that
program and 8.79pt short of where LibreOffice does. Nothing in the export said
so: there was no refusal to report, both children having been written as asked.

Such a face is now named — `embedded font`, `APPROXIMATED`, with the typeface
each of the two programs states and what a reader sees instead. `APPROXIMATED`
and not `DROPPED` because nothing was refused: both faces travel. Said only
where the family ships a regular face and both programs name their typeface,
which is what was measured; said for every other slot the family ships, though
only the bold one was measured, since the slot a run reaches is not what the
editors were seen to go by.

Whether two programs are of one typeface is read off the programs, as the format
means it: the typographic family (`name` id 16) where a face states one, the
family (id 1) otherwise, both from the Windows en-US record so that two faces
are never compared across two namings of one typeface. Id 1 alone would be wrong
on a bundled face — `AsapCondensed-Italic` states `Asap Condensed Condensed
Regular` there where its three siblings state `Asap Condensed`, and it is the one
face of the 130 bundled that states an id 16. Read this way, all 188 pairs of
faces inside the 35 bundled families match, so no bundled family draws the note.
The comparison is `String.equalsIgnoreCase`, which folds the same way wherever
the export runs.

No document's bytes change. It is not a limit of the format either: the same
program declared under a name of its own is drawn by both editors, which is the
alternative not taken — it would change the bytes of every such document and the
Word name a bold run carries. The capability matrix, its details, the report's
note table and the DOCX recipe carry the measurement and what it leaves.

`aFamilyReachedByBothItsFamilyNameAndAFaceNameOfItWritesOneElement` needed two
files it could tell apart and had used Lato with IBM Plex Mono, which is itself a
family of two typefaces and draws the note; it uses Poppins regular and bold, two
files of one typeface, and pins what it was written for unchanged.
…sured

`typefaceOf` fell back to `NamingTable.getFontFamily()` where a face states no
Windows en-US family record. That method searches the Unicode and Macintosh
platforms as well, so a face read through it was compared against a sibling read
from the Windows record — a name read under terms the other's was not, where a
difference says nothing. A one-typeface family whose bold face carries only
Macintosh name records would draw the note for that reason alone. The fallback
is gone: both ids are read from the Windows en-US record and only that one, and
a face that states neither is one this cannot compare, which it answers with
null as before.

The note and the javadoc said an editor draws a name from the program in
`embedRegular` wherever the two programs are of different typefaces. One pair of
typefaces was measured, Lato beside IBM Plex Mono, and what the editors read the
sameness off was not measured at all — the capability details said so three
sentences from the paragraph the note points at. Both now name the measured pair
as what they rest on and say the criterion is unmeasured, which is also why the
note is said of every pair and every slot rather than of the ones measured.

The reading protects a preset this repository ships, not only the bundled faces:
`OrangeOps` pairs `Oswald-Regular`, which states `Oswald` as its family, with
`Oswald-SemiBold`, which states `Oswald SemiBold` there and `Oswald` as its
typographic family. Read by the family record alone it would be told its own
bold face is of another typeface. The corpus exports that preset, so its 105
documents keeping the same 1718 notes measures the reading rather than arguing
it; the javadoc, the capability details, the recipe and the CHANGELOG now cite
it beside the bundled count.

Two sentences in the capability details were wrong about what they named: the
table row said an editor sets "that slot's" runs in the regular face, where the
runs meant are the ones reaching the face the row is about; and the measurement
of a program drawn under a name of its own was attached to the two-name shape,
which is the thing not measured.
@DemchaAV
DemchaAV marked this pull request as ready for review November 15, 2026 00:09
@DemchaAV
DemchaAV merged commit 173e2c2 into develop Nov 15, 2026
13 checks passed
@DemchaAV
DemchaAV deleted the fix/docx-mixed-typeface-family branch November 15, 2026 00:20
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