docs: how to probe the harness with a document of your own

Two traps cost an afternoon: an uncompressed mimetype entry, or LibreOffice
produces no PDF for the file at all, and a font name with no font-face
declaration, which it then resolves differently from the editor — inventing a
0.4mm-per-line difference that no real document has. Plus the note that a
LibreOffice shipping its own Liberation/Carlito copies needs no font install.
This commit is contained in:
Steffen Becker committed 2026-09-04 19:30:09 +02:00
1 parent 586ff300aa
commit 976cd4beda
1 file changed
+15
+15
View File
@@ -45,6 +45,11 @@ line breaks differently for a reason that is not a bug. With them, both engines
resolve Times New Roman → Liberation Serif, Arial → Liberation Sans, Calibri →
Carlito, Cambria → Caladea — the same files the editor bundles.
Where the LibreOffice build ships those families itself (the macOS app bundle does:
`Contents/Resources/fonts/truetype/`), it resolves them without fontconfig and the step
is only about what it does *not* ship — `fc-list` showing neither Liberation nor Carlito
is then not a reason to distrust a run.
**But install only what LibreOffice does not already ship.** A second copy of a
family it bundles makes its render *non-deterministic*: it picks between the two
files per run — measured as `Carlito` against `Carlito-Regular` in the PDF's font
@@ -79,6 +84,16 @@ reading it fails with `ENOENT` on a fresh clone; it zips its own document instea
(`docx-onoff.test.ts` — both importers take a `Uint8Array`, not a path), or reads
`tests/corpus/`, which is committed. CI greps for the read.
## Probing with a purpose-built document
The fastest probe is an `.odt` of your own run through the harness: both engines lay the
same file out and the report *is* the measurement, in the units the corpus uses. Build it
with `fflate` (`zipSync`), keep it in the scratchpad, and mind two traps — `mimetype` has
to be stored uncompressed (`{ level: 0 }`) or LibreOffice produces no PDF at all, and a
`style:font-name` with **no `<style:font-face>` declaration** is not resolved: LibreOffice
falls back (Calibri → Liberation Sans) where the editor honours the name, which invents a
line-height difference that is not there in any real document.
## Prerequisites, part two: Calibri Light
Word's default theme heading font. LibreOffice's substitution table knows Calibri but