feat(preview): explain kerning, and correct the tips against FreeType

kerning gets the ? badge the other tuning controls have: what a kern pair
is, why the control is a factor rather than a switch (the device stores an
adjustment in sixteenths of a pixel, so a face kerned for print
over-tightens), and that turning it down shrinks the table, since the pairs
are scaled before they are grouped into classes.

Reading FreeType 2.14 to check the tips written yesterday corrected four of
them and turned up one thing the panel had wrong.

- light hinting preserves inter-glyph spacing, it does not leave the widths
  to fall where they may (freetype.h, FT_LOAD_TARGET_LIGHT).
- Dropout control corrects the bitmap for shape continuity, which is wider
  than a stroke vanishing (ftimage.h).
- Stem darkening is meant for a screen that blends in linear light, and
  FreeType's own note warns it looks heavy and fuzzy elsewhere, which is
  what four grey levels are (ftdriver.h, no-stem-darkening).
- Mono changes the fit rather than only rounding advances.

The panel left grayscale hinting live while mono rasterizing was on, where
it does nothing: FreeType turns backward compatibility off for a monochrome
render (ttgload.c), which ttinterp.h calls falling back to version 35
behaviour, and those x-axis hacks are the whole difference between the two
interpreters. The row now greys with that reason, checked in a browser on a
face that carries bytecode. The docstring in cpfont/convert.py, the config
reference and the greying section of docs/preview.md say it too.

Verified as read: the auto-hinter darkens only at a light render mode
(afloader.c), CF2 darkens a scaled load (psft.c), normal runs the font's own
bytecode unless the TTF has no fpgm or prep (ftobjs.c), and a tricky face is
exempt from the auto-hinter entirely.

Author: CrazyCoder

docs/fonts.md

