Repository navigation
docs(docx): scope the shared-font-name rule to differing typefaces - #1066
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:fonthas one child for it and an editor has one program todraw 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:fontelement, which is how the exportwould have written it.
A
w:fontholds one child per face, so there is a second shape the format allows: the given-upfamily'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,
Embeddedisbuilt in one place out of one family's
fontSourceSet(), andtoXmlwrites one element perEmbedded— 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:fontwithw:embedRegularfrom one andw:embedBoldfrom the other, and the twoparagraphs' runs carry one
w:rFontsname and differ only inw: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:
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:embedRegularand IBM Plex Mono bold inw:embedBold, both paragraphs weredrawn 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
nametable, or something else — wasnot measured. Which program sat in
w:embedRegularwas 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/mainin this change is inside a javadoccomment.
DocxFontTable's class javadoc, thejavadoc of
refuseForASharedName, the backend capability details, the DOCX recipe and theCHANGELOG — 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.anElementDeclaresOnlyTheFacesOfTheFamilyItIsNamedForpins what the exportwrites, 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 documentationguards, the DOCX capability-matrix guard among them.
DocxFontTableTestholds 25, one of themnew, 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:
holder's declared slots;
refusal's own note, which is the assertion that stops the case passing on a document where the
collision never happened;
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 thestart of the run.
No corpus export: the only
src/mainedit is javadoc, so no export writes a different byte, whichthe 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 renderbackends, templates, testing, qa and coverage, the four knowledge-pack checks, core javadoc, then
the install and the examples suite (93 tests).