docs: write for a reader who is not a programmer

Every font and rasterizing term now carries a plain gloss the first time a
page uses it, and keeps its own name beside it. Hinting had no explanation
anywhere: a stem straddling two pixels comes out as two pale columns, and
hinting nudges the outline onto the grid. The same for the quantizer, gamma,
thresholds, stem darkening, grayscale hinting, mono, dropout control, em,
advance, line pitch, kerning, ligatures, GPOS and GSUB, codepoints, variable
font axes, WASI and Docker Compose.

fonts.md and preview.md both opened on syntax. They now say what a build
makes and what the preview is for first, and fonts.md defines family, style
and face before using them.

Numbers that go stale are out: the Literata build timings, the worker cap,
the render module size and its language count, the glyph count and download
sizes in the README, two preset sizes, an eighteen file folder. The limits
the format and the firmware fix are kept, with their citations, and so are
the measurements that state their conditions.

Two claims were wrong and are corrected. Only gamma, thresholds and the
export controls carry a ? tooltip, not every control. Four shades of grey is
what these readers draw, not what e-ink draws.

docker.md loses a paragraph about an upload interface that does not exist.
CONTRIBUTING.md carries the writing rules, since a contributor cannot see
the standard they live in.

Author: CrazyCoder

CONTRIBUTING.md

@@ -397,7 +397,26 @@ would be a second name. `crossglyph --version` reports what the stamp says.
 
 ## Writing
 
-Comments explain why, not what. They describe what the code does now, never
-what it used to do: git has that, and a comment retelling it is wrong by the
-next change. A firmware behaviour a value works around is worth a citation, and
+This covers the README, `docs/`, `--help` text, error messages, the strings in
+the preview, the release notes and the comments in the code.
+
+Write for somebody who wants to build a font and is not a programmer. Plain
+English, short common words, no em dashes and no `--` standing in for one,
+straight quotes, no emoji, sentence case in headings.
+
+Font and rasterizing terms are the point of this tool and strange to most
+readers. Gloss each one the first time a page uses it. "Stem darkening thickens
+the strokes, which helps on a screen where thin letters look washed out" tells
+the reader something; "stem darkening applies a stem darkening factor" does
+not. Name settings the way the reader's own surface names them: the label for
+anything about the preview, the config key for anything about `build`.
+
+Leave out numbers that go stale. Version numbers, glyph counts, download sizes
+and benchmark timings are all wrong a few commits later and nobody notices.
+Give the shape instead, and keep a number when something fixed holds it in
+place, such as the four greys the screen draws.
+
+Comments explain why, not what. Both comments and pages describe what the code
+does now. Git holds the rest, and a comment retelling it is wrong by the next
+change. A firmware behaviour a value works around is worth a citation, and
 those citations are why several comments here are long.

README.md