@@ -127,7 +127,7 @@ bolditalic     = NotoSans-BoldItalic.ttf
 | `weight` | `0` | outline emboldening in pixels. Advance widths do not move, so text gets heavier at the same spacing |
 | `slant` | `0` | shear as a tangent. `0.25` is about 14 degrees, for synthesizing an oblique a family lacks |
 | `hinting` | `normal` | `normal`, `light` (vertical only, softer), `none`, or `auto` (FreeType's auto-hinter, worth trying when a font looks muddy at small sizes) |
-| `grayscale_hinting` | `no` | run FreeType's interpreter version 35, which fits stems on both axes rather than hinting for a subpixel display. Only reaches a TrueType face carrying bytecode, under `hinting = normal`. See [Tuning how glyphs look](#tuning-how-glyphs-look) |
+| `grayscale_hinting` | `no` | run FreeType's interpreter version 35, which fits stems on both axes rather than hinting for a subpixel display. Only reaches a TrueType face carrying bytecode, under `hinting = normal` and with `mono` off. See [Tuning how glyphs look](#tuning-how-glyphs-look) |
 | `mono` | `no` | rasterize each glyph as one bit per pixel, with FreeType's dropout control, instead of thresholding coverage. The font then draws in two levels whatever the reader's anti-aliasing setting is. See [Tuning how glyphs look](#tuning-how-glyphs-look) |
 | `stem_darkening` | `no` | FreeType stem darkening. Narrow: a CFF or OTF face under any hinting but `auto`, and a TrueType face only under `hinting = light`. See [Tuning how glyphs look](#tuning-how-glyphs-look) |
 
@@ -539,6 +539,12 @@ anyway, and so does any family under `light`, `auto` or `none`. So this is a
 `hinting = normal` control on a TrueType face, and the preview greys the row
 everywhere else.
 
+`mono` takes it as well, for a reason of its own. FreeType turns backward
+compatibility off whenever the raster is monochrome, which its own source
+calls falling back to version 35 behaviour, and that behaviour is the whole
+difference between the two interpreters. So under `mono = yes` both settings
+draw the same glyph, and the row greys there too.
+
 ### Mono rasterizing
 
 `mono` builds a font with no greys in it at all: every pixel comes out black

docs/preview.md

@@ -298,7 +298,9 @@ switch that works is the worse mistake.
 The first picks FreeType's other bytecode interpreter, so it is out of reach
 for a face with no bytecode to run: a CFF family, a TrueType family with no
 instructions, and any family under `light`, `auto` or `none`, where the
-auto-hinter draws instead. The second leaves a pixel empty or full. While it is
+auto-hinter draws instead. It is out of reach while **mono rasterizing** is on
+as well, since FreeType hints the way that interpreter does whenever the
+raster is monochrome, whichever of the two you have picked. The second leaves a pixel empty or full. While it is
 on there is no coverage in between for **gamma** or the thresholds to act on,
 so those two rows are greyed.
 

src/crossglyph/cpfont/convert.py

@@ -1005,6 +1005,13 @@ def apply_interpreter(grayscale):
     so does any face under `light`, `auto` or `none`, unless FreeType calls it
     tricky, which exempts it from that dispatch entirely.
 
+    `mono` takes it too, for a reason of its own. FreeType turns backward
+    compatibility off for a monochrome render (truetype/ttgload.c, the
+    TT_INTERPRETER_VERSION_40 gate on `mode != FT_RENDER_MODE_MONO`), and
+    truetype/ttinterp.h calls that falling back to version 35 behaviour. What
+    backward compatibility gates is the set of x-axis hacks that separate the
+    two interpreters, so under `mono` both values draw the same glyph.
+
     Nothing reports a build that does not carry the property: the binding
     discards FreeType's error, so the call does nothing and the page is drawn
     with whichever interpreter the build defaults to. See apply_stem_darkening.

src/crossglyph/preview/static/index.html

@@ -185,7 +185,31 @@
 
 
   <div class="row num">
-    <label class="name" for="kerning">kerning <span class="unit">×</span></label>
+    <span class="name"><label for="kerning">kerning <span class="unit">×</span></label><span
+        class="explain">
+        <button type="button" class="info" aria-label="What kerning does"
+                aria-describedby="kerning-tip">?</button>
+        <span class="tip" id="kerning-tip" role="tooltip">
+          How hard particular pairs of letters are pulled together. A font
+          carries a table of them, so that the A and the V in "AV" tuck under
+          each other instead of leaving a hole, and the build reads that table
+          and writes the answers into the file.
+          <br><br>
+          This is a factor and not a switch, because the useful setting is
+          often part of the way. 1 is the amount the designer drew, 0 leaves
+          the pairs alone, and 0.5 keeps the shape of their decisions at half
+          the amount. A face kerned for print often over-tightens on a screen
+          this size, where the device stores each adjustment in sixteenths of
+          a pixel and one of those is already a good fraction of a stem.
+          <br><br>
+          Turning it down makes the file smaller as well. The pairs are scaled
+          before they are grouped, so pairs that flatten into each other are
+          then grouped together, and those that round away to nothing are
+          dropped. A style with more kerning entries than the reader will load
+          is refused outright, and turning this down is one of the two ways
+          out. Narrower coverage is the other.
+        </span>
+      </span></span>
     <input type="range" data-slider-for="kerning" min="0" max="2" step="0.05" value="1" tabindex="-1" aria-hidden="true">
     <span class="stepper">
       <button type="button" class="step mono" data-for="kerning" data-dir="-1" aria-label="decrease kerning">−</button>
@@ -260,8 +284,8 @@
           <br><br>
           <strong>normal</strong> runs the font's own hinting instructions
           where it carries them, and lets FreeType work it out where it does
-          not. <strong>light</strong> fits vertically only, which keeps the
-          shapes the designer drew and lets the widths fall where they may.
+          not. <strong>light</strong> snaps to the grid vertically only, which
+          keeps the horizontal shapes and the spacing the designer drew.
           <strong>none</strong> fits nothing. <strong>auto</strong> has
           FreeType fit the font whatever instructions it carries, and is worth
           trying on a face that looks muddy at small sizes.
@@ -314,6 +338,10 @@
             <strong>none</strong> hinting, is fitted by FreeType's own
             auto-hinter instead. The row greys itself in those cases and says
             which one it is.
+            <br><br>
+            One case it does not grey: with <strong>mono rasterizing</strong>
+            on, FreeType drops back to this older engine's behaviour of its
+            own accord, so the switch changes nothing either way.
           </span>
         </span></span>
       <input id="grayscale_hinting" name="grayscale_hinting" type="checkbox">
@@ -332,8 +360,8 @@
           <span class="tip" id="mono-tip" role="tooltip">
             Builds the font with no greys in it at all. Every pixel comes out
             paper or ink, chosen by FreeType's dropout control, a rule that
-            keeps a stroke too thin to land on a pixel from disappearing
-            altogether. Nothing measures coverage and cuts it at the
+            turns a pixel on where a stroke would otherwise break up or vanish
+            between two of them. Nothing measures coverage and cuts it at the
             thresholds.
             <br><br>
             Worth trying for a reader with <strong>anti-aliasing</strong> off.
@@ -345,9 +373,10 @@
             It belongs to the font and not to the page: one built this way
             draws in two levels whatever the reader's anti-aliasing is set to.
             <strong>gamma</strong> and <strong>thresholds</strong> have no
-            coverage left to work on while it is on, so both grey out. Fitting
-            to whole pixels also moves some advance widths, so lines break in
-            slightly different places.
+            coverage left to work on while it is on, so both grey out. The
+            outline is fitted differently as well, so some advance widths land
+            on other whole pixels and the text sets to slightly different
+            lines.
           </span>
         </span></span>
       <input id="mono" name="mono" type="checkbox">
@@ -380,6 +409,11 @@
             can still come out unchanged, its stems falling where the curve
             rounds to nothing, and <strong>weight</strong> is the control that
             will move it.
+            <br><br>
+            FreeType means this for a screen that blends in linear light,
+            which this one does not: it has four levels and nothing between
+            them. Its own documentation warns that the result is heavy and
+            fuzzy elsewhere. Judge it on the page rather than leaving it on.
           </span>
         </span></span>
       <input id="stem_darkening" name="stem_darkening" type="checkbox">

src/crossglyph/preview/static/js/dom.js

@@ -73,7 +73,14 @@ export function darkeningReason(outlines, hinting) {
 // does any face under light, auto or none. A tricky font is FreeType's own
 // exception to that last one -- it is never handed to the auto-hinter, so its
 // bytecode runs in every mode that hints at all.
-export function grayscaleReason(outlines, bytecode, tricky, hinting) {
+//
+// Mono rasterizing takes it away for a reason of its own. FreeType turns
+// backward compatibility off for a monochrome render (ttgload.c, the
+// TT_INTERPRETER_VERSION_40 gate on `mode != FT_RENDER_MODE_MONO`), and
+// ttinterp.h calls that falling back to version 35 behaviour. The x-axis
+// hacks that separate the two interpreters are what backward compatibility
+// gates, so with mono on both settings draw the same glyph.
+export function grayscaleReason(outlines, bytecode, tricky, hinting, mono) {
   if (outlines && outlines !== "truetype" && outlines !== "mixed") {
     return "These are not TrueType outlines, so there is no bytecode for "
       + "either interpreter to run.";
@@ -92,6 +99,10 @@ export function grayscaleReason(outlines, bytecode, tricky, hinting) {
     return "The auto-hinter draws it under " + hinting + " hinting, so the "
       + "bytecode interpreter has nothing to do.";
   }
+  if (mono) {
+    return "FreeType hints as this interpreter does whenever the raster is "
+      + "monochrome, so mono rasterizing already gets you it.";
+  }
   return "";
 }
 
@@ -134,7 +145,8 @@ export function syncFeatures() {
   const dark = darkeningReason(outlines, hinting.value);
   darkening.disabled = Boolean(dark);
   darkening.title = dark;
-  const grey = grayscaleReason(outlines, bytecode, tricky, hinting.value);
+  const grey = grayscaleReason(outlines, bytecode, tricky, hinting.value,
+                               Boolean(form.elements.mono?.checked));
   grayscale.disabled = Boolean(grey);
   grayscale.title = grey;
 }

tests/preview_persistence.mjs

@@ -4200,6 +4200,10 @@ for (const deferred of [
         grayscaleReason("truetype", true, false, "light") !== "");
   check("a family whose faces disagree on format is judged on its bytecode",
         grayscaleReason("mixed", true, false, "normal") === "");
+  // FreeType turns backward compatibility off for a monochrome render, which
+  // is the difference between the two interpreters, so the choice is moot.
+  check("and mono rasterizing takes the row whatever the font is",
+        grayscaleReason("truetype", true, false, "normal", true) !== "");
 }
 
 // 36. Mono rasterizing leaves a pixel empty or full, so the two knobs that