diff --git a/CHANGELOG.md b/CHANGELOG.md index 005fabd5c..7921c505f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,45 @@ follow semantic versioning; release dates are ISO 8601. ### Fixed +- **A PPTX export no longer stays silent about a face it carries that a presentation does not + draw as laid out.** + - A presentation matches an embedded face to the family a deck declares by the family the + *program* states for itself — `name` id 1 — and not by the names its container carries. Where + the two differ, the face travels and any runs laid out in it are not reached that way. + - Measured in PowerPoint 16 on a 45-character line at 20pt, one deck per run, with neither + family installed on the machine: a deck declaring `Asap Condensed` and carrying the bundled + `AsapCondensed-Italic`, whose own family record reads `Asap Condensed Condensed Regular`, had + that paragraph drawn in **Arial Italic** at 566.51pt where PowerPoint draws that same program + at 443.65pt once the record names the declared family — the engine's own render of the two + faces is 443.14pt and 443.96pt, which is what the page laid out. Its regular paragraph, whose + record does name the declared family, came out at 442.92pt. Rewriting that one record to the + declared name, and nothing else, was the only change that drew the program; rewriting it to the string it already held changed + nothing, so neither the rewriting nor the stale checksums it leaves were what the viewer went + by. Declaring the family as the italic states it had that program drawn for both paragraphs + and left the regular face unused, so for a family whose faces disagree in that record no one + declared name serves them all. + - What that costs differs, and both halves were measured: that face was not drawn at all, while + `Oswald-SemiBold`, which the `OrangeOps` preset pairs under `Oswald` and whose own record + reads `Oswald SemiBold`, was drawn and then weighted again by the viewer — 480.10pt where the + program itself draws 469.70pt. So the log line names both families and leaves the outcome to + the reader rather than promising the one measured first. + - Such a face is now named in the log (`render.pptx.font.name.mismatch`), with the family it states and + the one the deck declares. It is not refused: the program travels as the caller asked and no + deck's bytes change, which is the whole of what the export can add — the face is still not + reached as laid out, and only PowerPoint 16 was measured. The line says nothing about whether + the family travels either; a later face of it can still collide or fail to be read, and those + have their own lines. + - The comparison is on id 1 deliberately, not on the typographic family (id 16) the DOCX backend + prefers for telling typefaces apart: that is a different question, and reading id 16 here + would answer with the declared name for the very face a presentation refuses — and would + silence the `Oswald` pair that id 16 rescues there. + - The condition is not confined to a mis-built file. A declared typeface is `wordFamily()`, + which defaults to the name a family was registered under, so any caller registering a face + under a name of their own meets it; the font-coverage page now says to declare the name the + files state. Of the bundled families' face sources exactly one differs today, and a sweep in + `PptxFontNameMismatchTest` keeps that count honest across a font bump. The capability matrix + cell and its details entry move from ✅ to ⚠️ together, the mark the legend reserves for a + backend whose details name a deviation. - **A DOCX export no longer stays silent about a face it ships that neither editor measured draws.** - A font family's slots are filled one file at a time, so a caller can put a program of one typeface in the regular slot and a program of another in the bold slot — diff --git a/docs/architecture/backend-capability-details.md b/docs/architecture/backend-capability-details.md index a14e53cdd..88ed1878d 100644 --- a/docs/architecture/backend-capability-details.md +++ b/docs/architecture/backend-capability-details.md @@ -394,7 +394,7 @@ Font portability — does a file carry the family it drew with **PDF.** ✅ every embedded family is subset into the file (`PdfFontLoader`), so a reader needs nothing installed -**PPTX.** ✅ `PptxRenderEnvironment.embedBundledFontsUsed` + `PptxEmbeddedFont` — a registered family and a bundled one the deck drew with are both carried. Whole-font, no subsetting — the **bundled** path narrows that to the faces a run actually drew, so a five-script deck grows from 27 KB to about 1.4 MB rather than carrying weights no slide contains; a **registered** family is still taken at family granularity, all four faces. `PptxFixedLayoutBackend.Builder.embedBundledFonts(false)` declines the bundled half (a registered family travels regardless), and a declined or failed family is warned about by name and carried whole or not at all — a family one of whose faces cannot be read, or whose licence bits forbid embedding, leaves nothing of itself in the deck rather than half of it. A deck declares an embedded face under one of four style elements (`p:regular`, `p:bold`, `p:italic`, `p:boldItalic`) and holds one face in each, and which element a face lands under is not the slot the family registered it in: `XSLFFontInfo.addFacet` reads the weight and the italic flag out of the container and picks from those, so a face a caller put in the bold slot whose own `usWeightClass` is 400 or less reads back as the regular one. Two faces of a family that read back as the same element cannot both travel — a second face seated in a taken element overwrites the part the first wrote and keeps the first's declaration — so such a family is refused as an unreadable one is, with both faces and the element named. Before that it was silent and worse than a loss: the deck came out with one program that was the later face's bytes under the earlier face's declaration, PowerPoint 16.0 reported the family as embedded, and every run of it — the regular ones included — was drawn from the one program that survived, measured in an exported PDF whose subset carried the `glyf`, `hmtx`, `cmap` and `loca` tables of the face from the bold slot byte for byte. Refused rather than reseated, because the element is the presentation's answer and not the backend's to pick: there is no fifth one, and two faces that collide agree on the only two fields it is read from. The sources dedupe by description before the elements are compared, and the builder fills an unset slot from a source already given, so neither a family of one file nor a partially named one can collide with itself, and none of the bundled families collides (each one's distinct faces read back onto distinct elements; four of them ship fewer than four faces and so reach the dedupe rather than the comparison). The element's capacity belongs to the declared typeface rather than to a registration, and the same refusal answers for two definitions that share one: `XSLFFontInfo` looks an entry up by typeface ignoring case, so two definitions whose `wordFamily` matches that way write into one entry and one set of four elements. The family whose face arrives into an element another family already holds is refused whole, as a family with an unreadable face is — a face of it bound for a free element does not travel either — and the family holding the element keeps its program and its viewer metrics; in the form a caller reaches with one registration — their own family declared under a *bundled* family's viewer name, which the bundled pass does not skip because it skips only a matching `FontName` — that leaves the explicit registration carrying its own font, the bundled pass running after the last slide. The limit of that order is that a registered family is carried before anything is drawn, so one declared under a bundled family's name and never drawn in still takes the element and the bundled family's own text is drawn from that program, where before this guard the bundled face wrote over that part. The elements are claimed where the faces are handed to the presentation and not where they are read, because a registered family's viewer metrics are read in between and a family given up there has had nothing written for it: claiming at the read would let it hold an element it never filled and cost the next family declaring that name its own program. Before it, one entry declared `p:regular` held the later face's bytes with nothing logged, and PowerPoint 16.0 drew both families' text from it: an exported PDF had a single subset of 1,060 glyphs, the later face's glyph count, where the two declared under different names export subsets of 3,023 and 1,060. What refusing cannot fix, and what the log says instead of the ordinary "install the font": the refused family's text carries the shared name too, so a viewer draws it from the program that did travel — a run names a family and no more, so no deck holds two programs for one name and one element. Two definitions can also share a name without colliding, one holding `p:regular` and the other `p:bold`, and both travel; that gets `render.pptx.font.shared.family` once for the name, because the page measured each family with its own program while the deck has one name for both — "font family" and not "registered family" in that line, because a bundled family joins such a pair whenever the face it drew with lands in an element still free. The guard's boundary is what `FontName` counts as one family, which is case-insensitive: two registrations of one name are one family to it and the later program travels rather than being refused, because `FontLibrary` keeps the last factory registered under a name, so that later program is the one the page measured with and refusing it would leave the deck carrying a face no text was laid out in. A registered family is read by two parsers that do not accept the same files: the embedder parses table headers with fontbox, which skips a table whose directory entry runs past the end of the file, and the viewer metrics read the program whole through `java.awt.Font.createFont`, which rejects the font for such an entry. Both reads happen before the presentation is handed anything, so a font only one of them accepts — a truncated one — degrades the family instead of costing the deck. Carrying it without metrics is the alternative not taken: what seats such a family is then the PDF descriptor's ascent, which for 126 of the 130 bundled faces is the ascent the viewer uses and for the four Alegreya Sans faces is a full point out at 10pt text, and which of the two a refused font is cannot be established, since the reader that would say is the one that refused. A face's header is measured where the container is built, against the tighter of the two thousand-byte windows the presentation reads it through — each name on its own when it takes the face, refusing a longer one unchecked from inside the hand-over, and the whole header (96 bytes plus four names) when it reads the written part back. The metrics reader in front of it reads the family and full-name records but never the subfamily, so a long subfamily reached the writer and cost the deck: Lato-Regular rewritten with a 496-character subfamily makes a 1,002-byte full name. A header moves in fours, since the family is written twice, so 998 bytes is the largest any face can express and it is carried; the heaviest header among the 130 bundled faces is 250. The thousand is POI's default, which a host can lower with `IOUtils.setByteArrayMaxOverride`, so the check is a floor rather than a guarantee. A carried program's container names the face by the family and style the file states for the four-style model (`name` id 1 and id 2), not by the typographic names a face states when it falls outside that model (id 16 and id 17): the header read the container is built from keeps ids 1, 2 and 6 only, so a typographic name is discarded before it can be asked for. A face of six weights therefore names itself in the container by the name that made it one of four — and a face whose id 1 is built wrong carries that, as the bundled `AsapCondensed-Italic` does. Nothing in the engine compares those fields with the typeface the deck declares, and no refusal is keyed on what they say; the one refusal that 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 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; no other viewer was measured. A deck that carries a program declares it embedded and asks the reader to keep every character of it rather than only those its slides use, since nothing here subsets a face; a deck that carries none leaves embedding off, where the subset flag POI's blank template already sets decides nothing. Standard-14 names carry no binary and map to metric-compatible viewer replacements (Helvetica to Arial, and so on) rather than being embedded +**PPTX.** ⚠️ `PptxRenderEnvironment.embedBundledFontsUsed` + `PptxEmbeddedFont` — a registered family and a bundled one the deck drew with are both carried. Whole-font, no subsetting — the **bundled** path narrows that to the faces a run actually drew, so a five-script deck grows from 27 KB to about 1.4 MB rather than carrying weights no slide contains; a **registered** family is still taken at family granularity, all four faces. `PptxFixedLayoutBackend.Builder.embedBundledFonts(false)` declines the bundled half (a registered family travels regardless), and a declined or failed family is warned about by name and carried whole or not at all — a family one of whose faces cannot be read, or whose licence bits forbid embedding, leaves nothing of itself in the deck rather than half of it. A deck declares an embedded face under one of four style elements (`p:regular`, `p:bold`, `p:italic`, `p:boldItalic`) and holds one face in each, and which element a face lands under is not the slot the family registered it in: `XSLFFontInfo.addFacet` reads the weight and the italic flag out of the container and picks from those, so a face a caller put in the bold slot whose own `usWeightClass` is 400 or less reads back as the regular one. Two faces of a family that read back as the same element cannot both travel — a second face seated in a taken element overwrites the part the first wrote and keeps the first's declaration — so such a family is refused as an unreadable one is, with both faces and the element named. Before that it was silent and worse than a loss: the deck came out with one program that was the later face's bytes under the earlier face's declaration, PowerPoint 16.0 reported the family as embedded, and every run of it — the regular ones included — was drawn from the one program that survived, measured in an exported PDF whose subset carried the `glyf`, `hmtx`, `cmap` and `loca` tables of the face from the bold slot byte for byte. Refused rather than reseated, because the element is the presentation's answer and not the backend's to pick: there is no fifth one, and two faces that collide agree on the only two fields it is read from. The sources dedupe by description before the elements are compared, and the builder fills an unset slot from a source already given, so neither a family of one file nor a partially named one can collide with itself, and none of the bundled families collides (each one's distinct faces read back onto distinct elements; four of them ship fewer than four faces and so reach the dedupe rather than the comparison). The element's capacity belongs to the declared typeface rather than to a registration, and the same refusal answers for two definitions that share one: `XSLFFontInfo` looks an entry up by typeface ignoring case, so two definitions whose `wordFamily` matches that way write into one entry and one set of four elements. The family whose face arrives into an element another family already holds is refused whole, as a family with an unreadable face is — a face of it bound for a free element does not travel either — and the family holding the element keeps its program and its viewer metrics; in the form a caller reaches with one registration — their own family declared under a *bundled* family's viewer name, which the bundled pass does not skip because it skips only a matching `FontName` — that leaves the explicit registration carrying its own font, the bundled pass running after the last slide. The limit of that order is that a registered family is carried before anything is drawn, so one declared under a bundled family's name and never drawn in still takes the element and the bundled family's own text is drawn from that program, where before this guard the bundled face wrote over that part. The elements are claimed where the faces are handed to the presentation and not where they are read, because a registered family's viewer metrics are read in between and a family given up there has had nothing written for it: claiming at the read would let it hold an element it never filled and cost the next family declaring that name its own program. Before it, one entry declared `p:regular` held the later face's bytes with nothing logged, and PowerPoint 16.0 drew both families' text from it: an exported PDF had a single subset of 1,060 glyphs, the later face's glyph count, where the two declared under different names export subsets of 3,023 and 1,060. What refusing cannot fix, and what the log says instead of the ordinary "install the font": the refused family's text carries the shared name too, so a viewer draws it from the program that did travel — a run names a family and no more, so no deck holds two programs for one name and one element. Two definitions can also share a name without colliding, one holding `p:regular` and the other `p:bold`, and both travel; that gets `render.pptx.font.shared.family` once for the name, because the page measured each family with its own program while the deck has one name for both — "font family" and not "registered family" in that line, because a bundled family joins such a pair whenever the face it drew with lands in an element still free. The guard's boundary is what `FontName` counts as one family, which is case-insensitive: two registrations of one name are one family to it and the later program travels rather than being refused, because `FontLibrary` keeps the last factory registered under a name, so that later program is the one the page measured with and refusing it would leave the deck carrying a face no text was laid out in. A registered family is read by two parsers that do not accept the same files: the embedder parses table headers with fontbox, which skips a table whose directory entry runs past the end of the file, and the viewer metrics read the program whole through `java.awt.Font.createFont`, which rejects the font for such an entry. Both reads happen before the presentation is handed anything, so a font only one of them accepts — a truncated one — degrades the family instead of costing the deck. Carrying it without metrics is the alternative not taken: what seats such a family is then the PDF descriptor's ascent, which for 126 of the 130 bundled faces is the ascent the viewer uses and for the four Alegreya Sans faces is a full point out at 10pt text, and which of the two a refused font is cannot be established, since the reader that would say is the one that refused. A face's header is measured where the container is built, against the tighter of the two thousand-byte windows the presentation reads it through — each name on its own when it takes the face, refusing a longer one unchecked from inside the hand-over, and the whole header (96 bytes plus four names) when it reads the written part back. The metrics reader in front of it reads the family and full-name records but never the subfamily, so a long subfamily reached the writer and cost the deck: Lato-Regular rewritten with a 496-character subfamily makes a 1,002-byte full name. A header moves in fours, since the family is written twice, so 998 bytes is the largest any face can express and it is carried; the heaviest header among the 130 bundled faces is 250. The thousand is POI's default, which a host can lower with `IOUtils.setByteArrayMaxOverride`, so the check is a floor rather than a guarantee. A carried program's container names the face by the family and style the file states for the four-style model (`name` id 1 and id 2), not by the typographic names a face states when it falls outside that model (id 16 and id 17): the header read the container is built from keeps ids 1, 2 and 6 only, so a typographic name is discarded before it can be asked for. A face of six weights therefore names itself in the container by the name that made it one of four — and a face whose id 1 is built wrong carries that, as the bundled `AsapCondensed-Italic` does. Nothing in the engine compares those fields with the typeface the deck declares, and no refusal is keyed on what they say; the one refusal that 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 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; no other viewer was measured. What a presentation does go by is the family the **program** states for itself (`name` id 1): measured in PowerPoint 16 on a 45-character line at 20pt, a deck declaring `Asap Condensed` and carrying the bundled `AsapCondensed-Italic`, whose own family record reads `Asap Condensed Condensed Regular`, had that paragraph drawn in Arial Italic at 566.51pt where the program itself draws 443.96pt — the program carried and used by nothing — while the same deck's regular paragraph, whose record does name the declared family, came out at 442.92pt against 443.14pt. Rewriting that one record to the declared name, and nothing else, had the program drawn; rewriting it to the string it already held changed nothing, so neither the rewriting nor the stale checksums it leaves are what the viewer went by. Declaring the family as the italic states it instead had that program drawn for both paragraphs and left the regular face unused, so for a family whose faces disagree in that record no one declared name serves them all. What that costs differs, and both halves were measured in PowerPoint 16: the face above was not drawn at all, while `Oswald-SemiBold`, which the `OrangeOps` preset here pairs under `Oswald` and whose own record reads `Oswald SemiBold`, was drawn and then weighted again by the viewer — and id 16, which rescues that pair for the DOCX comparison above, does not enter into it here. So such a face is carried as the caller asked and named in the log (`render.pptx.font.name.mismatch`) with both families, and the line says only that the face is not reached as the page laid it out; nothing is refused for it, because only one viewer was measured and the deck's bytes are the caller's. The condition is not confined to a mis-built file: a declared typeface is `wordFamily()`, which defaults to the name a family was registered under, so any caller registering a face under a name of their own meets it too. Of the bundled families' face sources exactly one differs, which a sweep in `PptxUndrawnFaceWarningTest` keeps true. A deck that carries a program declares it embedded and asks the reader to keep every character of it rather than only those its slides use, since nothing here subsets a face; a deck that carries none leaves embedding off, where the subset flag POI's blank template already sets decides nothing. Standard-14 names carry no binary and map to metric-compatible viewer replacements (Helvetica to Arial, and so on) rather than being embedded **DOCX.** ⚠️ `DocxFontTable` + `DocxFontEmbedding` — a bundled or registered family the body, a page zone or a header band sets text in is carried in Word's font table (`w:embedRegular`, `w:embedBold`, …), only the faces its styles name, each obfuscated against a key derived from the font as Word stores it. Whole faces, no subsetting, so a character typed later on a machine without the family is still set in it (measured in Word 16 and LibreOffice 26.8). A document that ships a face asks for embedded fonts in its settings (`w:embedTrueTypeFonts`, never `w:saveSubsetFonts`), so the faces survive a save in LibreOffice 24.2 and 26.8 as well as in Word 16. A face whose `OS/2` `fsType` forbids embedding, or allows it for reading and printing only, is named but not shipped, and so is one that cannot be read; the report names each (`embedded font`). A face that ships and neither editor measured draws is named too, as `APPROXIMATED`: a family's slots are filled one file at a time, so a caller can put a program of one typeface in `embedRegular` and one of another in `embedBold`, and the export writes both — but measured with a bold run in Word 16.0.20527 and LibreOffice 24.2 on a 45-character line at 14pt, a family holding Lato regular and IBM Plex Mono bold had both paragraphs drawn from the Lato program, to the hundredth of a point where the same document ships no bold program at all, while that one 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, 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 PDF backend draws the same graph in the program each slot holds, so the configuration is not wrong everywhere — only unreadable here. Carrying such a family as two declared names is the alternative not taken: the same program declared under a name of its own is drawn by both editors (Word 406.53pt, LibreOffice `IBMPlexMono-Bold` 398.10pt against the page's own 398.00pt), but carrying a family that way changes the bytes of every such document and the Word name a bold run carries. 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. Id 1 alone would be wrong on a bundled face and on a shipped preset: `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 and so does that pair, so no family a document here is set in draws this note — which the corpus measures rather than argues, its 105 documents keeping the same 1718 notes. Said only where the family ships a regular face and both programs name their typeface, since that is what was measured and a program whose name cannot be read is one this cannot compare. What the editors read the sameness off was not measured either, so the note is said of every pair of typefaces a family holds and every slot but the regular one, on the strength of the one pair and the one slot that were. One face set per declared name: a family declares itself by its `wordFamily()`, which defaults to the name it was registered under and can be set apart from it, so two families can ask for one name — the same spelling or one differing only in case — and where both are set in text in the same slot an editor reads only one of them, which is all it can do since a `w:font` holds one child per slot (measured in Word 16.0.20527 and LibreOffice 24.2: both set every run naming the family in the face of the element declared first and ignored the other program, a slot the holder left empty included), so the family asking for a name another one already ships under is given up whole and named. Whole rather than only on a slot that clashes, the way the PPTX sibling decides it, and for a slot the holder left empty — the only place where the second program could have been read at all — what the editors go by is not the shape of the declaration but the pair of typefaces: such a program could be written either as an element of its own or as another child of the holder's element, the second being a document two registrations cannot write since the refusal comes first, so it was written by one registration whose two slots hold programs of two typefaces, which an editor cannot tell from the other; both shapes were measured in both editors on a 45-character line at 14pt with a regular and a bold paragraph, with the same answer twice — 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, while Lato regular beside Lato bold had both programs read in either shape, each paragraph drawn from its own. So 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, where it gives up a program both editors would have read; what the editors read the sameness off — the programs' own `name` table, or something else — was not measured, and 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, while within one element the two children's order was swapped and did not decide; which one keeps the name is decided by the order the faces are read in — the document's tree, then the page zones, then the header and footer bands — and not by the registration, which is the opposite of PPTX; and where the declared name is one the editor knows itself the editor's own font wins regardless (Word 16 drew its own Lato for a document declaring `Lato` with another family's program). The limit of that: each shipped face's line is kept under the exact name and slot its runs carry, so a given-up family's paragraphs read the line of a face the holder shipped only where both of those match one the holder filled, and read none where the spelling differs in case or the slot is one the holder left empty. Whether that reaches the written line depends on the two faces: for the pairs the tests use, it did not, every route writing the height the page measured. Standard-14 names carry no binary and fall to Word's own substitution @@ -731,4 +731,14 @@ drew with, or because it is a standard-14 name mapped to a metric-compatible replacement. Three of those lines say what the deck will not carry and leave what it does reference to the text that was drawn — in the family, or in the face that did not travel; embedded -families render silently. +families render silently unless a face of theirs is named by the line +below. That one is about the naming of a face rather than about what the +deck carries: `render.pptx.font.name.mismatch`, once per face whose +program states a family other than the typeface the deck declares. A +presentation matches on the program's own record, so any runs laid out in +that face are not reached the way the page laid them out; what that costs +was measured two ways — a substitute in one case, the viewer's own weight +added in another — so the line names both families and the face's own +source rather than asking for the font to be installed. It says nothing +about whether the family travels: a later face of it can still collide or +fail to be read, and those have their own lines. diff --git a/docs/architecture/backend-capability-matrix.md b/docs/architecture/backend-capability-matrix.md index 85166ec32..81d443586 100644 --- a/docs/architecture/backend-capability-matrix.md +++ b/docs/architecture/backend-capability-matrix.md @@ -53,7 +53,7 @@ names what it cannot carry. The PPTX and DOCX Java APIs are Experimental | [Arabic contextual shaping](backend-capability-details.md#arabic-contextual-shaping) | ✅ shaped before drawing | ✅ base letters; PowerPoint shapes them | ✅ Word shapes it | | [Bidi mirroring](backend-capability-details.md#bidi-mirroring) | ✅ paired punctuation mirrored | ⚠️ brackets flipped in advance; right in PowerPoint only | n/a — Word mirrors it | | [Text extraction fidelity of reordered/shaped text](backend-capability-details.md#text-extraction-fidelity-of-reorderedshaped-text) | ✅ copies out as written | ⚠️ copied text has swapped brackets | n/a — runs stored as written | -| [Font portability](backend-capability-details.md#font-portability) | ✅ subset into the file | ✅ fonts carried in the deck, whole | ⚠️ whole faces embedded; one face set per name; a restricted face, a name-sharing family and a face of another typeface than the family's regular one all named | +| [Font portability](backend-capability-details.md#font-portability) | ✅ subset into the file | ⚠️ fonts carried in the deck, whole; a refused family, a name-sharing one and a face whose own family record is not the declared typeface are all named | ⚠️ whole faces embedded; one face set per name; a restricted face, a name-sharing family and a face of another typeface than the family's regular one all named | | [Writing direction inside a **table cell**](backend-capability-details.md#writing-direction-inside-a-table-cell) | ✅ | ✅ PowerPoint orders the cell text | ⚠️ cell is right-to-left; columns not mirrored | ## Navigation and interactivity diff --git a/docs/font-coverage.md b/docs/font-coverage.md index b8640f021..09afa53f5 100644 --- a/docs/font-coverage.md +++ b/docs/font-coverage.md @@ -135,12 +135,33 @@ Where that record does and does not travel: file. It does *read* these records — id 16 first, then id 1 — to tell whether a family's faces are of one typeface, which is why a family of Asap Condensed faces draws no note about them. -- **A PPTX** carries an embedded face in a container that names it by id 1 and - id 2, so a deck setting text in this face carries - `Asap Condensed Condensed Regular` in that container's family field while the - deck itself declares `Asap Condensed`. Nothing in GraphCompose reads those - container names back, and PowerPoint 16 was measured drawing such a deck the - same whichever name the container carried. +- **A PPTX** is where it costs something. A presentation matches an embedded + face to the family the deck declares by the family the *program* states for + itself — id 1, not the container's fields and not id 16. Measured in + PowerPoint 16: a deck declaring `Asap Condensed` and carrying this face had + that paragraph drawn in **Arial Italic**, the embedded program used by + nothing, while the same deck's regular paragraph was drawn from its own + program. A face can also be mishandled rather than dropped: + `Oswald-SemiBold`, whose record reads `Oswald SemiBold`, came out of a deck + declaring `Oswald` with the viewer's own weight added on top of it. Declaring the family as this face states it instead draws this + program for every paragraph and leaves the regular face unused — so for a + family whose faces disagree in that record, no single declared name serves + them all. The face is still carried, and the export says so in its log + (`render.pptx.font.name.mismatch`) with both names. + +This is not only about one mis-built file. **For a PPTX deck, declare a family +under the name its files state in `name` id 1.** The declared name is +`wordFamily()`, which defaults to the name you register the family under, so a +family registered as `Corporate` from a file that states `Acme Sans` meets the +same condition — a presentation matches on the file's record, and the program +you paid bytes for is not what draws your text. A multi-weight face registered +beside its regular meets it too: `Oswald-SemiBold` states `Oswald SemiBold`, +and a deck declaring `Oswald` was measured drawing it with the viewer's own +weight added on top. + +One route out is to register the odd face as a family of its own, declared under +the name that face states, and set that text in it; that was not measured, only +reasoned from the arms above. ## See also diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 35b17711d..8d0cfa2da 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -25,6 +25,25 @@ bullet `•` (U+2022) **is** in WinAnsi, but the larger black circle `●` Full detail and the coverage table: [font coverage and glyph fallback](font-coverage.md). +## PowerPoint draws Arial where the deck embeds a font + +A presentation matches an embedded face to the family a deck declares by the +family the **program** states for itself — `name` id 1 — not by the name the +deck declares or anything in the font container. Where the two differ, the face +travels in the deck and the runs laid out in it are not reached that way: +measured in PowerPoint 16, one such face was replaced by Arial Italic and +another was drawn with the viewer's own weight added on top. + +The export says so: look for `render.pptx.font.name.mismatch` in the render log, +which names the family the file states and the one the deck declares. + +Declare the family under the name its files state. The declared name is +`wordFamily()`, which defaults to the name the family was registered under, so +`FontFamilyDefinition.files("Corporate", path)` on a file that states +`Acme Sans` meets this — as does a weight registered beside its regular, such as +`Oswald-SemiBold` under `Oswald`. See +[Font coverage](font-coverage.md#what-a-bundled-face-calls-itself). + ## DOCX export is missing paths, polygons, or other drawing **Cause.** The DOCX backend (`DocxSemanticBackend`, Apache POI) is a diff --git a/render-pptx/src/main/java/com/demcha/compose/document/backend/fixed/pptx/PptxEmbeddedFont.java b/render-pptx/src/main/java/com/demcha/compose/document/backend/fixed/pptx/PptxEmbeddedFont.java index 8fbd2ebb2..c2283c345 100644 --- a/render-pptx/src/main/java/com/demcha/compose/document/backend/fixed/pptx/PptxEmbeddedFont.java +++ b/render-pptx/src/main/java/com/demcha/compose/document/backend/fixed/pptx/PptxEmbeddedFont.java @@ -1,8 +1,10 @@ package com.demcha.compose.document.backend.fixed.pptx; import org.apache.fontbox.ttf.FontHeaders; +import org.apache.fontbox.ttf.NamingTable; import org.apache.fontbox.ttf.OS2WindowsMetricsTable; import org.apache.fontbox.ttf.OTFParser; +import org.apache.fontbox.ttf.TrueTypeFont; import org.apache.pdfbox.io.RandomAccessReadBuffer; import org.apache.poi.common.usermodel.fonts.FontHeader; @@ -78,7 +80,21 @@ private PptxEmbeddedFont() { } static byte[] wrap(InputStream input) throws IOException { - byte[] fontData = input.readAllBytes(); + return wrap(input.readAllBytes()); + } + + /** + * The same, for a caller that already holds the program. + * + *

