explico 0.6.0 → 0.8.0

package/docs/authoring/migrating.md

@@ -33,6 +33,510 @@ required config block throws with the section of this file to read.
 
 ---
 
+## 0.7.0 → 0.8.0
+
+### 1. Rule N17 is inverted: delimiters are sized by the engine (`\left`/`\right` everywhere)
+
+The engine now installs its own KaTeX delimiter sizing, so a `\left … \right`
+pair is always strictly taller than its content and a nest shows its depth
+without help. Hand-picking `\bigl` → `\Bigl` → `\biggl` → `\Biggl` outward —
+which rule N17 previously *required* — is now the thing the linter warns about.
+
+**There is no install step.** `astro.config.mjs` already imports
+`explico/reference/katex-options.mjs`, and that module now imports
+`explico/reference/katex-delimiters.mjs` for its side effect. Confirm the import
+is still there; a course that inlined its own KaTeX options object instead must
+add, as the **first** import in `astro.config.mjs`:
+
+```js
+import 'explico/reference/katex-delimiters.mjs';
+```
+
+Order matters: the installer moves KaTeX's render entry points onto the shared
+`katex` object, so anything that renders math before the import would keep stock
+spacing. It refuses to fail quietly — it renders a known nest at install time and
+throws if the sizes did not grow.
+
+Two course-side conditions make the build throw, both with an explicit message:
+
+- **A `patches/katex@*.patch` file that already applies a negative
+  `\delimitershortfall`.** Delete the patch and its `pnpm.patchedDependencies`
+  entry; the engine does this in code now, and a patch is project-local anyway
+  so it never reached a consumer.
+- **A `katex` whose bundle no longer holds the constant where the engine looks
+  for it.** The rewrite targets one line in KaTeX's ESM bundle, so keep `katex`
+  on the declared peer version (`0.16.47`). An upgrade that moves or reformats
+  that line fails the build asking you to re-derive the change against
+  [`../katex-bracket-scaling.md`](../katex-bracket-scaling.md), which is
+  shipped in the package. The failure is loud and immediate, not a silent
+  return to stock spacing.
+
+### 2. Diagnostic renamed: `delimiter-size-hierarchy` → `delimiter-manual-size`
+
+The old code string no longer exists. Update every place that names it:
+
+- `lint-ignore.yml` — a stale line is inert and silently stops suppressing.
+- Course scripts, tests, and type narrowings over the diagnostic union;
+  `astro check` flags a comparison against a non-member.
+
+Its payload changed shape too. A consumer reading the fields, rather than just
+the `code` and `message`, needs this edit:
+
+```diff
+-// outerSize / nestedSize described the mismatch between two levels
+-const found = diagnostic.outerSize;
+-const suggested = diagnostic.suggestion?.size;
++// `size` is the hand-picked size found; `suggestion` is always present and is
++// always a \left/\right pair, so it no longer carries a `size` of its own.
++const found = diagnostic.size;
++const suggested = diagnostic.suggestion.latex;
+```
+
+`DelimiterSizeSuggestion` keeps `open`, `close`, and `latex`, and drops `size`.
+`DelimiterSizeDiagnostic` drops `outerSize` and `nestedSize`, gains a required
+`size`, and `suggestion` is no longer optional.
+
+### 3. Content: hand-sized nests now warn
+
+Math that was N17-compliant under 0.7.0 reports one `delimiter-manual-size`
+finding per hand-sized level. This is a Tier-3 warning — it does not fail a
+build — so it can be worked through at your own pace, but the findings are real
+and the repair improves the rendering.
+
+Find them with:
+
+```
+pnpm content warnings --json
+```
+
+The repair is mechanical: replace the hand-picked pair with `\left`/`\right`,
+keeping the delimiter shapes.
+
+```diff
+-\Biggl[a+\biggl(b+\Bigl[c+\left(d+e\right)\Bigr]\biggr)\Biggr]
++\left[a+\left(b+\left[c+\left(d+e\right)\right]\right)\right]
+```
+
+A **lone** hand-sized pair that is not part of a nest — `\bigl(x,\ y\bigr)`
+around a tuple, for instance — is a single-level typographic choice with no
+hierarchy to get wrong, and is deliberately left alone. Do not convert those.
+
+Expect a small visual change everywhere a nest is rendered: each level is now
+strictly larger than the one inside it, so outer delimiters grow by roughly one
+size step. A course holding screenshot or bounding-box baselines over math
+should re-record them.
+
+### 4. Manifest schema is now v16: a math diagnostic can name its equation
+
+`MANIFEST_SCHEMA_VERSION` is 16 (v15 → v16). The bump is **additive** — nothing
+existing changed shape — so the only required edit is to a client that asserts
+the number by exact equality, which now expects 16.
+
+What was added: a finding the math gate reports from a `$$…$$` block carrying a
+`\label{eq:…}` gains an optional `equation` field, `{ key, href }`. `href` is
+the rendered page's anchor for that equation
+(`/l1-ar/ar1-basics/#eq-ar1-variance`). `CliDiagnostic` carries the same
+optional field, so a course's own `scripts/content.ts` picks it up with no
+change.
+
+`diagnosticLine()` now appends it, so console output, the run log, and
+`pnpm content diagnostics` read:
+
+```
+[code] file:line:column: message (eq:<key> -> <href>)
+```
+
+A course script that parses that line with an anchored regex must tolerate the
+optional trailing ` (eq:… -> …)`. One that just prints the string needs nothing.
+
+### 5. Diagnostic line numbers are corrected — re-record anything that stored them
+
+Every gate scans the lesson body, which Astro hands over with the frontmatter
+already stripped, but findings are reported against the lesson *file* — so every
+`file:line:column` the engine has emitted for a lesson was short by the height
+of that lesson's frontmatter. `gate-math` (every `delimiter-manual-size`
+column), `gate-prose-notation` (rule N9), `gate-abbreviations` (rule N14), and
+`gate-heading-length` (S1) are all corrected at once.
+
+Nothing to edit in content, but line numbers move, so:
+
+- Re-check any suppression, snapshot, or problem matcher keyed to a line number.
+  Line numbers were wrong before; they now point at the real line.
+- `pnpm validate:content` (twice) regenerates `build/resolution/*` with the
+  corrected positions. Commit the result.
+
+### 6. Malformed `\explain` / `\slot` keys now fail the build
+
+Previously a key that did not match the notation key pattern —
+`\explain{Not A Key}{\Omega}` — was not a KaTeX parse error: KaTeX rendered the
+command name in its error color and carried on, so the page shipped red
+`\htmlData` text with a green build. `renderNotationMath` now checks both marker
+macros before KaTeX runs and throws, naming the offending key.
+
+**This can newly fail a build that passed on 0.7.0.** If it does, the page was
+already broken for readers. Fix the key to match the notation key pattern
+(lower-case, hyphen-separated) and make sure it resolves to a real entry.
+`renderNotationFormula` still degrades to inert-but-correct math rather than
+costing a reader the equation.
+
+### 7. Glossary entry heading markup: the anchor is now a sibling of the `<h2>`
+
+The per-entry anchor link moved out of the `<h2>` and into a new
+`.glossary-heading` flex row wrapping both — the same shape
+`rehype-heading-anchors` gives a lesson heading. This restores the heading's
+accessible name (a screen reader was announcing "Velocity Link to Velocity").
+
+Nothing visual changed, but update course-owned CSS and end-to-end tests that
+assumed the nesting:
+
+```diff
+-h2:hover .glossary-anchor,
+-h2:focus-within .glossary-anchor {
++.glossary-heading:hover .glossary-anchor,
++.glossary-heading:focus-within .glossary-anchor {
+```
+
+A test locating the anchor as a descendant of the heading must target
+`.glossary-heading .glossary-anchor` instead. A check for the heading *by
+accessible name* now matches the term alone, which is the point of the fix — if
+such a test was written against the broken name ("Velocity Link to Velocity"),
+it needs the term.
+
+### 8. The About panel publishes its versions as data attributes
+
+Additive; no course edit is required. `details[data-about-panel]` now carries
+`data-knowledge-version`, `data-knowledge-date` (omitted when the content
+changelog has no date), and `data-engine-version`, and the rendered version line
+is marked `data-knowledge-line`.
+
+This exists so a build check does not have to match prose. A course asserting
+the panel's contents by text is pinned to one version string and turns every
+routine bump into a test edit — this repo's own `about.spec.ts` was asserting
+`0.4.0` against a playground long since past it. Prefer:
+
+```diff
+-await expect(panel).toContainText('0.6.0');
++await expect(panel).toHaveAttribute('data-knowledge-version', knowledgeVersion);
+```
+
+reading the expected value from `content/course.config.ts` rather than hard-coding
+it. A bare version substring is not scoped to the panel either — the engine
+version printed one row below can satisfy it.
+
+### 9. Fixes that need no action
+
+These remove build failures; they never require a content edit. Formulas you
+previously worked around may now be written directly.
+
+- **A notation `formula` can use a manual delimiter size, an accent, a box, or
+  a color.** `render-notation-math.ts`'s attribute allowlist is now KaTeX's
+  whole inert presentation surface, so `\Bigl`/`\biggl`/`\Biggl`,
+  `\xrightarrow`, `\boxed`, and `\colorbox` no longer throw
+  `Unexpected KaTeX property`. `alt`, `href`, `src`, and `title` are explicitly
+  denied; no attribute that can carry a URL is allowed through.
+- **`\vec` and every other accent renders.** The style sanitizer no longer
+  requires a trailing `;` on the last CSS declaration. `\mathbf` remains the
+  house style for a vector; `\vec` simply works now.
+- **A macro in a formula no longer invents a source span.** `\vdots`,
+  `\varSigma`, `\argmax`, `\bmod`, `\R`/`\N`/`\Z` and 79 of KaTeX's 282 macros
+  produce nodes whose `loc` indexes the macro body, which the glyph resolver
+  read as a span over unrelated text — failing with `Unresolved notation ""`,
+  or worse, silently splitting a formula mid-command. Fixed. An existing
+  explicit `\explain{key}{\varSigma}` annotation still works and is still the
+  way to bind a macro-expanded glyph, since it has no authored span for
+  canonical matching to see.
+- **`equationAnchorId({ key })` type-checks without a `number`.** Its JSDoc
+  required a property the function ignores when a `key` is given.
+
+### 10. Verify
+
+```
+pnpm add -D explico@0.8.0
+pnpm validate:content   # twice — the first run regenerates build/resolution/*
+pnpm content check --changed
+pnpm content warnings   # expect new delimiter-manual-size findings (item 3)
+astro check
+astro build
+```
+
+Commit the regenerated `build/resolution/*` (items 4 and 5 both change it).
+
+## 0.6.0 → 0.7.0
+
+### 1. Manifest schema is now v15: diagnostic severity has three levels
+
+`MANIFEST_SCHEMA_VERSION` is 15 (v14 → v15). Public diagnostic severity unions
+now include `info`, so a client that treated "not an error" as "a warning"
+needs three edits:
+
+1. A client asserting `MANIFEST_SCHEMA_VERSION` by exact equality expects 15.
+2. Widen any hand-written `'error' | 'warning'` type over manifest diagnostics
+   to `'error' | 'warning' | 'info'`. `ConsistencyDiagnostic.severity` is now
+   `'warning' | 'info'`.
+3. In `scripts/compile-manifest.ts` (and any other consumer), filter on
+   `severity === 'warning'` before printing or counting warnings. A script that
+   counts all of `manifest.diagnostics.consistency` as "Tier-3 findings" now
+   over-reports:
+
+```diff
+-const consistencyByCode = consistencyCounts(consistency);
+-const consistencyTotal = consistency.length;
++const consistencyWarnings = consistency.filter(
++  (diagnostic) => diagnostic.severity === 'warning',
++);
++const consistencyByCode = consistencyCounts(consistencyWarnings);
++const consistencyTotal = consistencyWarnings.length;
+```
+
+These codes moved from `warning` to `info`: `eq-key-unused`, every keyed-float
+`*-key-unused`, `unused-definition`, `weak-local`, `gloss-wants-promoting`, and
+`card-wants-demoting`. Their code strings and container fields did not change,
+the `lint-ignore.yml` lines that already worked for `weak-local`,
+`gloss-wants-promoting`, and `card-wants-demoting` still match, and nothing
+blocks the build. They no longer appear in `pnpm content warnings`; read them
+with `pnpm content diagnostics info`.
+
+Run `pnpm validate:content` twice. The committed `build/resolution/*` files
+(including `consistency-report.json`) change because those findings now carry
+`info` severity and `numerals-tagged` findings are gone (item 2); commit them.
+
+### 2. Retired diagnostic: `numerals-tagged`
+
+`ConsistencyCode` no longer contains `numerals-tagged`, and the engine never
+emits it. Delete every `numerals-tagged` line from `lint-ignore.yml` (a stale
+line is inert but misleads the next reader) and every course script, test, or
+type narrowing that names the code — `tsc`/`astro check` flags the latter as a
+comparison against a non-member of the union.
+
+### 3. `explicoContentRefresh()` fails the build on a missing remark plugin (rule N14 and its siblings)
+
+This is the enforcement half of rule N14's Astro wiring (see item 4 of the
+0.4.x → 0.5.0 section). Its `astro:config:setup` hook now compares the manifest
+against the configured remark plugins and throws, naming each gap, when a
+non-empty table has no matching plugin registered:
+
+| Manifest table is non-empty | Plugin that must be registered |
+| --- | --- |
+| `manifest.abbreviations` | `[remarkAbbreviations, { abbreviations: manifest.abbreviations }]` from `explico/reference/remark-abbreviations.mjs` |
+| `manifest.sources` | `[remarkCitation, { sources: manifest.sources }]` from `explico/reference/remark-citation.mjs` |
+| `manifest.notation.raw` | `[remarkNotation, createRemarkNotationOptions(manifest)]` from `explico/reference/remark-notation.mjs` |
+
+Check `astro.config.mjs` against that table. The check reads both wiring
+surfaces Astro offers — the flat `markdown.remarkPlugins` array and a
+`markdown.processor` such as `unified({ remarkPlugins: [...] })` — and accepts
+either the bare plugin or a `[plugin, options]` tuple. It compares by identity
+with the module the `explico/reference/*.mjs` specifier resolves to, so register
+the imported function itself rather than a local wrapper around it. A course
+that was already fully wired needs no edit; one that skipped a plugin was
+silently rendering triggers as plain text and now fails `astro build` /
+`astro dev` until it adds the missing registration.
+
+### 4. Removed markup: popup "Copy LaTeX", glossary `#` copy-link, formula scroll region
+
+None of these has a replacement selector; update course-owned CSS and
+end-to-end tests that target them:
+
+- `.notation-popup-copy` / `[data-popup-copy]` — the button in a notation
+  popup. Copying is now a click on the equation itself (item 8).
+- `[data-glossary-anchor]` and its "Link copied" flash — a glossary entry's `#`
+  button that wrote its URL to the clipboard. The entry title is now a link to
+  `#notation-<key>` (`.glossary-term-link`), and a hover-revealed link-icon
+  anchor (`.glossary-anchor`) simply navigates; nothing is copied.
+- `NotationFormula`'s `tabindex="0"` scroll region moved from
+  `.notation-formula-math` to a nested `.notation-formula-scroll`. A test that
+  focuses or scrolls `.notation-formula-math` must target the inner element.
+
+No source or config change is needed beyond selectors.
+
+### 5. Rule N14: every occurrence of a catalogued abbreviation is now wrapped
+
+Two changes ride under rule N14, neither of which needs a config edit:
+
+- **Rendered output changed.** `remarkAbbreviations` used to wrap only the first
+  occurrence of each catalogued abbreviation per page; it now wraps every
+  occurrence (`a.abbreviation-term[data-abbr-key]`). A course-owned e2e test or
+  snapshot that expected exactly one such link per term per page, or CSS that
+  assumed a page's later occurrences were plain text, must be updated.
+  `AbbreviationLayer.astro` already resolved markers independently by
+  `data-abbr-key`, so no island change is needed.
+- **The shipped baseline grew** (`base-abbreviations.mjs`): `AM`, `PM`, `A.M.`,
+  `P.M.`, and `e.t.c.` join `a.m.`, `p.m.`, `e.g.`, `i.e.`, and `etc.`. This only
+  loosens the gate. A now-redundant `abbreviations.allow` line or
+  `content/abbreviations/*.md` entry for one of them is harmless and can stay; a
+  course that wants one explained anyway lists it in `abbreviations.deny`.
+
+### 6. Rule N16 and rule N17: delimiter conventions and sizes
+
+Rule N16 (alternate `()`, `[]`, `\{\}` for purely stylistic nested grouping,
+never for conventional delimiters such as `f(x)`, `\mathbb{E}[X]`, or
+intervals) is **review-only**: nothing checks it and nothing needs to change to
+keep building. Rule N17 (every outer scalable pair in a nest grows strictly
+larger than the pairs inside it: `\left…\right` → `\Bigl…\Bigr` → `\biggl…\biggr`
+→ `\Biggl…\Biggr`) is a **Tier-3 warning**, `delimiter-size-hierarchy`, reported
+at the outer pair's line and column by the normal math gate for lesson math,
+notation formulas, and assessment math. It never fails a build, so no course
+needs to change to keep building. To clear the warnings, run
+`pnpm content diagnostics warning`, and enlarge each named outer pair to the
+next manual size without changing its delimiter shape. Rule N15's build-enforced
+behavior is unchanged — its documentation now also accepts an N17 manual pair as
+"sized". See [`notation.md#n16`](notation.md#n16) and
+[`notation.md#n17`](notation.md#n17).
+
+### 7. Rule P1: "or" never introduces a second name for the same thing
+
+Rule P1 opens the new `P` (prose) rule area and is **review-only**: nothing is
+checked at build time and no course change is required. When editing lessons,
+replace "the residual or error term" with "the residual (i.e., the error
+term)"-style wording. See [`prose.md#p1`](prose.md#p1).
+
+### 8. Optional: click-to-copy equations, glossary equation numbers, and live lab LaTeX
+
+Nothing to do for a course that wires `Footer` to `LessonFooter.astro`: a
+click on any `[data-notation-formula]` box now copies its `data-latex`, and every
+glossary formula gets a `G.<n>` number and copy button, automatically.
+
+Only a course with an interactive lab island that renders math through
+`renderLabMath()` can opt that equation into the gesture, and keep the copied
+LaTeX in step with the sliders, with `plainLatexTemplate` and the new
+`slotPlaceholder` export:
+
+```tsx
+import {
+  slotPlaceholder,
+  type RenderedLabMath,
+} from 'explico/reference/render-lab-math';
+
+// On the math root element:
+<div
+  className="lab-math"
+  data-notation-formula
+  data-latex={rendered.plainLatexTemplate}
+  /* … */
+/>
+
+// Where the island writes each slot's live value (`values`: slot name → text):
+let latex = rendered.plainLatexTemplate;
+for (const [name, value] of Object.entries(values)) {
+  latex = latex.split(slotPlaceholder(name)).join(value);
+}
+root.dataset.latex = latex;
+```
+
+Rebuild `latex` from the template on every update, not from the previous result.
+A lab that does not set these attributes is unchanged. `RenderedLabMath` gained
+the required `plainLatexTemplate` field; a course that constructs one by hand
+(a test double, for instance) must add it.
+
+### 9. Only if you override `Footer` yourself: mount `AnchorScrollEnhancer`
+
+The new smooth-scroll behavior for in-page anchor links ships in
+`AnchorScrollEnhancer.astro`, which `LessonFooter.astro` mounts. A course whose
+Starlight `components.Footer` is `explico/components/starlight/LessonFooter.astro`
+gets it with no change. A course that swapped in its own footer component must
+render it (`import AnchorScrollEnhancer from
+'explico/components/starlight/AnchorScrollEnhancer.astro'`, then
+`<AnchorScrollEnhancer />`) or its anchor links keep the browser's native jump.
+
+### 10. Optional: wire `rehypeBaseLinks` for a course deployed under a subpath
+
+Skip this for a course served from a domain root (`base` omitted or `'/'`); the
+plugin is a no-op there. For a course under a subpath (a GitHub Pages *project*
+site, `base: '/my-course'`), Starlight prefixes only its own navigation, so
+every root-relative link the Markdown pipeline produces — prose links,
+equation cross-references, citation links — 404s without this:
+
+```diff
++ import rehypeBaseLinks from 'explico/reference/rehype-base-links.mjs';
+  …
+  rehypePlugins: [
+    [rehypeKatex, createNotationKatexOptions()],
+    rehypeFailKatexErrors,
++   [rehypeBaseLinks, base],
+  ]
+```
+
+`base` is the same value passed to `defineConfig({ base })`. **Undo any manual
+workaround first:** the plugin prefixes every `href` beginning with a single
+`/`, so a lesson link already hand-written as `/my-course/other/` would become
+`/my-course/my-course/other/`. Write lesson links without the base. A lesson's
+Starlight frontmatter (`hero.actions[].link`) never passes through this
+pipeline; write those as paths relative to the current page.
+
+### 11. Optional: run logs for `pnpm validate:content`
+
+Route the course's `scripts/compile-manifest.ts` through `createRunLog()` to
+record every diagnostic to `build/logs/<timestamp>/{error,warning,info}.log`
+(Python `logging` format, `build/logs/latest` symlinks the newest run):
+
+```diff
++ import { createRunLog } from 'explico/compiler/logging';
+  …
++ const log = createRunLog();
+  const manifest = await compileManifest(courseConfig);
+  …
+- console.warn(`[${warning.code}] ${warning.message}`);
++ console.warn(log.warning('notation', `[${warning.code}] ${warning.message}`));
+  …
++ const summary = log.close();
++ console.log(
++   `Run log: ${summary.relativeDirectory} ` +
++     `(${summary.counts.ERROR} error(s), ${summary.counts.WARNING} warning(s), ${summary.counts.INFO} info).`,
++ );
+```
+
+Each `log.error/warning/info(source, message)` call returns its message, so
+printing and recording share one expression; `log.infoDiagnostics(manifest.diagnostics)`
+records the severity-`info` findings the console never showed. Call
+`log.close()` before any `throw` so a failing run's log is complete
+(`playground/scripts/compile-manifest.ts` is a full worked example). Add
+`build/logs/` to the course's `.gitignore` — a course commits
+`build/resolution/*`, and nothing prunes old runs.
+
+### 12. Optional: the `content diagnostics` / `content warnings` commands and VS Code tasks
+
+`content diagnostics [info|warning|error] [--json]` and `content warnings
+[--json]` are new, and `content status` now reports an `info` count
+(`report.diagnostics.infos`). The engine implements them in
+`explico/compiler/cli`, but a course's own `scripts/content.ts` dispatches
+commands, so it must route them:
+
+```diff
+  import {
+    ContentCliError,
+    contentCheck,
+    contentContext,
++   contentDiagnostics,
+    contentStatus,
++   contentWarnings,
+    …
+  } from 'explico/compiler/cli';
+```
+
+Add a `case 'warnings'` (`contentWarnings(manifest)`) and a `case 'diagnostics'`
+(validate the one positional as `info`/`warning`/`error`, default `info`, then
+`contentDiagnostics(manifest, severity)`) beside `case 'status'`, printing
+`file:line:column: severity code: message` lines — copy
+`playground/scripts/content.ts`. To surface findings in VS Code's Problems
+panel, copy the three **Explico: Show content diagnostics** tasks from the
+engine repository's `.vscode/tasks.json`, replacing the `--filter` package name
+and the problem matcher's `fileLocation` root with the course's own.
+
+### 13. No action: other changes in this release
+
+- Every `<a>` back-link (`↩`) in a page's References section now also carries a
+  `title` tooltip; `remark-citation.mjs` does this itself.
+- Standalone HTML export now inlines a `<link>` only when its `rel` is
+  `stylesheet` or an icon type, and leaves other `<link>`s (`canonical`,
+  `alternate`, `preload`, …) as authored.
+
+### Verification
+
+`pnpm validate:content` (run it **twice** — the first run regenerates
+`build/resolution/*`, item 1), then `pnpm content check --changed`, then
+`astro check`, then `astro build`. `astro build` is the step that reports item 3.
+
+---
+
 ## 0.5.0 → 0.6.0
 
 ### 1. Rule S1: no heading or float title runs past 65 characters
@@ -215,6 +719,16 @@ abbreviation needs its remark plugin wired in too:
   ]
 ```
 
+Skipping this second half is now **build-enforced**, not just documented:
+`explicoContentRefresh()`'s `astro:config:setup` hook checks
+`markdown.remarkPlugins` against the manifest and throws if a catalogued
+manifest table (`manifest.abbreviations`, `manifest.sources`, or
+`manifest.notation.raw`) has no matching plugin (`remarkAbbreviations`,
+`remarkCitation`, `remarkNotation` respectively) registered — so a
+half-completed migration like this one fails `astro build`/`astro dev`
+instead of silently rendering plain text with `pnpm validate:content` still
+green.
+
 ### 5. Optional: rule N10 warns on an unexplained `\mathrm{…}` label
 
 A `\mathrm{…}` multi-letter label (`\mathrm{KE}`, `\mathrm{PV}`) not on the