@@ -2,12 +2,13 @@
 
 Tune a font for an Xteink reader running
 [CrossPoint](https://github.com/crosspoint-reader/crosspoint-reader), and watch
-the page redraw as you move each control. A change lands in 10 to 300 ms,
-depending on your hardware and how much of the font is being built.
+the page redraw as you move each control. Changes appear as fast as your
+machine can rebuild that part of the font, which is fast enough to keep turning
+a knob and watching what happens.
 
-Most fonts need tuning to read well at two bits per pixel. Without a preview
-every guess costs a card swap or an emulator run, which is why most people stop
-at the point size.
+These readers draw in four shades of grey and nothing else, so most fonts need
+work before they read well on one. Without a preview, every guess costs a card
+swap or an emulator run, which is why most people stop at the point size.
 
 <p align="center">
   <a href="docs/images/tune.png"><img src="docs/images/tune.png" width="32%"
@@ -18,36 +19,43 @@ at the point size.
      alt="The Export panel with sizes, coverage, fallbacks and build controls"></a>
 </p>
 
-- the firmware's own renderer, its C++ compiled to WebAssembly, so the page
-  shows what the device draws and not an impression of it
-- rasterizing controls for gamma, the three grey thresholds, weight, slant,
-  hinting mode, grayscale hinting, mono rasterizing, stem darkening, line
-  height, letter and word spacing, kerning strength, ligatures, proportional
-  figures
-- page controls, so the page you judge is set up like the device you are
-  judging for: margin, alignment, line spacing, hyphenation and the language
-  its patterns come from, paragraph spacing, anti-aliasing and night mode
-- the page inside the reader itself, rendered from XTEINK's own models, at one
-  screen pixel to one of your monitor's with neither the page nor the body
-  resampled, shaded to the cast measured off a real device and adjustable from
-  there, and copied out as an image in one press
-- variable fonts build at the weight their designer named, or at any weight you
-  pick: left alone, Merriweather would ship its Light as your Regular
-- four sizes of a four-style family, 795 glyphs each with kerning, built in
-  about a second, one process per size
-- the bundled Noto families on request, so a missing arrow or Greek letter is not
-  a hole in the page. Each lends its own bold or italic to a run set that way,
-  where it has one
-- Arabic comes out joined with any face, because the joining rules a modern one
-  stores are run here and the joined shapes built in, which the device has no
-  room to do for itself
-- nothing installed system wide, since the launcher fetches uv, Python and the
-  dependencies into a cache directory you can delete
-
-CrossGlyph turns TTF and OTF files into `.cpfont`, the format the device
-reads: glyph bitmaps at two bits per pixel, one file per point size, with
-kerning and ligature tables baked in. The device has no rasterizer, so every size is a
-separate build.
+- **The reader's own renderer.** The firmware's drawing code, compiled to run
+  in the browser, so the page shows what the device will draw and not an
+  impression of it.
+- **Controls for the letters.** How dark the type is (gamma, and the three grey
+  cut points), how thick or thin the strokes are (weight, and stem darkening),
+  a slant for a face with no italic of its own, how the outline is snapped onto
+  the pixel grid (hinting, grayscale hinting, and a one-bit mode that drops the
+  greys), the space between letters, words and lines, how hard pairs are pulled
+  together (kerning), whether `fi` joins into one shape (ligatures), and
+  whether digits are all one width. [docs/fonts.md](docs/fonts.md) explains
+  what every one of them does to the type.
+- **Controls for the page.** Margins, alignment, line and paragraph spacing,
+  hyphenation and the language its rules come from, anti-aliasing and night
+  mode, so the page you are judging is set up like the device you are judging
+  it for.
+- **The page inside the reader.** Drawn from XTEINK's own models, one screen
+  pixel to one of your monitor's, shaded to match a real device and adjustable
+  from there. One press copies it out as an image.
+- **Variable fonts.** These carry a range of weights in a single file. Build
+  one at the weight its designer named, or at any weight you pick. Left alone,
+  Merriweather would hand you its Light as your Regular.
+- **A family in seconds.** Regular, bold, italic and bold italic, at every
+  point size you asked for, one process per size.
+- **The bundled Noto faces on request**, so a missing arrow or Greek letter is
+  not a hole in the page. Each one lends its own bold or italic to text set
+  that way, where it has one.
+- **Arabic comes out joined** with any face. A modern Arabic font carries the
+  rules for how letters connect, and CrossGlyph runs them and builds the joined
+  shapes in. The device has no room to do that itself.
+- **Nothing installed system wide.** The launcher fetches uv, Python and the
+  dependencies into a cache directory you can delete.
+
+CrossGlyph turns TTF and OTF files into `.cpfont`, the format the device reads.
+A `.cpfont` holds a picture of every letter at one point size, in the four
+greys the screen has, along with the tables that space letter pairs and join
+`fi` into one shape. The device cannot scale type itself, so each point size is
+a separate file and a separate build.
 
 ## Quick start
 
@@ -134,13 +142,13 @@ fonts/
 `$CROSSGLYPH_FONTS` names another workspace, and so does `--fonts DIR`. Builds
 land in `cpfonts` unless `out` in `all.conf` says otherwise.
 
-A family needs no config at all. Drop four files in, name them the way their
-foundry did, and they build on the next run. `all.conf` holds settings shared
-by every family. It is yours and starts absent; copy `all.conf.example` beside
-it to start from a commented list of every key. Write a `<family>.conf` when
-one family needs settings the others do not. See
-[docs/fonts.md](docs/fonts.md) for every key, and for what the tuning controls
-actually do.
+A family needs no config at all. Drop the regular, bold, italic and bold italic
+files in, name them the way their foundry did, and they build on the next run.
+`all.conf` holds settings shared by every family. It is yours and starts
+absent; copy `all.conf.example` beside it to start from a commented list of
+every key. Write a `<family>.conf` when one family needs settings the others do
+not. See [docs/fonts.md](docs/fonts.md) for every key, and for what the tuning
+controls actually do.
 
 ## Getting the fonts onto the device
 
@@ -153,10 +161,11 @@ offers three of them.
 
 ## Fallback faces
 
-CrossPoint draws nothing for a codepoint no font in the chain has, so a family
-that lacks an arrow leaves a gap where it should be. The bundled Noto faces fill
-those holes, covering Hebrew, Arabic, Thai, Bengali, Armenian, Georgian,
-Ethiopic, Cherokee, Tifinagh, Coptic, mathematics, symbols and emoji.
+A codepoint is one character as the computer stores it, and CrossPoint draws
+nothing at all for one that no font in the chain has. A family with no arrow in
+it leaves a gap where the arrow should be. The bundled Noto faces fill those
+gaps, covering Hebrew, Arabic, Thai, Bengali, Armenian, Georgian, Ethiopic,
+Cherokee, Tifinagh, Coptic, mathematics, symbols and emoji.
 
 They are OFL licensed and unmodified, so they are downloaded on request and
 not shipped here:
@@ -165,16 +174,17 @@ not shipped here:
 ./crossglyph.sh fetch-fallbacks
 ```
 
-That is 3.4 MB, and it puts `OFL.txt` beside them. A CJK face is another
-15.7 MB and comes only when something has asked for it: a config naming a CJK
-script, or, in the preview, text on the page that cannot be drawn without one.
-One face answers all four languages, Korean included, so there is no choice to
-make between them.
+That is a few megabytes, and it puts `OFL.txt` beside them. The face for
+Chinese, Japanese and Korean is a much larger download on its own, and it comes
+only when something has asked for it: a config naming one of those scripts, or,
+in the preview, text on the page that cannot be drawn without it. That one face
+covers Chinese in both its written forms, Japanese and Korean, so there is no
+choice to make between them.
 
 The preview offers the same download as a button, with a bar, since it takes a
 while. Bundled fallbacks are off by default, which keeps a first build
-self-contained and makes a narrow face about twelve times smaller. After
-fetching them, turn on **bundled fallback faces** in the preview or set
+self-contained and makes a narrow face a fraction of the size. After fetching
+them, turn on **bundled fallback faces** in the preview or set
 `fallbacks = yes` in a config to fill codepoints the family lacks.
 
 ## What is here

docs/docker.md

@@ -5,15 +5,16 @@ on the host. The container can read and write one mounted workspace. That
 folder holds the source fonts, configuration files, downloaded fallback faces
 and built `.cpfont` families.
 
-The preview has no authentication. The supplied Compose service publishes it
-on `127.0.0.1` so that only the Docker host can open it.
+The preview has no login. Anyone who can reach the address can retune a
+family, save a config and start a build, so the supplied Compose service
+publishes it on `127.0.0.1` and only the Docker host can open it.
 
 ## Command cheat sheet
 
 Run every command from the folder that contains `compose.yaml`. That can be a
 Git checkout or an unpacked release ZIP.
 
-| Folder | `docker compose` uses | Local build context |
+| Folder | `docker compose` uses | What `--local` builds from |
 |---|---|---|
 | Git checkout | `ghcr.io/crazycoder/crossglyph:latest` | Current checkout |
 | Unpacked release | Image tagged with the release version | `versions/<release>` |
@@ -45,6 +46,10 @@ running CrossGlyph directly instead.
 
 ### Run Compose directly
 
+Compose is the part of Docker that reads a `compose.yaml` file and runs what
+it describes. CrossGlyph ships those files, so the commands below work as
+printed from the folder that holds them.
+
 To use the published image:
 
 ```sh
@@ -124,9 +129,9 @@ of this cleanup.
 
 ## Run builds and other commands
 
-The image entrypoint is `crossglyph`. A command after the Compose service name
-replaces the default preview command while keeping the workspace mount and the
-container restrictions.
+Everything in the image runs `crossglyph`, so a word after the Compose service
+name is a CrossGlyph command. It replaces the default preview command and keeps
+the mounted workspace and the container restrictions.
 
 ```sh
 docker compose run --rm crossglyph build
@@ -204,11 +209,11 @@ docker run --rm \
 
 ## Update the image
 
-The preview checks the release manifest at startup and when you press
-**Check now**. If the selected image is behind, the version row names the
-release and says to pull the new image. The check state stays in the
-container's private temporary filesystem rather than adding a file to the
-mounted workspace.
+The preview checks `latest.json`, the small file on the web that names the
+newest release, at startup and when you press **Check now**. If the selected
+image is behind, the version row names the release and says to pull the new
+image. The check state stays in the container's private temporary filesystem
+rather than adding a file to the mounted workspace.
 
 An installed ZIP defaults to its own version so native and container launches
 run the same code. Set `CROSSGLYPH_TAG` in `.env` to move a container-only
@@ -230,7 +235,8 @@ deployment settings in `.env` so the managed Compose files can update without
 a conflict.
 
 Published images support `linux/amd64` and `linux/arm64`. Each release also
-carries build provenance and an SBOM in the GitHub Container Registry.
+carries build provenance in the GitHub Container Registry, along with an SBOM,
+which is a list of everything that went into the image.
 
 ## Security boundary
 
@@ -248,7 +254,4 @@ login, and its save and build endpoints write to the workspace. Put an
 authenticated TLS reverse proxy in front of CrossGlyph before making it
 available on another machine.
 
-The bind mount is the current input and output path. A future upload and
-download interface can use the same `/workspace` contract with a Docker volume
-instead of a host folder. That change does not require another image entrypoint
-or another internal storage layout.
+The mounted folder is the only way fonts get in and builds get out.