Which the embedder does: it reads the face once and asks what family the program states + * for itself before handing it over, and reading the stream twice would copy every face twice + * over for nothing.

+ * + * @param fontData the face's own file, as read + * @return the container a presentation reads + * @throws IOException if the program cannot be read, or its terms forbid embedding + */ + static byte[] wrap(byte[] fontData) throws IOException { Metadata metadata = metadata(fontData); validateEmbeddingRights(metadata.fsType()); @@ -190,7 +206,11 @@ static Style styleOf(byte[] container) { * the whole account of it.

* *

Do not key a guard on what these two fields say. Nothing in the engine compares - * them with the typeface a deck declares, and nothing in it but a test reads what they say — + * these with the typeface a deck declares — {@link #statedFamilyOf} compares the + * family a program states, which is a different read of a different record: that one pins the + * Windows en-US id 1, where the header's family comes through fontbox's search of the Unicode, + * Windows and Macintosh platforms in turn and so can answer a record no viewer matches on. + * Nothing in the engine but a test reads what the container's two fields say — * the presentation reads the header itself, which is what {@link #validateReadableHeader} * answers for. Preferring the typographic names was tried on both faces in this repository * that state them, the bundled {@code AsapCondensed-Italic} and the {@code Oswald-SemiBold} a @@ -310,6 +330,54 @@ private static void putName(ByteBuffer target, byte[] encoded) { target.putShort((short) 0); } + /** + * The family a program states for itself, which is what a presentation matches an embedded + * face to a declared typeface on. + * + *

Measured in PowerPoint 16 on the bundled {@code AsapCondensed-Italic}, whose own family + * record reads {@code Asap Condensed Condensed Regular} where the other three faces of that + * family read {@code Asap Condensed}: declared as {@code Asap Condensed}, the italic paragraph + * was drawn in Arial Italic and the program was not used; rewriting that one record to the + * declared name, and nothing else, had the program drawn. Rewriting it to the same string it + * already held changed nothing, so the rewriting itself — which leaves the table directory's + * checksums as they were — is not what the viewer went by. Declaring the family as the italic + * states it instead had that program drawn for both paragraphs and left the regular face + * unused, so for a family whose faces disagree here no one declared name serves them all.

+ * + *

Name id 1, deliberately, and not the typographic family of id 16. The DOCX backend + * prefers id 16 where a face states one, because its question is which typeface a face belongs + * to; the question here is what a viewer matches on, and what it was measured matching on is + * id 1. Reading id 16 here would answer {@code Asap Condensed} for the very face a viewer + * refuses, and the warning would fall silent exactly where it is needed.

+ * + *

The Windows en-US record and only it, because that is the record the measurement read; + * a face stating id 1 on the Unicode or Macintosh platform alone answers null here and is + * left unsaid, which is the safe direction for a warning — silence misses a face, a guess + * accuses a good one. The name is trimmed, as {@code FontFamilyDefinition} trims the name a + * family declares, so a trailing space in a file cannot pass for a different family. The + * program is parsed whole rather than through the header read {@link #metadata} uses, whose + * {@code FontHeaders} exposes fontbox's own English-name pick and not the record itself; the + * parse is asked to take an embedded font, so a face missing a table a standalone one must + * have is read here as the embedder reads it. Once per face per render, and not on a layout or + * render path.

+ * + * @param program the face's own file, as read + * @return the family it states for the Windows en-US record, or null where it states none or + * cannot be read + */ + static String statedFamilyOf(byte[] program) { + try (TrueTypeFont font = new OTFParser(true).parse(new RandomAccessReadBuffer(program))) { + NamingTable naming = font.getNaming(); + if (naming == null) { + return null; + } + String stated = naming.getName(1, 3, 1, 0x409); + return stated == null || stated.isBlank() ? null : stated.trim(); + } catch (IOException | RuntimeException unreadable) { + return null; + } + } + private static String valueOr(String value, String fallback) { return value == null || value.isBlank() ? fallback : value; } diff --git a/render-pptx/src/main/java/com/demcha/compose/document/backend/fixed/pptx/PptxRenderEnvironment.java b/render-pptx/src/main/java/com/demcha/compose/document/backend/fixed/pptx/PptxRenderEnvironment.java index 25e1bc46f..ba6c76524 100644 --- a/render-pptx/src/main/java/com/demcha/compose/document/backend/fixed/pptx/PptxRenderEnvironment.java +++ b/render-pptx/src/main/java/com/demcha/compose/document/backend/fixed/pptx/PptxRenderEnvironment.java @@ -866,9 +866,38 @@ private static FamilyPrograms readPrograms(FontFamilyDefinition family, if (programs.containsKey(description)) { continue; } - byte[] container; + byte[] program; try (InputStream stream = source.openStream()) { - container = PptxEmbeddedFont.wrap(stream); + program = stream.readAllBytes(); + } + byte[] container = PptxEmbeddedFont.wrap(program); + // A face whose program states a family of its own, said where the names are known. + // A presentation matches an embedded face to the declared typeface by that record + // and not by the names the container carries, so a face naming another family is + // not reached the way the page laid it out. What that costs differs, and both + // halves were measured in PowerPoint 16: one such face was not drawn at all and + // its runs came out in a substitute, another was drawn and then weighted again by + // the viewer. So this says what the two names are and leaves the outcome to the + // reader rather than promising the one it happened to measure first. + // + // Nothing is refused for it, and nothing here says the family travels: a later + // face of it can still collide, be unreadable, or lose its viewer metrics, and + // each of those says so on its own line. What this line is about is the naming. + // + // The names are compared ignoring case, which folds the same way wherever the + // export runs. Whether a viewer matches case-insensitively was not measured, so + // a pair differing only in case is left silent rather than warned about on a + // guess. + String stated = PptxEmbeddedFont.statedFamilyOf(program); + if (stated != null && !stated.equalsIgnoreCase(typeface)) { + LOG.warn("render.pptx.font.name.mismatch family={} typeface={} face={} " + + "states={} — a presentation matches an embedded face on the family " + + "its program states for itself, which is not the one this deck " + + "declares, so any runs laid out in this face are not reached the " + + "way the page laid them out; measured in PowerPoint 16, one such " + + "face was replaced by a substitute and another was drawn with the " + + "viewer's own weight added", + familyName.name(), typeface, description, stated); } // Which slot the face is seated in is not the slot it was registered under: // a presentation reads it off the container, so a face put in one slot of diff --git a/render-pptx/src/test/java/com/demcha/compose/document/backend/fixed/pptx/PptxFontNameMismatchTest.java b/render-pptx/src/test/java/com/demcha/compose/document/backend/fixed/pptx/PptxFontNameMismatchTest.java new file mode 100644 index 000000000..06292549d --- /dev/null +++ b/render-pptx/src/test/java/com/demcha/compose/document/backend/fixed/pptx/PptxFontNameMismatchTest.java @@ -0,0 +1,178 @@ +package com.demcha.compose.document.backend.fixed.pptx; + +import com.demcha.compose.font.DefaultFonts; +import com.demcha.compose.font.FontFamilyDefinition; +import org.assertj.core.api.InstanceOfAssertFactories; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +import java.io.InputStream; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.LinkedHashMap; +import java.util.LinkedHashSet; +import java.util.List; +import java.util.Map; +import java.util.Set; + +import static org.assertj.core.api.Assertions.assertThat; + +/** + * A carried face whose program states a family of its own. + * + *

An embedded face is matched to the declared typeface by the family the program states for + * itself, not by the name the container carries. Measured in PowerPoint 16 on the bundled + * {@code AsapCondensed-Italic}, whose own family record reads {@code Asap Condensed Condensed + * Regular} where its three siblings read {@code Asap Condensed}: declared as {@code Asap + * Condensed}, the italic paragraph came out in Arial Italic at 566.51pt where the program itself + * draws 443.96pt, on a 45-character line at 20pt, while the same deck's regular paragraph was + * drawn from its program. Rewriting that one record to the declared name had the program drawn; + * rewriting it to the string it already held changed nothing, so the rewriting was not what the + * viewer went by.

+ * + *

What that costs differs, and both halves were measured: that face was not drawn at all, while + * the {@code Oswald-SemiBold} a preset here pairs under {@code Oswald} was drawn and then weighted + * again by the viewer. So the line says what the two names are rather than promising one outcome.

+ * + *

Nothing is refused for it. The program travels as the caller asked and no deck's bytes change + * — what the export adds is the warning, so the reason is in the log rather than only in the + * picture.

+ */ +class PptxFontNameMismatchTest { + + /** The bundled family whose italic face states a family of its own. */ + private static final String ASAP_REGULAR = "fonts/google/asapcondensed/AsapCondensed-Regular.ttf"; + private static final String ASAP_ITALIC = "fonts/google/asapcondensed/AsapCondensed-Italic.ttf"; + /** A family whose every face states the name the family declares. */ + private static final String LATO_REGULAR = "fonts/google/lato/Lato-Regular.ttf"; + private static final String LATO_ITALIC = "fonts/google/lato/Lato-Italic.ttf"; + + @TempDir + Path directory; + + private RenderLogCapture log; + + @BeforeEach + void captureRenderLog() { + log = RenderLogCapture.attach(); + } + + @AfterEach + void releaseRenderLog() { + log.close(); + } + + @Test + void theFamilyAFaceStatesForItselfIsWhatAPresentationMatchesOn() throws Exception { + // Read through the backend's own reader, so the two cases below rest on what the files + // hold rather than on what this test says they hold. + assertThat(PptxEmbeddedFont.statedFamilyOf(PptxDeck.face(ASAP_ITALIC))) + .isEqualTo("Asap Condensed Condensed Regular"); + assertThat(PptxEmbeddedFont.statedFamilyOf(PptxDeck.face(ASAP_REGULAR))) + .isEqualTo("Asap Condensed"); + assertThat(PptxEmbeddedFont.statedFamilyOf(PptxDeck.face(LATO_ITALIC))) + .isEqualTo("Lato"); + assertThat(PptxEmbeddedFont.statedFamilyOf(PptxDeck.face(LATO_REGULAR))) + .isEqualTo("Lato"); + } + + @Test + void aFaceStatingAnotherFamilyThanTheDeckDeclaresIsCarriedAndNamed() throws Exception { + Path regular = Files.write(directory.resolve("AsapCondensed-Regular.ttf"), + PptxDeck.face(ASAP_REGULAR)); + Path italic = Files.write(directory.resolve("AsapCondensed-Italic.ttf"), + PptxDeck.face(ASAP_ITALIC)); + FontFamilyDefinition family = FontFamilyDefinition.files("asap-condensed", regular) + .italicPath(italic).wordFamily("Asap Condensed").build(); + + byte[] deck = PptxDeck.registering(family, page -> page.addParagraph( + paragraph -> paragraph.text("Drawn in the default face"))); + + assertThat(PptxDeck.fontParts(deck)) + .as("both faces travel: this is not a refusal") + .hasSize(2); + assertThat(PptxDeck.part(deck, "ppt/presentation.xml")) + .as("and the deck declares the family the caller asked for, not the one the " + + "italic face states — the longer name contains the shorter, so the " + + "attribute is asserted whole") + .contains("typeface=\"Asap Condensed\""); + + assertThat(log.messages("render.pptx.font.name.mismatch")) + .as("the face is named, with the family it states and the one the deck declares " + + "— a reader has to see both to know which of the two to go after, and " + + "which face of the family it is") + .singleElement(InstanceOfAssertFactories.STRING) + .as("the declared name whole: the stated one begins with it, so a prefix match " + + "would pass for either") + .contains("typeface=Asap Condensed face=") + .contains("states=Asap Condensed Condensed Regular") + .contains(italic.toString()); + } + + @Test + void oneBundledFaceStatesAFamilyOtherThanItsOwnFamilyDeclares() throws Exception { + // The catalogue against the reading, as its two siblings in this package measure their + // own guards against it. The count is quoted in the capability details and on the + // font-coverage page, and a font bump is exactly what would make both of them false + // without a line of code changing — so it is measured here rather than written down + // twice and believed. Deduped the way the embedder dedupes. + Map differing = new LinkedHashMap<>(); + int faces = 0; + for (FontFamilyDefinition family : DefaultFonts.bundledFamilies()) { + if (family.fontSourceSet().isEmpty()) { + continue; + } + FontFamilyDefinition.FontSourceSet sources = family.fontSourceSet().get(); + Set read = new LinkedHashSet<>(); + for (FontFamilyDefinition.FontBinarySource source : List.of(sources.regular(), + sources.bold(), sources.italic(), sources.boldItalic())) { + if (!read.add(source.description())) { + continue; + } + faces++; + byte[] face; + try (InputStream stream = source.openStream()) { + face = stream.readAllBytes(); + } + String stated = PptxEmbeddedFont.statedFamilyOf(face); + if (stated != null && !stated.equalsIgnoreCase(family.wordFamily())) { + differing.put(source.description(), stated); + } + } + } + + assertThat(faces) + .as("the premise: this walked the catalogue rather than an empty list") + .isGreaterThan(100); + assertThat(differing) + .as("the one bundled face whose own family record is not the name its family " + + "declares, which is the count both documents quote") + .hasSize(1); + assertThat(differing.keySet().iterator().next()).contains("AsapCondensed-Italic"); + assertThat(differing.values().iterator().next()) + .isEqualTo("Asap Condensed Condensed Regular"); + } + + @Test + void aFamilyWhoseFacesAllStateItsOwnNameIsNotNamed() throws Exception { + Path regular = Files.write(directory.resolve("Lato-Regular.ttf"), + PptxDeck.face(LATO_REGULAR)); + Path italic = Files.write(directory.resolve("Lato-Italic.ttf"), + PptxDeck.face(LATO_ITALIC)); + FontFamilyDefinition family = FontFamilyDefinition.files("lato-pair", regular) + .italicPath(italic).wordFamily("Lato").build(); + + byte[] deck = PptxDeck.registering(family, page -> page.addParagraph( + paragraph -> paragraph.text("Drawn in the default face"))); + + assertThat(PptxDeck.fontParts(deck)) + .as("the premise: this family is carried, so silence is about the names and " + + "not about an empty deck") + .hasSize(2); + assertThat(log.messages("render.pptx.font.name.mismatch")) + .as("every face states the name the deck declares, so there is nothing to say") + .isEmpty(); + } +}