Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 —
Expand Down
14 changes: 12 additions & 2 deletions docs/architecture/backend-capability-details.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/architecture/backend-capability-matrix.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
33 changes: 27 additions & 6 deletions docs/font-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
19 changes: 19 additions & 0 deletions docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -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;

Expand Down Expand Up @@ -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.
*
* <p>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.</p>
*
* @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());

Expand Down Expand Up @@ -190,7 +206,11 @@ static Style styleOf(byte[] container) {
* the whole account of it.</p>
*
* <p><b>Do not key a guard on what these two fields say.</b> Nothing in the engine compares
* them with the typeface a deck declares, and nothing in it but a test reads what they say —
* <em>these</em> 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
Expand Down Expand Up @@ -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.
*
* <p>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.</p>
*
* <p><b>Name id 1, deliberately, and not the typographic family of id 16.</b> 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.</p>
*
* <p>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.</p>
*
* @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;
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Loading