pdfmd-cli 3.29.36__tar.gz → 3.31.46__tar.gz

{pdfmd_cli-3.29.36 → pdfmd_cli-3.31.46}/CHANGELOG.md

@@ -2,42 +2,1532 @@
 
 Newest first. Versions follow semver loosely: a **major** bump changes
 behavior in a way that could surprise an existing user (a default flips, a
-flag's meaning changes), a **minor** bump adds a capability, a **patch**
-bump fixes a bug without changing what any flag does.
+flag's meaning changes). One **minor** bump (`3.N.0`) opens a feature line,
+however large it is; every change after it in that line is a **patch**
+(`3.N.x`), whatever it adds, so the version count stays small.
 
-The version string lives in one place, `pdfmd.py`, right after the module
-docstring:
+The version string lives in one place, the `PDFMD_VERSION` line of `pdfmd.py`
+(a little below its module docstring; `pyproject.toml` and the publish workflow
+read it from there):
 
 ```python
 PDFMD_VERSION = "2.0.0"
 ```
 
 `pdfmd --version` prints it. Bump it there and add an entry here in the
-same edit.
-
-<!--
-## Why this starts at 2.0.0, not 1.0.0
-
-`pdfmd.py` began as a one-line `pandoc file.md -o file.pdf` wrapper and was
-revised many times since — across ChatGPT, ChatGPT Codex, Claude Chat,
-Cowork, and Claude Code sessions — with no version marker or changelog kept
-at any point. `backups/pdfmd.py.bak-*` has snapshots from a handful of
-points in that history, but not from the ChatGPT/Codex/Cowork era at all,
-so reconstructing an honest "v1.x" changelog from what's actually on disk
-isn't possible — only a partial, misleadingly-precise-looking one. Decided
-2026-09-16 (the author): start real changelog tracking now, at 2.0.0, rather than
-fabricate the gap. If the full history ever matters, it would need pulling
-the actual chat transcripts from each of those tools, not guessing from
-diffs between inconsistent backup snapshots.
-
-**Update, 2026-10-05:** an approximate outline of the earlier history has
-since been reconstructed, at the very end of this file (see "Before 2.0.0 —
-reconstructed history"), from the saved Codex transcripts and the surviving
-backup snapshots. It is explicitly NOT reliable: its 1.x numbers are
-invented, snapshot-based entries cover windows of days rather than single
-changes, and anything done in unsaved sessions (other ChatGPT chats,
-claude.ai, Cowork) is missing. Real tracking still begins at 2.0.0.
--->
+same commit as the change.
+
+---
+
+## v3.31.46c — 2026-11-02
+
+Pre-edit state: commit `119003b`. No shipped code changes (tests only), so no version bump. The first push of the 3.31.4x commits showed what the CI saw and the machine of the author did not.
+
+Lint and Windows, which kept `Test and publish` from releasing.
+
+- `ruff check --select F` (the `lint` job) found five unused or redefined imports in `test_build_log`, `test_diagram_shim` and `test_kit_selection`; removed.
+- Windows: `test_display_path` expected the temporary folder to be written absolute, but there it lies below the home folder, where the `auto` style writes `~`: the test asks for the `relative` style. `test_kits`: `/one/place` has no drive on Windows (the test uses an absolute path of its own folder), and the cache of the kit lookup is in `LOCALAPPDATA` there, not `XDG_CACHE_HOME`.
+
+## v3.31.46b — 2026-11-02
+
+Pre-edit state: commit `63d353d`. No shipped code changes (tests only), so no version bump.
+
+Five test modules no longer depend on the machine they run on.
+
+- Without Pandoc on the PATH, `test_build_log`, `test_build_time` and `test_path_display` ran real builds and failed (20 tests); they are skipped now, as the other modules that need Pandoc are. `test_table_widths` crashed when it was imported, reading Pandoc's version for a decorator; with no Pandoc it reads `(0,)` and its tests are skipped.
+- `test_diagrams` gives the pdfmd it starts an empty data folder (`XDG_DATA_HOME`, `LOCALAPPDATA`): the diagram tools that `pdfmd --install diagram` keeps there are on pdfmd's own PATH, and on a machine that had installed them two tests (a missing tool, the doctor's "nothing installed") found a `dot` that the test had taken away.
+
+## v3.31.46 — 2026-11-02
+
+Pre-edit state: commit `2a63449`. Still under 3.31 [tables]. Entry 3dy (the author's wish, 2026-10-31, with the answers of 2026-11-01/02).
+
+A caption typed by hand next to a table can be the table's caption.
+
+- `pdfmd_lua/table_caption.lua` (new, a Pandoc filter, so gfm and Pandoc Markdown alike): a paragraph that is entirely one bold span starting with a label word (`**Table 1: Results**`), right above a table without a caption (or else right below one; above wins), becomes its caption. The label and number are cut off (the engine numbers the table), the rest keeps its markup, a trailing `{#tbl:id}` becomes the table's id when it has none. A paragraph or heading between them, a bold line that is not alone in its paragraph, or a table that already has a caption: left alone. The number of blank lines does not matter.
+- The label words come from `pdfmd_tables/captions.py` (English always, then the document's `lang:`: de, fr, es, it, pt, nl, pl, cs, sv, da, no, fi, ro, hu, el, bg, ru, uk, kk, tr, ar, zh, ja, ko), then `table-caption-words`: data, not code.
+- Four `pdfmd-options` keys, each a `--setup` row (config and folder levels) and in the inventory: `table-captions` (`note`, the default: change nothing and say once, `NOTE  table-captions: N lines next to a table read like captions`; `on`; `off`), `table-caption-label` (`strip`, `keep`), `table-caption-need-label` (`on`; `off` takes any line that is one bold span, the author's "skip the label word" toggle) and `table-caption-colon-words` (0 = off, the author's "<= 2 words" sketch as a number: a gfm `: Results` of at most that many words is a caption too; Pandoc Markdown reads it by itself).
+- The filter is added to the Pandoc command only for a document with a line that could be a caption, and after the CSV, markup and page-break filters.
+- Tests: `tests/test_table_captions.py`.
+
+## v3.31.45 — 2026-11-01
+
+Pre-edit state: commit `f4cd293`. Still under 3.31. Entry 3eh (the author: "i suggest making it build @05,10, since both of them are introductions"; "yes, i want it done as 3.31").
+
+A part name that fits several top-level files with the same name builds all of them.
+
+- `report#introduction` (or `#intro`) with both `parts/05-introduction.md` and `parts/10-introduction.md` stopped with "is ambiguous: it matches parts in 05-introduction.md, 10-introduction.md". Top-level files that differ only in their numbers are one section in two files, so the name builds both, in document order. The error stays for what is really ambiguous: the same name in two different folders (`yield` in Calculations and Discussion), and a prefix that fits different names (`intro` with an `introduction` and an `introspection`). A number (`05`) or the full file name (`10-introduction`) still names one file.
+- Tests: `tests/test_sections.py` (`SameNameParts`). README: the example in the parts section.
+
+## v3.31.44 — 2026-11-01
+
+Pre-edit state: commit `c16091d`. Still under 3.31. Entry 3ef (the author's decision, with an example: the numbers of a part built alone are the numbers of the full build, names printing in the order they appear).
+
+A part built alone sees the calculator's names of the whole document, below it as well as above it.
+
+- Until now only the parts above the one built were evaluated (3.30.19), so a name defined in a later part was undefined in a part built alone, and the author had to build the Calculations part along with every part that prints its numbers. Now pdfmd reads the whole document with `calc.lua` alone (nothing typeset, about a second): the scaffold, then every part in order, a one-word paragraph `pdfmd-calc-mark-in` / `-out` around each part built. `calc.lua` writes (`-M pdfmd-calc-halves=FILE`) each name's last definition above the part built and its first definition below it, each evaluated in its own place, and the build reads them back, the first as before (`pdfmd-calc-seed`, standing above everything), the second as `pdfmd-calc-below` (standing after everything, so a name is taken from there only when nothing above or inside the part defines it). That is the full build's rule: the nearest definition above, else the first one below. With `x = 2` in the introduction, `y = x * 2` and then `x = 3` in the calculations, the procedure alone prints 2 and 4, the discussion alone 3 and 4, like the full build; the introduction alone, with every name below, works too.
+- Sections of a plain document (`doc#procedure`) too: the text above and below the sections chosen is read, each section marked. The NOTE says where the names came from: `NOTE  calc: 128 names taken from parts 10-50, 3 from parts 70-90 (defined below) (evaluated, not typeset)`. The same `seed-calc` setting (`auto`, `scan`, `off`) governs both halves; no new setting. The export file (`calc: {export:}`) of a part built alone still lists the names above it and inside it only.
+- KNOWN BUG, not fixed here (queued, entry 3eg): two parts built together that are not next to each other (`report#20+40`) take what the parts between them define as defined above both, so a number in part 20 can be the value a name gets only in part 30, silently. It was so before this version (the parts between were already read as "above"). Adjacent parts and sections are exact.
+- README (the paragraph on a part built alone), recipes 3.2, the `--seed-calc` help and its `--setup` row say the new rule. Tests: `tests/test_calc.py` (`NamesBelow`: the example above, the first part alone, the part's own definition winning, two parts side by side, `--seed-calc off`, a name that is nowhere, sections).
+
+## v3.31.43 — 2026-10-31
+
+Pre-edit state: commit `c32ad4b`. Still under 3.31. Entry 3ec (the author's answer: "rdkit's colouring is a fun feature, so keep it on"; first said black by default, then corrected to colour by default).
+
+The atom colours of a structure are a setting.
+
+- `palette` (`color`, `bw`; `pdfmd-options.smiles.palette`, a `palette=` attribute on a block, a `--setup` row under Chemical structures, a folder setting): `color` is RDKit's own colouring (O red, N blue, S yellow...) and the default; `bw` draws every atom black, as a chemfig drawing is. The palette is part of the picture's cache key, so changing it draws a new picture and never reuses the other. (Chemfig can colour with `\color` too, but looks worse: not built.)
+- Tests: `tests/test_smiles.py`.
+
+## v3.31.42b — 2026-10-31
+
+Pre-edit state: commit `bbce97f`. No shipped code changes (a formula, a workflow, a script, the README, a test), so no version bump. Entry 3ed (the author: no separate repositories; the tap moves here).
+
+The Homebrew formula lives in this repository.
+
+- `Formula/pdfmd.rb` is the formula of the `aliperdehan/homebrew-tap` repository (pandoc, typst, libyaml, python@3.13; pyyaml and pypdf pinned by hand). Install: `brew tap aliperdehan/pdfmd https://github.com/aliperdehan/pdfmd`, `brew trust aliperdehan/pdfmd`, `brew install aliperdehan/pdfmd/pdfmd`. The URL is needed because the repository is not named `homebrew-...`; checked with a throwaway tap, which brew clones as `homebrew-<name>`. Homebrew 7 refuses a formula of a tap that is not trusted (`Refusing to load formula ... from untrusted tap`), so the README gives `brew trust` as the step in between; there are no users of the old tap yet, so nothing needs migrating. The old repository is deleted by the author once the new install has worked from GitHub.
+- `scripts/bump_formula.py` points the formula's `url` and `sha256` at a release on PyPI (a version that PyPI does not list yet is asked for again, `--tries` times `--wait` seconds apart); only those two lines change, the pinned resources are tested to stay as they are.
+- `publish.yml` has a `homebrew` job, `environment: homebrew` (a Deployment of its own on the repository page, as `pypi` is), after the PyPI upload: bump, `brew audit --strict`, build from source, `brew test`, then a commit to `main`. A push made with `GITHUB_TOKEN` starts no workflow, so it does not run the tests again. It also runs when the version is already on PyPI (`workflow_dispatch` repairs a formula that fell behind); the tap's daily schedule is gone, the release replaces it. Not run on GitHub yet: the first real run is the first push after this commit.
+- Tests: `tests/test_formula.py`.
+
+## v3.31.42 — 2026-10-31
+
+Pre-edit state: commit `a609345`. Still under 3.31 (no minor before the tables are done). Entry 3ec (the author's wish: Obsidian draws SMILES through a plugin, pdfmd should draw the same notes). First slice of the `[smiles]` line.
+
+A chemical structure written as text is drawn as a picture.
+
+- `smiles` blocks, in the three spellings: a fenced ```` ```smiles ````, a fence with attributes ```` ```{.smiles caption="..." #fig:id} ````, and a `::: smiles` div (what Obsidian's chemistry plugins read, and what the calc blocks accept). A block is one structure per line, side by side (`per-row` to a row) under one caption; a name after the SMILES (`CCO ethanol`, the `.smi` convention) is written under that structure. `kind=` (`smiles`, `mol`, `mol2`, `inchi`, else read from the text or the file) and `file="x.mol"` (a file beside the document: `.mol`, `.sdf`, `.mol2`, `.smi`) are attributes of the block.
+- The div form reads the body back as it was typed: Pandoc takes the nitro group `[N+](=O)[O-]` for a link, and the filter puts the link back together (`pdfmd_lua/smiles.lua`).
+- Drawn by RDKit through `pdfmd_smiles`, one call of `python3 pdfmd_smiles` per document with pdfmd's own interpreter (RDKit is imported once; nothing is shelled to another Python). Every structure has the same bond length (`bond-length`), so a small molecule is not drawn large. Format by output: PDF for LaTeX (through `rsvg-convert`; PNG when there is none), SVG for HTML, EPUB and Typst, PNG for Word and OpenDocument (`office-format: svg` for SVG; Word 365 and LibreOffice read it, older Word, Google Docs and Pages do not), an SVG beside the output for flat Markdown (`--to gfm`, as diagrams are). A captioned block is a figure; `{#fig:id}` reaches pandoc-crossref.
+- The picture cache is keyed by everything that changes the picture: the engine and its version, the kind, the structures, the format, the cell size, the columns, the bond length, the dpi and the module's own version. The same block twice is drawn once; the same block with another engine, format or setting is a new picture, never a stale one. (The chemfig engine's compiled cache, `cache: {smiles}`, comes with that engine.)
+- A block that cannot be drawn (RDKit missing, a structure that does not read, a missing file, an unknown setting in the block) stays as code with one warning that says why; a wrong `pdfmd-options.smiles` stops the build and names the key.
+- Settings, all under one key, `pdfmd-options.smiles`, and every one also an attribute of a block (`columns=` for `per-row`): `engine` (`auto`, `rdkit`), `format` (`auto`, `svg`, `png`, `pdf`), `office-format` (`png`, `svg`), `cell-width` (250), `cell-height` (200), `per-row` (3), `bond-length` (40), `dpi` (300). The numbers are the author's to change, not constants: each is a `--setup` row (Chemical structures) and a folder setting.
+- `--no-auto smiles` leaves the blocks as code. `--doctor` says whether RDKit is installed.
+- A Markdown file with no front matter is read as gfm, which has neither the div nor code attributes: the note about what gfm leaves as plain text now also names a fence that opens with attributes (```` ```{.smiles caption=... } ````, ```` ```{.d2 ...} ````), as it names `:::` divs.
+- `CLAUDE.md` names the new `[smiles]` tag next to `[kits]` and `[tables]`.
+- `scripts/build_zipapp.py` lists `pdfmd_smiles` and, which it was missing since the kits line, `pdfmd_kits` (`tests/test_packaging.py` compares it with the wheel's list and was failing).
+- Tests: `tests/test_smiles.py` (settings, reading, drawing and the cache, no RDKit, builds through `pdfmd` itself).
+
+## v3.31.41 — 2026-10-31
+
+Pre-edit state: commit `437c3ef`. Still under 3.31 (no minor before the tables are done). Entry 3ea (the author's wish, from a `FOUND` line that printed the long path of a course folder's `.pdfmd/`).
+
+A path in a message is written as short as it can be, by a setting.
+
+- Cause: `display_path` wrote a path relative to the working folder only when it was under it, so a folder above it (a course folder's `.pdfmd/`, a shared metadata file) fell back to the absolute path.
+- `path-style` (`auto`, `relative`, `home`, `full`; `--path-style`, `options.path-style`, a `--setup` row under Messages). `auto` (the default): relative to the working folder, up to `path-up` `..` steps above it (`--path-up N`, `options.path-up`, a `--setup` row, default 2: the author's number, a setting and not a constant), else `~/...` under the home folder (the same on every system, `~\` separators on Windows), else absolute. `relative` is that without `~`, `home` is `~/...` whenever the file is under the home folder, `full` is `--full-paths`.
+- Both settings work at every level: the command line, the config file (`--setup`) and a folder's own settings (`pdfmd --setup DIR`, `.pdfmd/config.yaml`; the nearest folder wins, read at the first document of the run, as the style is one for the whole run). They are not `pdfmd-options` keys of a document.
+- `--verbose` and `--debug` still write full paths, as before (the author asked to keep that); an explicit `--path-style` on the same command line wins. Only what is printed changes; the manifests, the caches and the commands' own arguments keep real paths.
+- A symlink is still written where it sits, as before.
+- The `CMD` line (`--verbose`, and the build record) is a command to run again, so it never uses `..`: a path under the working folder is relative, under the home folder `~/...` (outside the quotes, so a shell expands it), else absolute; `full` (so also `--verbose`) keeps every path absolute. The copy of the line in the build record, written whatever `--verbose` said, follows the style, so the account name stays out of it.
+- Setup: the two rows are in a folder's setup too (`FOLDER_OPTIONS`); the inventory has `--path-style`, `--path-up` and the keys.
+- Tests: `tests/test_path_display.py`.
+
+## v3.31.40 — 2026-10-31
+
+Pre-edit state: commit `25ec92a`. Still under 3.31. `[kits]`, entry 3du, point 20 (the author's wish: a course whose lab partners rotate).
+
+A metadata value can add to the layers below instead of replacing them.
+
+- `author+: [B]` in any layer is the value the layers below hold, then `B` (a single value is a list of one; nothing below, just `B`); `author:` and `author+:` in one place are taken in that order. `pdfmd-options.metadata-append: [author]` (a name or a list; `--setup` row *Keys whose document value adds to the layers below*, folders may set it) makes the document's own value add too.
+- The layers, lowest first, are the global metadata, a kit's defaults, the folders' `.pdfmd/metadata.yaml` (the farthest first), the document folder's metadata files and the document's front matter; `tests/test_metadata_append.py` pins that order, which was already how a build behaved.
+- Pandoc cannot do it (the document's front matter beats every metadata file), so pdfmd merges the layers and hands the finished values over in a metadata file under `pdfmd-merged`; `pdfmd_lua/metadata_append.lua` runs before every other filter, sets them and removes the `key+` keys. A build with no plus key and no setting adds no argument at all.
+- A mapping cannot be added to and `header-includes` is not supported (pdfmd lifts it into header files itself): both stop with a message naming the file.
+- An assembled or attached source holds the finished value and no `key+`, and its `pdfmd-options` says `metadata-append: []` (the same reason as `kit: none`, 3.31.38): a restored report rebuilds elsewhere with each name once.
+- Not covered: the built-in renderer (no Pandoc) does not run Lua filters, so it takes the layers as before and does not add.
+- Setup: the `options.metadata-append` row, and the key in `pdfmd_setup/inventory.py`.
+- Tests: `tests/test_metadata_append.py` (11: the order, `+` in each layer, both keys in one place, the setting in the config and in the document, markup in a name, a mapping and `header-includes`, the source and a rebuild in another folder).
+
+## v3.31.39 — 2026-10-31
+
+Pre-edit state: commit `6120d64`. Still under 3.31. `[tables]`, entry 3dz (reported by the author from a pK table).
+
+CSV rows typed straight into a `::: {.csv}` block keep their inline markup.
+
+- Cause: Pandoc has parsed the lines of such a block as a paragraph before the filter sees them; `pdfmd_lua/csv_table.lua` rebuilt the text from the paragraph's inlines and flattened every one but words, quotes and code with `stringify`, so `p*K*~1~` reached the cell reader as `pK1`. A `file=` block and a fenced body never went through that, and neither did a pipe table; `\ce{..}` and `$..$` survived only because Pandoc keeps them as plain text.
+- Emphasis, strong, sub- and superscript, strikeout, links, citations, math and spans are written back as the Markdown that makes them (`pandoc.write` of that one inline, no wrapping), then read as the cell's Markdown as before (`reader`, `pdfmd-csv-reader`). Where that write fails the old flattening is the fallback.
+- Tests: `tests/test_csv_table.py` (`InlineData`): the markup reaches the cells, and the straight form and the fenced form of one table give the same document. Both fail without the change.
+
+## v3.31.38 — 2026-10-31
+
+Pre-edit state: commit `e29cb08`. Still under 3.31. `[kits]`, C4 of entry 3du (a hole found by the review of 3.31.35 to 3.31.37).
+
+An attached or assembled source whose kit is fully embedded says `kit: none`.
+
+- Cause: 3.31.35 embedded what a kit brings (its defaults as metadata files, its preamble, its Lua filter) and stored its parts, but a `kit:` chosen in the document's own front matter stayed in the source. A rebuild on a machine without the kit stopped with "no kit called ...", and on a machine with it (or under a folder whose `.pdfmd/` chooses it) the kit applied again on top of the stored copies: the source of the rebuild was 800 lines longer, with the defaults and the preamble twice.
+- The assembled source's `pdfmd-options` gets `kit: none`, which replaces every `kit:` below the document (the document layer drops what is under it), when metadata and preamble are embedded and so is the Lua filter if the kit has one (`lua` kind embedded or applied; a `ref` or `off` filter, or an embedding with fewer kinds, keeps the kit chosen). The command line's `--kit` still wins. `--restore` says so on its `KIT` line.
+- Checked on copies of a real report with real lualatex: a kit chosen in the report's own front matter, attached and restored, rebuilds pixel-identically (a) in a folder with no `kits/` above it, no config and an empty `TEXMFHOME`, and (b) under a course folder whose `.pdfmd/config.yaml` chooses the kit, where the kit's Lua filter runs once. The transition state (a course `.pdfmd/` with the report's old `metadata/` folder still there) builds pixel-identically to the original as well.
+- Tests: `tests/test_kit_carry.py`.
+
+## v3.31.37b — 2026-10-31
+
+Pre-edit state: commit `48864de`. Documentation only (`CLAUDE.md`): `PDFMD_VERSION` stays 3.31.37.
+
+### Docs
+- `CLAUDE.md`, "Version numbers": the kits and tables lines have no minor of their own; each of their commits is a 3.31.x patch with an entry tagged `[kits]` or `[tables]` (the author's decision of entry 3du, point 14).
+
+## v3.31.37 — 2026-10-31
+
+Pre-edit state: commit `6a21c23`. Still under 3.31. `[kits]`, the spike of entry 3du (point 12).
+
+A chosen kit works from its own folder: no install into the TeX tree.
+
+- The kit's folder, and the folders its `carry:` names with `//` (a logo found by its bare name), go on `TEXINPUTS` and `BIBINPUTS` of the engine's environment (`tex_search_env`, new third argument; the six call sites pass the document). They follow `.` and any value the environment had and come before TeX's own path. The kit's whole folder is not searched recursively: it may hold a repository's worth of data, and kpathsea walks every folder under a `//`. No kit, no change: `tex_search_env` still returns None where it did.
+- Checked with real lualatex on a copy of a real report: with `TEXMFHOME` pointing at an empty folder (so `kpsewhich nulabreport.sty` finds nothing) the report builds from the kit's folder alone, pixel-identical to the build with the package installed.
+- `tests/test_kit_preamble.py`'s real compile no longer sets `TEXINPUTS` itself: its package exists only in the kit's folder. Tests: `tests/test_kit_texinputs.py`.
+
+## v3.31.36 — 2026-10-31
+
+Pre-edit state: commit `e9c09d3`. Still under 3.31. `[kits]`, C4 of entry 3du (the folder layers' part).
+
+An attached source carries the folder settings the build used, and `--restore` writes them back.
+
+- The manifest gets `layers: {options: {...}}`: the `options:` of the `.pdfmd/config.yaml` files above the report, nearest layer winning, flattened into one mapping, without `kit` and `kit-stack` (what a kit wrote is in the source already, and a restored `kit:` would name a kit the machine may not have). `--restore` writes it to `.pdfmd/config.yaml` of the restored folder with a comment line, prints a `FOLDER` line, and leaves a `.pdfmd/config.yaml` that is already there as it is, with a NOTE of what the build used besides. The folders' `.pdfmd/metadata.yaml` files already travel as metadata files; the folder's own value wins, as for every restore.
+- **Attachment format 3, but only for a source with layers.** `ATTACH_FORMAT` (what this pdfmd reads) is 3 and `ATTACH_FORMAT_PLAIN` (what it writes otherwise) stays 2, so a PDF is not refused by an older pdfmd unless it needs the layers, as a refusal is better than restoring a report that builds differently.
+- README: the kit's carrying paragraph says `--embed-metadata` holds the preamble only (3.31.35 said it held the parts).
+- Checked on a copy of a real report: a folder layer with `kit: nulabreport:qca` and `bundle-max-mb: 50` is attached, restored, and the restored folder holds `.pdfmd/config.yaml` with the second only.
+- Tests: `tests/test_attach_layers.py`, `tests/test_attach_format.py`.
+
+## v3.31.35 — 2026-10-31
+
+Pre-edit state: commit `6ab64f0`. Still under 3.31. `[kits]`, C4 of entry 3du (the kit's part).
+
+An attached or assembled source holds what a chosen kit wrote and the kit's parts, so a restored report rebuilds on a machine with no kit.
+
+- **The preamble.** `--attach-source`, `--keep-source`, `--bundle` and `--embed-metadata` put the kit's header (`\usepackage[<options>]{package}`, its `latex:` lines) first among the embedded preambles, and the found preambles as the build read them: what the kit writes twice is settled in them (`KIT-SAME`, `KIT-MERGE`, `KIT-YIELD`), so a rebuild gets the same LaTeX in the same order and `Option clash` cannot come back. The settling is one function for the build and the source (`kit_header_settle`).
+- **The parts.** The files a kit's `carry:` names are stored beside the document whether or not the folder is bundled: a named file keeps its path, a named folder is carried by its files (flat), a name the document's folder holds is left to the folder, a name that is not in the kit is a NOTE, a kit over `bundle-max-mb` is not carried (WARN). They go in before the bundle's own TeX-tree files, so the kit's copy wins. The manifest gets `kits: [{name, version, mode, package, carried}]` (additive; `ATTACH_FORMAT` stays 2); `--restore` prints a `KIT` line and labels the files "from a kit".
+- Checked on a copy of a real report with real lualatex: the report built with `kit: nulabreport:qca` and a course `.pdfmd/`, attached, restored, and rebuilt in the restored folder with no config, no kit and an empty `TEXMFHOME`, is pixel-identical.
+- Tests: `tests/test_kit_carry.py`.
+
+## v3.31.34 — 2026-10-31
+
+Pre-edit state: commit `5420849`. Still under 3.31. `[kits]`.
+
+A kit that leaves out `version:` takes it from its own package.
+
+- A `.kit` with a `package:` and no `version:` reads the version from the `\ProvidesPackage{package}[date vX.Y.Z ...]` line of `package.sty` in the kit's folder. A kit that ships a package then cannot name a version the package no longer has (a number typed twice is stale at the next release). A `version:` that is written still wins; no `.sty`, or a line with no number, gives no version, as before.
+- `pdfmd --kits` shows it like a written one.
+- Tests: `tests/test_kits.py`.
+
+## v3.31.33 — 2026-10-31
+
+Pre-edit state: commit `db18fa3`. Still under 3.31. `[kits]`, found by building a lean copy of a real pre-lab with the kit.
+
+Pandoc, and the TeX engine with it, no longer run in the folder of a metadata file that is not the document's.
+
+- Cause: the folder Pandoc runs in was that of the first metadata file in the list, so that a `bibliography:` or an `\input` written beside a `metadata/` file resolves there. A kit's defaults, a folder's `.pdfmd/metadata.yaml` and the global metadata of `pdfmd --setup` come first when the document has no file of its own, and a relative path in raw LaTeX (a pgfplots table at `../ir/x.csv`) then failed: `Could not read table file`. The same held for a document with only a folder layer since 3.29.10.
+- `metadata_cwd` takes the folder of the first metadata file placed for the document (beside it, in its `metadata/` folder, named with `-y`), else the document's own. The folders of the files it skipped go on `--resource-path`, so a relative `bibliography:` or `csl:` beside them is still found (a kit's folder already was). A document that has only the global metadata now runs Pandoc in its own folder, with the config folder on the resource path.
+- Checked on copies of real reports with real lualatex: a pre-lab built from the original `prelab-metadata.yaml` link and the same pre-lab built with `kit: nulabreport:prelab` and no link are pixel-identical on all 13 pages when the kit's Lua filter is left out (`--no-auto lua`); an LR3 (6 pages, parts, figures) and an LR6, each built with its `metadata/` folder and lean with `kit: nulabreport:qca` and a course `.pdfmd/`, are pixel-identical. Tests: `tests/test_kit_selection.py`.
+
+## v3.31.32 — 2026-10-31
+
+Pre-edit state: commit `1ee4fb9`. Still under 3.31. `[kits]`, C3 of entry 3du.
+
+A chosen kit writes its own preamble, and what it and the user's LaTeX say twice is settled in the build copy (3du, point 9).
+
+- **The kit's lines come first.** One header file, `\usepackage[<mode options>]{package}`, then the kit's `latex:` lines and its mode's, goes ahead of every other `--include-in-header` (after pdfmd's code-wrapping header), so `\labsetup{...}` and the like in `preamble.tex`, `header-includes:` (the document's or a folder's metadata) or an `--include-in-header` file follow it. A kit's `latex-keys` now apply with no `preamble.tex` of the user's.
+- **Four outcomes** for the user's text, in copies in the cache folder (a user's file is never edited): the same line (the package with options the kit already gives, or an `\input` the kit writes) is dropped, `KIT-SAME`; extra options (`[qca,draft]` against `[qca]`) are merged into the kit's one line, `KIT-MERGE` (LaTeX itself stops on two different `\usepackage` lines of one package: "Option clash"); an option that belongs to another mode of the same kit is a contradiction: a preamble found in the folder yields with a WARN, `KIT-YIELD`, its line commented out, while `header-includes:`, an `--include-in-header` file or a named `preamble:` stop the build naming both sides; everything else stays after the kit's lines with no word. `KIT-SAME` and `KIT-MERGE` show with `--verbose`; the ids are fixed for the chatter ladder to come.
+- Only a whole-line `\usepackage[...]{name}` (options may span lines; `\RequirePackage` too) and a whole-line `\input{...}` are rewritten. The kit's package behind a macro or inside a list (`\usepackage{a,labstyle}`) stops the build and names the line; an `\input` in another shape is left alone.
+- `keep_header_includes` (the one place the finished command's header files are settled) does the work for every route; `document_header_file` is active when a kit writes a preamble, so the document's own `header-includes` are not dropped. Pure part: `pdfmd_kits/preamble.py`; tests: `tests/test_kit_preamble.py` (the resolver as a table, builds through pdfmd, and a real `pdflatex` run that survives the user's added option).
+
+## v3.31.31 — 2026-10-31
+
+Pre-edit state: commit `abe26bb`. Still under 3.31. `[kits]`, C2 of entry 3du.
+
+A document can choose a kit, and the kit's defaults, Lua filters and folder reach the build. (The preamble a kit writes is the next patch; until then a kit's package is loaded by the document's own preamble.)
+
+- **Choosing.** `pdfmd-options: {kit: ...}` in a document, a metadata file, a folder's `.pdfmd/` files, a preset or the config's `options:`; `--kit` on the command line. The value reads `nulabreport`, `nulabreport:qca` (no quotes needed), `nulabreport[qca]`, `"[qca]nulabreport"` (quoted), `{nulabreport: qca}`, `{nulabreport: {mode: qca}}`, a list for the order, a path (a value with `/`, `\` or a leading `~` or `.`), and `none|off|false|no` for no kit. A mode is matched by name or alias, ignoring case and `- _ .` and spaces; an unknown mode stops and lists the modes. README, section "Kits".
+- **Layers stack**, lowest first: the config's `kit:` (global), the global metadata or a preset, the folders' files (farthest first), the document's metadata files and front matter. The same kit named higher up replaces only the keys it names (a mode, say); different kits are added in order; `none` drops what is below. A folder's `kit:` names a kit and never searches the project's `kits/` folder or takes a path (a folder's options cannot name code); a message says so.
+- **`--kit`** replaces every `kit:` setting; repeated `--kit` stacks in order; `--kit none`, or a bare `--kit` before another option, means no kit. **`--kit-stack`** (also `pdfmd-options: {kit-stack: ...}` and a `--setup` row) says what `--kit` stacks on instead of replacing: `off` (default), `all`, or a list of `global`, `preset`, `folder`, `document`. Switches stay absolute whatever it says. `kit` and `kit-stack` are `--setup` rows ("Kits").
+- **What a chosen kit brings.** Its `defaults:` files, its inline `metadata:`, its mode's `defaults:` and `metadata:` as metadata files between the global metadata and the folders' own (the folder tunes the kit; the document wins; inline metadata is written once into `kit-metadata/` of the cache folder, named by its content); its `lua:` filters; its folder on Pandoc's resource path, so its `csl:` and `bibliography:` are found by name; its package, so `package_helper` and the Lua and Word lookups see it, and `kit_package_folders` (the 3.31.29 slot) answers; the helper blocks of its `.kit` (`latex-keys`, `draft-skip`, `office`, `lua`...) when no `<package>-pdfmd.yaml` stands beside the `.sty`. `--verbose` prints an `AUTO KIT` line per chosen kit. A document that no layer gives a `kit:` is read as before; the kit code is not imported.
+- Tests: `tests/test_kit_selection.py` (the grammar as a table, YAML spellings, stacking, `--kit` and `kit-stack`, and builds through pdfmd itself with a fixture kit).
+
+## v3.31.30 — 2026-10-31
+
+Pre-edit state: commit `37bfee6`. Still under 3.31. `[kits]`, C1 of entry 3du.
+
+Kits can be read and found (nothing chooses one for a document yet).
+
+- A **kit** is a folder with a `.kit` file, a YAML mapping that generalises `<package>-pdfmd.yaml`: `kit-format: 1`, name, version, `package`, `modes` (package options, a defaults file, default metadata, extra `latex` lines, `aliases` for course codes and the like), `default-mode`, `latex`, `lua`, `defaults`, `metadata`, the helper blocks (`latex-keys`, `picture-cache`, `draft-skip`, `office`) and `carry`. `settings:`, `requires:` and `options:` are reserved and accepted silently; an unknown key is a WARN; every fault of a file is listed at once; a path leaving the kit's folder, a missing file and a `kit-format` above 1 stop. README, section "Kits".
+- New package `pdfmd_kits` (`kitfile`: the format and the mode lookup, names compared ignoring case and `- _ .` and spaces; `discovery`: the search and the cache), pure, imported only when a kit is asked for: a build that selects none costs nothing.
+- Finding by name: a `kits/` folder beside the document and above it, `kits:` in the config file (a path, or `{path:, aliases: {MODE: [names]}}` to add mode names without editing the kit), a `kits/` folder beside the config file, then the folder of `NAME.sty` that kpsewhich finds (asked from an empty folder, the 3.31.29 lesson). The TeX-tree answer is cached in `kits.json` of the cache folder, written atomically, trusted only while the `.kit` has the same size and time; a corrupt cache or a miss is never an error and a miss is never stored. Two different kits of one name in one place stop the search naming both; between places the order decides. `--verbose` prints an `AUTO KIT` line.
+- `--no-auto kit` takes the searching off (a registered `kits:` folder and a path stay); `--no-auto kpsewhich` only the TeX tree.
+- `pdfmd --kits` lists the kits and their modes; `pdfmd --kits NAME-OR-PATH` shows one in full and checks it, with "did you mean" for a near name. `kits:` is a config key (a `--setup` row, *Folders of kits*, this computer only); `--kits` is an `Omitted` command in the inventory; tests: `tests/test_kits.py`.
+
+## v3.31.29 — 2026-10-31
+
+Pre-edit state: commit `c268035`. Still under 3.31.
+
+A lone copy of a package's `.sty` beside the document no longer loses what the package tells pdfmd about itself (3dw).
+
+- Cause: TeX takes `<package>.sty` beside the document first, and pdfmd read `<package>-pdfmd.yaml` only in the folder of the `.sty` it had taken. A report folder holding just `nulabreport.sty` therefore had no `latex-keys:`: the experiment number printed `N/A`, and the performance date and the unknowns line were gone, with no message. (The same gap hid `lua:`, `office:` and `draft-skip:`.) The hard-coded table of those keys was removed in 3.28.37 on purpose ("pdfmd names no package") and stays removed.
+- `package_helper` now looks for the file in this order: beside the `.sty` the document uses (as before), beside the `.sty` of a selected kit that ships the package (kits are not built yet: the place is asked and answers nothing), then beside the installed copy `kpsewhich` finds (asked from an empty folder: TeX searches the current folder first, so from the document's own it answers with the lone copy). The file found keeps its own path, so the names it lists resolve beside it. A helper beside the lone copy still wins. The last two places are searched only when the first has none, so a build whose package carries its file pays nothing.
+- Two `--no-auto` kinds, `kit` and `kpsewhich` (`pdfmd-options: {no-auto: [kpsewhich]}` too, and a `--setup` row each), take one place off; a bare `--no-auto` takes both. On by default: a copy older than the installed helper fails loudly (a `\renewcommand` of a macro it lacks), where without the fallback it printed `N/A` silently.
+- `no_auto` now reaches `package_latex_keys`, `package_lua_names`, `find_lua_filters`, `package_draft_skips`, `document_header_file` and `office_defaults_sources`.
+- Checked through pdfmd itself: a copy of a real 28-page report with a lone `nulabreport.sty` beside it printed `#N/A` for the experiment before, and builds with the same text on every page as the copy without one now.
+- Tests (`tests/test_package_helper.py`): the lone copy reads the installed helper for keys, Lua names and draft skips; the helper beside it wins; `kpsewhich` and a bare `--no-auto` stop the borrowing and `kit` does not; a kit's folder is asked before the installed copy.
+
+## v3.31.28 — 2026-10-31
+
+Pre-edit state: commit `fe93e0a`. Still under 3.31.
+
+`--to png,docx,tex`: the list may now hold any format, not only pictures (3.31.26 refused the others). The author's wish (3dv).
+
+- pdfmd runs itself once per format that is not a picture (the same command line, minus the picture options, with that `--to`), then once for the pictures (`picture_command`). A plain `pdf` is one of those ordinary runs, with its build stamp, backup and attached source, unless `--crop` is given or a source is a PDF already, when it belongs to the picture run (cropped, or a NOTE). The list has no spaces (the shell would split it); a quoted `"png, pdf"` works too.
+- `-o` with more than one format must be a folder (made if need be); otherwise each result is beside its source.
+- Not yet: a document or a setting asking for several formats (`default-output` takes one); logged with the post-build step (3dv).
+- Test: `tests/test_crop.py` (a folder of `html` and `png` from one command; `-o` as a file refused).
+
+## v3.31.27 — 2026-10-31
+
+Pre-edit state: commit `1eb332d`. Still under 3.31.
+
+`--no-page-folder`: the pages of a picture target go beside the document as `NAME-001.png`, `NAME-002.png` ... instead of into the folder `NAME/` (3.31.22); `--page-folder` is the default. The author's wish (3dv): "for people who want exactly this behaviour".
+
+- A setting: `pdfmd-options: {page-folder: false}` in a Markdown file's front matter, in a folder layer's `config.yaml` or the config, a `--setup` row ("Several pages of a picture go into a folder"), the command line over all of them. Not yet read from separate metadata files (queued with the post-build step, 3dv).
+- Test: `tests/test_crop.py` (beside the document; the option in front matter, the flag over it).
+
+## v3.31.26 — 2026-10-31
+
+Pre-edit state: commit `0655fc9`. Still under 3.31.
+
+`--to png,pdf`: several picture targets in one run, from one build and one crop. The author's wish (3dv).
+
+- Any of `pdf, png, jpg, tiff, eps, ps, svg`, comma-separated, each written beside the others (`NAME.png`, `NAME.pdf` ...; a PDF source gives `NAME-crop.pdf` for pdf); `-o` is then a folder. A format that is not a picture (`--to pdf,docx`) is refused with the reason: it has to be a run of its own (queued: a loop of runs, 3dv).
+- A PDF source with `pdf` among the targets and no `--crop` writes nothing for pdf and says so (NOTE).
+- Test: `tests/test_crop.py` (several targets from a PDF and from Markdown; `-o` as a file, a non-picture format, a PDF to pdf).
+
+## v3.31.25 — 2026-10-31
+
+Pre-edit state: commit `cd59372`. Still under 3.31.
+
+`--to tiff` (also `tif`), `--to eps` and `--to ps`; `-o x.tif|x.tiff|x.eps|x.ps` choose them by suffix. The author's wish (3dv).
+
+- All three by Ghostscript: `tiff24nc` (LZW, white, at `--image-dpi`; **all pages in one multi-page file**), `eps2write` (vector; **one file per page**, so several pages go into the folder `NAME/` as `001.eps`...; its bounding box is the ink of the page, whether or not `--crop` is given) and `ps2write` (vector; all pages in one file).
+- Test: `tests/test_crop.py` (`test_tiff_and_postscript_hold_all_pages_in_one_file_and_eps_one_each`).
+
+## v3.31.24 — 2026-10-31
+
+Pre-edit state: commit `36cd49e`. Still under 3.31.
+
+`--to jpg` (also `jpeg`; `-o x.jpg` and `-o x.jpeg` choose it by suffix). The author's wish (3dv).
+
+- Drawn by Ghostscript's `jpeg` device on white (a JPEG has no transparency) at `--image-dpi`, with `--image-quality 1-100` (default 90; a flag with its default in `--help`, `--setup`-omitted like the other picture flags). The file is `NAME.jpg` whichever spelling was typed.
+- `--image-dpi` and `--image-quality` without a picture target are an error.
+- Test: `tests/test_crop.py` (`test_jpeg_is_white_and_takes_a_quality`).
+
+## v3.31.23 — 2026-10-31
+
+Pre-edit state: commit `19d38ab`. Still under 3.31.
+
+`--crop` and `--to png|svg` work with `-b`, `-r` and `-p`; 3.31.21 refused them. The author's wish (3dv): `pdfmd notes -b --crop -o out/` to turn a folder of sources into cropped pictures.
+
+- **`-b`** takes the one folder it takes everywhere (`*.md`, `--recursive` for subfolders) and works through its files, `-j` at a time; **`-r`** builds the report and gives one result named after the folder (inside it, like the report itself); **`-p`** builds the slides and draws a picture per slide. Files named on the command line need no `-b`: `pdfmd *.tex --crop -o out/` crops the PDF of every `.tex`.
+- `-b` and `--recursive` are not handed on to the build of each file's PDF (the files are built one at a time).
+- Test: `tests/test_crop.py` (a folder with `-b -j 2 -o`, `-b` without a folder, a report as a picture; the Markdown builds run on the built-in renderer with no Pandoc on the path).
+
+## v3.31.22 — 2026-10-31
+
+Pre-edit state: commit `a2a987e`. Still under 3.31.
+
+A picture target with more than one page no longer scatters `NAME-1.png`, `NAME-2.png` beside the document: one page is `NAME.png` beside it, several go into a folder `NAME/` as `001.png`, `002.png` ... (zero-padded to at least three digits, wider for a thousand pages, so they sort). `-o a.png` with several pages gives the folder `a/`. The author's wish (3dv).
+
+- Test: `tests/test_crop.py` (`test_png_without_crop_is_the_whole_page_one_file_per_page`).
+
+## v3.31.21 — 2026-10-31
+
+Pre-edit state: commit `27c28e8`. Still under 3.31.
+
+`--crop` and the new targets `--to png` and `--to svg` work on a Markdown source as well as on a PDF.
+
+- **Targets.** `--to pdf` (the default), `png`, `svg`; `-o x.png` / `-o x.svg` choose by suffix. PNG is drawn by Ghostscript's `pngalpha` device (transparent) at `--image-dpi` (default 300, a flag with its default in `--help`, `--setup`-omitted); SVG by `pdftocairo`, else `mutool`, else an error naming the packages.
+- **A Markdown source** is built to a PDF first (pdfmd runs itself with the other options of the command line, and `--no-stamp --no-backup --rewrite`, into a scratch folder, as `--check-docx` does), then cropped and drawn. Its result is `NAME.pdf|png|svg` beside the source (`-d`: the current folder). A PDF source with `--to pdf` gives `NAME-crop.pdf`.
+- **`--to png|svg` without `--crop`** draws the whole page: a crop is asked for, never implied.
+- **More than one page.** A PDF keeps all of them, each cut to its own ink (`--crop-page N` keeps one). A picture format is one picture per page: `NAME.png` for one page, `NAME-1.png`, `NAME-2.png` ... for several, with a NOTE.
+- **`--crop` with a target that has no pages** (`--to docx`, `odt`, `html`, `epub` ...) is an error before anything is built, naming pdf, png and svg. `-b`, `-r`, `-p` with these are refused; `--image-dpi` without a picture target is an error.
+- `png` and `svg` are in `FORMAT_EXTENSION` and `EXTENSION_FORMAT`; new module `pdfmd_crop/images.py`.
+- Test: `tests/test_crop.py` (`Pictures`: whole page, cropped, `-o x.png`, svg, a docx target, batch/report, a dpi without a picture, a Markdown source through the built-in renderer with no Pandoc on the path).
+- The decisions are suggestions the author asked for; they are in the maintainer's notes (3dv) and can be changed.
+
+## v3.31.20 — 2026-10-31
+
+Pre-edit state: commit `db904bd`. Still under 3.31.
+
+`pdfmd --crop FILE.pdf...` cuts a finished PDF to what it draws. It is the crop of eqpop (the macOS popup that renders a formula to a cropped PDF), made portable so eqpop can later hand the job to pdfmd.
+
+- The ink of each page is what Ghostscript's `bbox` device finds painted (the same measurement `pdfmd_office/fragments.py` uses for a fragment); pypdf then sets the media box and the crop box (and the trim, bleed and art boxes if the page has them) to that box plus a pad, never beyond the page's own box. The page stays vector. A rotated page is measured as displayed and cut in its own coordinates; a page that draws nothing is left as it is, with a NOTE.
+- The result is `NAME-crop.pdf` beside the source (the source is never changed), `-o FILE` for one PDF or `-o FOLDER` for several; `-o` the source itself crops in place, through a `.part` file.
+- Settings, each a flag with its default written in `--help`: `--crop-pad PT` (default 2), `--crop-ignore-bottom PT` (default 0; leaves the foot of each page out of the measurement, e.g. a page number), `--crop-page N` (keep that page alone; default every page, each to its own ink). They are `--setup`-omitted (about one run), like `--check-docx`.
+- New package `pdfmd_crop` (`crop_pdf`, `ink_boxes`); `--help crop` is its topic. Without Ghostscript or pypdf the command says what to install.
+- Test: `tests/test_crop.py` (pages drawn by Ghostscript from PostScript, so the ink is known: pad, foot, one page, rotation by 90/180/270, a blank page, in place, the command line).
+
+## v3.31.19 — 2026-10-30
+
+Pre-edit state: commit `aeaad80`. Still under 3.31. Merged from a pull request of the Windows test session.
+
+The plot cache records the files a plot job read, and drops any that is not under the report's folders. TeX writes a Windows drive letter in lower case (`d:/work/lab/ir/product.csv`) where the report's folder is `D:\work\lab`, and the comparison was case-sensitive, so every CSV was dropped as foreign and an edit to it showed as a stale plot. `plot_recorded_inputs` now compares through `os.path.normcase` on both sides (the identity on macOS and Linux).
+
+- Found by the nulabreport smoke test on Windows: after a CSV edit the cached build differed from the uncached one in 96 of 1114 words; with the fix the checks pass and the `.deps` files list the CSVs.
+- Test: `tests/test_plot_cache.py` (`test_a_lower_case_drive_letter_is_still_the_reports_folder`), Windows only, fails without the fix.
+
+## v3.31.18 — 2026-10-31
+
+Pre-edit state: commit `a66a343`. Still under 3.31. Merged from a pull request of the Windows test session.
+
+### Added
+- **`pdfmd --user-path add|remove|show [FOLDER...]` (Windows): put folders on the user PATH, and take them off again.** Spelled-out forms: `--add-to-path`, `--remove-from-path`, `--show-user-path`; `--yes` skips the question, `--dry-run` writes nothing. Opt-in only: nothing in pdfmd calls it by itself. It writes `Path` under `HKEY_CURRENT_USER\Environment` (no administrator rights), keeps the registry type (`setx` would cut the value at 1024 characters and turn it into `REG_SZ`), copies every other entry byte for byte and appends at the end so a new folder never shadows a program of the machine PATH. `add` with no folder takes the folders of the tools pdfmd found off PATH (3.31.10); a folder you name may be any existing folder. It lists what it will do and asks first (no terminal or `PDFMD_NO_PROMPT` without `--yes` refuses); folders already on the user or machine PATH are skipped; the running programs are told (`WM_SETTINGCHANGE`) and the PowerShell line that refreshes the current window is printed. What was added is recorded in `path-added.json` in pdfmd's settings folder (state, not a setting); `remove` takes off exactly those entries and leaves a folder the user already removed alone. On macOS and Linux the command exits 1 and prints the `export PATH=...` line for the shell profile.
+- **A new kind of `--setup` row: an action** (`pdfmd_setup/__init__.py` takes `actions=`; the plain and the full-screen setup both draw it). The first is "Windows user PATH" in "Tool locations" (add the found folders / add a folder you name / show / undo); per machine, shown on Windows only, never in a folder's setup.
+- `--doctor` ends with one note on Windows when tools it found are not on the user PATH.
+- The code is `pdfmd_setup/userpath.py` (four-method backend: `Registry` is the real one, tests use a fake and, on Windows, a throwaway key named by `PDFMD_USER_ENV_KEY`, a test-only variable); `tests/test_user_path.py` (26 tests). Decision 3dr of the maintainer's notes; by the Windows test session (pull request #35).
+
+## v3.31.17 — 2026-10-31
+
+Pre-edit state: commit `61be750`. Still under 3.31. Merged from a pull request of the Windows test session.
+
+### Fixed
+- **The build record of a `-e soffice` build on Windows.** The record runs `soffice --version`; on Windows `soffice.exe` (the window launcher) never answers it, so the probe waited its 10 s, the record said "soffice: no version" and the `soffice.bin` it had started stayed in the process list. `engine_version_line()` now asks the program `resolve_soffice()` found and, on Windows, the `soffice.com` beside it (answers in 0.3 s, leaves nothing). Three tests in `tests/test_probes.py`. By the Windows test session (pull request #35).
+
+## v3.31.16b — 2026-10-31
+
+Pre-edit state: commit `80d19d0`. Tests only (from a pull request of the Windows test session): `PDFMD_VERSION` stays 3.31.16.
+
+### Docs
+- **`docs/windows.md`**: pdfmd on Windows, environment problems and how to fix them (16 entries and a checklist: tools off PATH, a terminal that predates an install, non-UTF-8 locales, symlink privilege, the `python3` Store stub, LibreOffice hangs, files in use, Git Bash paths, PowerShell 5.1, memory, backslashes in re-read paths, where pdfmd keeps its files, CRLF scripts, symlinks and `sh` stand-ins in tests), each tied to the pdfmd version that fixed it. Written by the Windows test session (pull request #34). Not yet wired into `pdfmd --doc` (the documentation programme, 3dg).
+
+## v3.31.16 — 2026-10-31
+
+Pre-edit state: commit `e9445e7`. Still under 3.31. Merged from a pull request of the Windows test session.
+
+### Added
+- **`soffice-timeout`: a LibreOffice run has a time limit.** Every start of LibreOffice (the Office converter and the `-e soffice` route, the ODF reader of hybrid builds, spreadsheets read through it, the SVG converter) goes through one runner, `run_soffice()`: a run that takes longer than the limit is stopped together with the processes it started (the process group on macOS and Linux, `taskkill /T` on Windows), and its file fails with a message that names the setting; the other files of a batch go on. Default 300 seconds. **`0`: LibreOffice is never run** (it counts as not installed; `--doctor` says it is turned off). **A negative number (`-1`): no limit.** The key is in `pdfmd-options` (per document, and in a folder's setup), the config and `pdfmd --setup` ("Checks and limits"); no command-line flag. The two hard-coded limits it replaces (120 s for an SVG, 180 s for a sheet) are gone; the packages take the runner as an argument (`run=`), and without one keep their old limit. `tests/test_soffice_timeout.py`. Decision 3ds of the maintainer's notes.
+
+### Notes
+- The default is a constant the author has not confirmed as a number (300); a first start with a new profile takes 20 to 30 seconds and a large document more, so a low default would break working builds.
+
+## v3.31.15c — 2026-10-31
+
+Pre-edit state: commit `939b66f`. Tests only (from a pull request of the Windows test session): `PDFMD_VERSION` stays 3.31.15.
+
+### Tests
+- A settings folder is named for Windows (`APPDATA`) wherever one is named for `XDG_CONFIG_HOME`: 25 test modules (on Windows pdfmd keeps its settings in `%APPDATA%\pdfmd`, so those tests read and wrote the real folder); `test_indent_office` sets `USERPROFILE` with `HOME`. By the Windows test session (pull request #33).
+
+## v3.31.15b — 2026-10-31
+
+Pre-edit state: commit `9b5b5b5`. Tests only (from a pull request of the Windows test session): `PDFMD_VERSION` stays 3.31.15.
+
+### Tests
+- The full run on Windows (cp1251, every tool installed) found tests that assumed a Unix or macOS machine. New `tests/env_support.py`: `hidden_tools(folder)` (a run with no tools on PATH also hides the Windows install folders and the registry lookup, so the nine "without Pandoc" tests of ansi, build_record, check and native really have no Pandoc), `config_env(folder)` (a settings folder named for `XDG_CONFIG_HOME` and `APPDATA`; `test_tables`), `can_symlink()`. `test_direct` puts `typst` on PATH under the program's own name and copies it when a link is refused; the Calibre archive test skips where symbolic links are not allowed. By the Windows test session (pull request #31).
+
+## v3.31.15 — 2026-10-31
+
+Pre-edit state: commit `0695669`. Still under 3.31. Merged from a pull request of the Windows test session.
+
+### Fixed
+- **A `.csv` block of an `.xlsx` on Windows.** The map from a sheet to its converted CSV (a `--metadata-file`) held `C:\Users\...\x.csv`; Pandoc reads metadata as Markdown, so the backslashes went and the block came out empty ("could not open the converted sheet"). The path is written with forward slashes (`as_posix()`; no change on macOS and Linux), like 3.31.8 and 3.31.13. By the Windows test session (pull request #32).
+
+## v3.31.14 — 2026-10-31
+
+Pre-edit state: commit `0f8f11a`. Still under 3.31. Merged from a pull request of the Windows test session.
+
+### Fixed
+- **`pdfmd --completion` prints its script with Unix line ends on Windows.** Python's text-mode standard output wrote CRLF, and `source <(pdfmd --completion bash)` failed in Git Bash and WSL ("syntax error near unexpected token `$'{\r''"). The command keeps plain newlines (`sys.stdout.reconfigure(newline="\n")`); macOS and Linux are unchanged. A test checks the bytes. By the Windows test session (pull request #30).
+
+## v3.31.13b — 2026-10-30
+
+Pre-edit state: commit `c4491c7`. Docs only: `PDFMD_VERSION` stays 3.31.13.
+
+### Docs
+- `CHANGELOG.md`: the note "Why this starts at 2.0.0, not 1.0.0" and its 2026-10-05 update moved from the top of the file to the end of the v2.0.0 entry, so the file opens with the version rule and the newest entry.
+
+## v3.31.13 — 2026-10-30
+
+Pre-edit state: commit `5204a2c`. Still under 3.31. Merged from a pull request of the Windows test session.
+
+### Fixed
+- **Converted SVG pictures on Windows.** `image_filter_args` wrote the converted PDF's path into the image map with backslashes; `images.lua` puts it into raw LaTeX, where a backslash is a command (`lualatex`: ``File `C:-1234.pdf' not found``). The path is written with forward slashes (`as_posix()`; no change on macOS and Linux). By the Windows test session (pull request #28).
+
+## v3.31.12 — 2026-10-30
+
+Pre-edit state: commit `83f8331`. Still under 3.31. Merged from a pull request of the Windows test session.
+
+### Fixed
+- **Mermaid diagrams on Windows.** `diagram.lua` started `mmdc` by its bare name; npm writes `mmdc.cmd` on Windows, a command script that a program started by name cannot be, so a ```mermaid block stayed code ("could not be drawn") with `mmdc` on PATH. On Windows the filter now starts it as `cmd /c mmdc ...`; macOS and Linux are unchanged. With 3.31.8's slash fix a real `mmdc` 12 builds an inline SVG. `tests/test_diagram_shim.py` (Windows only, a stand-in `mmdc.cmd`) fails without the change. By the Windows test session (pull request #25).
+
+## v3.31.11 — 2026-10-30
+
+Pre-edit state: commit `a080381`. Still under 3.31. Merged from a pull request of the Windows test session.
+
+### Added
+- **Pandoc, Typst and Chrome are found and used when a Windows installer leaves them off PATH,** on the lookup of 3.31.10: the keys `options.pandoc-path`, `typst-path` and `chrome-path` (`--setup`, "Tool locations"; a file or a folder), then PATH, then the usual folders (Pandoc under `%LOCALAPPDATA%\Pandoc`, Typst in WinGet's `Links` and `Packages`, Chrome under `Google\Chrome\Application`). The folders of Pandoc and Typst go on the PATH of pdfmd and its programs; a Chrome named by the key is handed to the browser engines through the existing `PDFMD_BROWSER`. `--doctor` adds the same `found at X, not on PATH` / `set by options.KEY` notes. By the Windows test session (pull request #24, entry 3dq).
+
+## v3.31.10 — 2026-10-30
+
+Pre-edit state: commit `56c5e9b`. Still under 3.31. Merged from a pull request of the Windows test session.
+
+### Added
+- **Tools that a Windows installer leaves off PATH are found and used: Tesseract, LibreOffice, Graphviz (`dot`), Mermaid (`mmdc`), Poppler.** `winget` and the vendors' installers often skip PATH, so `--doctor` said "not found" for programs that were installed. One lookup (`locate_tool()`, table `FOUND_TOOLS`) now tries, in this order: the config key, PATH, then on Windows the usual install folders (`%ProgramFiles%`, `%ProgramW6432%`, `%ProgramFiles(x86)%`, `%LOCALAPPDATA%\Programs`, `%APPDATA%\npm` for `mmdc`) and the registry's `App Paths`. A tool found off PATH has its folder added to the PATH of pdfmd and of the programs and filters it starts (in front when the config names it, behind otherwise); LibreOffice is resolved by path only, because its folder holds a `python.exe` and DLLs of its own. The folders are a file-system fact about those installers, not a behaviour threshold.
+- **Five config keys, `options.tesseract-path`, `soffice-path`, `dot-path`, `mmdc-path`, `poppler-path`,** in `pdfmd --setup` ("Tool locations", per machine; a folder's `--setup DIR` never offers them): a file or a folder (`poppler-path` takes the folder holding `pdftotext` and `pdftoppm`). A key that names nothing warns once and is passed over. No command-line flag, no `pdfmd-options` key.
+- `--doctor` says where a tool was found: `found at X, not on PATH (pdfmd uses it anyway)` or `set by options.KEY`; the README has a Windows note.
+
+### Changed
+- `resolve_soffice()` and `resolve_calibre()` use the same lookup. `PDFMD_NO_APP_PATHS=1` turns the registry probe off; it is for the tests (so that a test that hides a tool does not find it again), not a setting.
+
+### Notes
+- The next patch adds `pandoc-path`, `typst-path` and `chrome-path` on the same lookup. By the Windows test session (pull request #23, entry 3dq of the maintainer's notes).
+
+## v3.31.9h — 2026-10-30
+
+Pre-edit state: commit `7c57727`. Tests only (from a pull request of the Windows test session): `PDFMD_VERSION` stays 3.31.9.
+
+### Tests
+- `tests/test_build_log.py`: the test that needs an `AUTO` line made no file of its own and found the author's global `metadata.yaml`; on a clean machine there was none. It writes its own `metadata.yaml` beside the document and asserts that line. By the Windows test session (pull request #26).
+
+## v3.31.9g — 2026-10-30
+
+Pre-edit state: commit `d4bca2e`. Tests only (from a pull request of the Windows test session): `PDFMD_VERSION` stays 3.31.9.
+
+### Tests
+- `tests/test_ansi.py` reads pdfmd's output as UTF-8 (`encoding="utf-8"` on three `subprocess.run` calls); under a non-UTF-8 Windows locale such as cp1251 ten tests failed on the decoding, not on pdfmd, which writes valid UTF-8. By the Windows test session (pull request #29).
+
+## v3.31.9f — 2026-10-30
+
+Pre-edit state: commit `ea1a7f7`. Tests only (from a pull request of the Windows test session): `PDFMD_VERSION` stays 3.31.9.
+
+### Tests
+- One helper, `tests/cache_support.py` (`cache_env(folder)`), names the cache folder for every system (`XDG_CACHE_HOME` and `LOCALAPPDATA`); seven test modules use it (build_record, calibre, chem, compat, images, markup_word, raw). By the Windows test session (pull request #27).
+
+## v3.31.9e — 2026-10-30
+
+Pre-edit state: commit `57cf5e8`. Tests only (from a pull request of the Windows test session): `PDFMD_VERSION` stays 3.31.9.
+
+### Tests
+- `tests/test_completion.py` hands bash a path Git Bash can read (forward slashes); `tests/test_edit_pdf.py` no longer uses the Unix command `true` as an editor. By the Windows test session (pull request #22).
+
+## v3.31.9d — 2026-10-30
+
+Pre-edit state: commit `63ddd01`. Tests only (from a pull request of the Windows test session): `PDFMD_VERSION` stays 3.31.9.
+
+### Tests
+- The build-log and office-LaTeX tests point the cache at their own folder through `LOCALAPPDATA` as well as `XDG_CACHE_HOME` (Windows reads the first; the records went to the real user cache and the tests found none). By the Windows test session (pull request #21).
+
+## v3.31.9c — 2026-10-30
+
+Pre-edit state: commit `d4f4cf1`. Tests only (from a pull request of the Windows test session): `PDFMD_VERSION` stays 3.31.9.
+
+### Tests
+- `tests/test_indent_office.py` closes the `ZipFile` it opens before the temporary folder is removed (`WinError 32` on Windows). By the Windows test session (pull request #20).
+
+## v3.31.9b — 2026-10-30
+
+Pre-edit state: commit `28f1168`. Tests only (from a pull request of the Windows test session): `PDFMD_VERSION` stays 3.31.9.
+
+### Tests
+- The helpers of `tests/test_office_latex.py` that run Pandoc with the office filter alone pass `pdfmd-office-python` (the running interpreter), as the real pipeline does; on Windows `python3` is the Microsoft Store stub. Nine tests. By the Windows test session (pull request #19).
+
+## v3.31.9 — 2026-10-30
+
+Pre-edit state: commit `0b1f055`. Still under 3.31. Merged from a pull request of the Windows test session.
+
+### Fixed
+- **LibreOffice's throwaway profile on Windows.** The three places that start `soffice` with `-env:UserInstallation=file://{profile}` (the Office converter, the ODF reader, the SVG converter of `pdfmd_images`) built `file://C:\...`, which is not a file URL: headless LibreOffice then waited for ever with no output (25+ minutes measured), or exited 1 without a PDF. They pass `Path.as_uri()` now (`file:///C:/...`, percent-encoded; the same string on macOS and Linux). A test (`tests/test_svg_profile.py`) fails without the change. A time limit for the call is not added: it needs a setting and waits for the author. By the Windows test session (pull request #18).
+
+## v3.31.8 — 2026-10-30
+
+Pre-edit state: commit `57919d1`. Still under 3.31. Merged from a pull request of the Windows test session.
+
+### Fixed
+- **The raw filters on Windows.** `pdfmd-raw-cache`, `-work` and `-preamble` were written into the generated YAML metadata file with `str(Path)`; Pandoc reads a string there as Markdown, where a backslash escapes, so a Windows path lost its backslashes and the PDF images and the Typst/LaTeX raw pictures were not converted. They are written with forward slashes now (`as_posix()`; no change on macOS and Linux). By the Windows test session (pull request #17).
+
+## v3.31.7 — 2026-10-30
+
+Pre-edit state: commit `9813fde`. Still under 3.31. Merged from a pull request of the Windows test session.
+
+### Fixed
+- **`--split` no longer crashes on Windows without the symlink privilege.** `split_into_parts` linked the files and folders next to the source into the scaffold with `symlink_to`; an ordinary Windows user (no Developer Mode, not elevated) gets `WinError 1314`. It now copies the file or folder when the link cannot be made. macOS and Linux still link. A test covers the copy; the command-line split test globs the parts folder only. By the Windows test session (pull request #16).
+
+## v3.31.6 — 2026-10-29
+
+Pre-edit state: commit `9f09a1f`. Still under 3.31. The first step of `emit` (the chatter ladder of the tables line, which is NOT started).
+
+### Changed
+- **The record of a build holds the lines that only `--verbose` shows.** The 40 or so places that printed under `--verbose` (the `AUTO` decisions, `CALC`,
+  `LABELS`, `OFFICE`, `HYBRID`, the direct routes, backups and the history) call `vprint(shown, ...)`: on the console when `--verbose` is on, as before, and in the record
+  always. The metadata files the build used are in the record too. The console without `-v` is unchanged. `WARN`, `NOTE` and `ERROR` lines still print directly
+  (the console shows them anyway); the chatter ladder will move them to one `emit(level, id, text)` and `vprint` becomes its verbose level.
+
+## v3.31.5 — 2026-10-29
+
+Pre-edit state: commit `3cb13f4`. Still under 3.31, in front of the rest of the tables work.
+
+### Added
+- **The record of a build.** Every build writes a plain-text file to the cache: the command line, the versions (pdfmd, Python, Pandoc, the engines), every
+  command run (the `CMD` lines, whatever `--verbose` said), everything pdfmd printed, what each engine answered (exit code, stderr, stdout), the steps and their
+  times, and what the build answered; the home folder is written as `~`. It sits where `cache: location` says (`~/.cache/pdfmd/builds/NAME-HASH/`, or
+  `.cache/pdfmd/builds/NAME/` beside the document), one file per build (`20261029-140533-ok.log`, `-failed.log`). A failed build ends with `full record: PATH`
+  (`--verbose` also names the record of a good one); a build that stopped with an error is recorded too.
+- **`pdfmd --last-build FILE [--failed]`** prints the newest record, or the newest failed one; none: a message and exit status 1.
+- **`build-log: on|failed|off`** (default on; `--build-log MODE`), **`build-log-keep`** (default 5; the newest ones stay, and the newest failed one whatever its age,
+  so a good build never erases a failure) and **`build-log-max-size`** (KB, default 512; a longer record keeps its start and more of its end), in `pdfmd-options`,
+  the config and `--setup`.
+- The package `pdfmd_buildinfo.record` (pure): scrubbing, clipping, naming, atomic writing and pruning.
+
+### Notes
+- A first version, built from the central points (no `emit` yet): the lines that only `--verbose` prints at their own print sites are not in the record until every
+  message goes through one function. A `.qmd`, a direct `.typ`/`.html` build and a report or book build are not recorded yet. A record that cannot be written
+  (read-only or full disk) never fails a build.
+- `tests/test_00_environment.py` turns the record off for the suite as a whole (it would make a record for each of the thousand documents the tests build); the
+  tests of the record ask for it.
+
+## v3.31.4 — 2026-10-29
+
+Pre-edit state: commit `f05d80e`. Still under 3.31, in front of the rest of the tables work (the author asked for it at once).
+
+### Added
+- **How long a build took.** The closing line ends in the time, `OK    report.md > report.pdf  in 3:07  (lualatex)`, also for a file that failed
+  (`FAIL  report.md  in 0.15 s`) and for a report or book build. Written by `time-format` (the new package `pdfmd_buildinfo`): `auto` (the default;
+  `0.42 s`, `12.4 s`, `3:07`, `1:02:03`, `1 d 02:03:04`), `clock` (`03:07`; hours never wrap into days), `seconds`, `words`, or a template with
+  `{d} {h} {hh} {m} {mm} {s} {ss} {s1} {s2} {ms}`; a unit wraps only under a larger one of the template, and the time is rounded to the smallest unit shown.
+- **`build-time: on|off`** (default on) and **`time-format`**, in `pdfmd-options`, the config, `--setup`, and as `--build-time` / `--no-build-time` and
+  `--time-format STYLE`. A wrong format stops the command line and warns for a document (it reads as `auto`).
+- **`--verbose` prints a `TIME` line for every step**: the engine run (`pandoc + lualatex`; a font retry is a second line), the label and calc passes, plots,
+  polish, attach-source, backup, history, the size budget; and "the rest" (finding files and settings, the pre-passes no step covers).
+- **The history file records the seconds** of a build (`took=187.4`) when the history goes to `NAME.hst`; nothing is written into the document's BUILD NOTES.
+
+### Changed
+- The tests that matched the whole closing line take the time into account.
+
+## v3.31.3b — 2026-10-27
+
+Pre-edit state: commit `b08a7b4`. Documentation only (`CLAUDE.md`): `PDFMD_VERSION` stays 3.31.3.
+
+### Docs
+- `CLAUDE.md`, "Version numbers": one commit is one version and one entry; a test, workflow or docs file alone takes a lettered entry; a commit that changes only `TODO.md` has no entry; the unreleased-fix clause is for a fix to a bug of that very version only.
+
+## v3.31.3 — 2026-10-27
+
+Pre-edit state: commit `4d6291b`. Still the tables line: the settings of the width filter are named for what they set, and none of their numbers is a constant.
+
+### Added
+- **`column-outlier-rows`** (default 4), **`column-outlier-length`** (30) and **`column-word-floor-limit`** (16, the longest word the floor protects) are
+  settings; they were constants in the filter. Every number of the filter (`column-outlier` too) can be given per table, `{column-outlier=3
+  column-outlier-rows=6 column-outlier-length=40 column-word-floor-limit=24}` after the caption (Pandoc 3.8.2 or newer), in `pdfmd-options`, in the
+  config and in `--setup`.
+- **`column-count-raw-tex: on|off`**, a KLUDGE until a real width estimator exists: raw TeX in a cell counted as nothing (a cell of "respiratory
+  tract \SIrange{10}{20}{\minute}" was sized as 17 characters and printed as 34, so its column wrapped while another took the room). `\SI`,
+  `\SIrange`, `\num`, `\ce` and other raw TeX now count as about what they print. Off (or `{count-raw-tex=off}` on a table) gives the old behaviour.
+
+### Changed
+- **`table-widths` is now `column-widths`, and `table-word-floor` is `column-word-floor`**: "table width" read as the width of the whole table, and
+  these set the columns'. The older names are still read everywhere (the config, `--setup`, `pdfmd-options`, `-M`).
+
+### Docs
+- `CLAUDE.md`: "No hardcoded thresholds": a number that changes behaviour is a setting; a constant that must stay in the code is reported to the author.
+
+## v3.31.2 — 2026-10-27
+
+Pre-edit state: commit `041a8f0`. Still the tables line.
+
+### Added
+- **`column-outlier`** (default 2; 0 switches it off; `pdfmd-options`, the config, `--setup`, or `{column-outlier=N}` after a table's caption): one cell
+  more than twice as long as the next-longest of its column (a column of four rows or more, a cell of at least 30 characters) no longer sizes the
+  column, so the others keep the room that holds them on one line; the outlier wraps, and what is left over goes to its column. The one-line "natural
+  width" test still counts the real longest cell, so an outlier never runs past the margin. (The two minimums were constants here; 3.31.3 makes them settings.)
+- **Plain `pdfmd` never reads standard input** (decided: a script's inherited pipe looks the same as `echo x | pdfmd`). In a folder without Markdown
+  files the error now names `pdfmd -` when standard input is not a terminal.
+
+## v3.31.1 — 2026-10-27
+
+Pre-edit state: commit `12cc24a`. Still the tables line.
+
+### Changed
+- `--doctor` lists the Pandoc 3.8.2 floor for a table's own `{widths=... word-floor=...}` (it reads the table's attributes from the caption), and the `--setup` notes of both keys say so.
+
+## v3.31.0b — 2026-10-27
+
+Pre-edit state: commit `15f70ee`. Documentation only (`CLAUDE.md`): `PDFMD_VERSION` stays 3.31.0.
+
+### Docs
+- `CLAUDE.md`: "Decisions are recorded first": every decision goes into the maintainer's notes, at full context, and a short `TODO.md` line, before any code.
+
+## v3.31.0 — 2026-10-27
+
+Pre-edit state: commit `d296523`. Opens the tables line (the plan is in the maintainer's notes): the first change is to the pipe-table width filter.
+
+### Fixed
+- **A column the author chose could break words in the middle.** A pipe table whose separator dashes are unequal (`|:-------|:-------------|`) is a
+  choice and was kept as written, even when a column came out narrower than its own longest word and LaTeX cut "Sustained" into "Sus-tained". A
+  chosen column too narrow for its longest word (a word of up to 16 characters; a URL is not worth the room) is now widened to it, and the
+  other columns give up the space in proportion to what they had, none below its own longest word. A table where every column already holds its
+  words is untouched, byte for byte. The note `AUTO TABLEWIDTH` says when it happened.
+
+### Added
+- **`table-word-floor: on|off`** (`pdfmd-options`, the config, `--setup` "Tables"): off leaves a chosen table exactly as written, for a table where
+  breaking a word is meant (long chemical names in a narrow column).
+- **`table-widths: force`** next to `auto` and `keep`: the dashes are ignored and every table gets the widths that give the fewest lines.
+- **A table's own `{widths=auto|keep|force word-floor=on|off}`** after its caption wins over the document and the config (Pandoc 3.8.2 or newer,
+  which keeps a caption's attributes on the table; older ones print them in the caption).
+- A document's `pdfmd-options` now wins over the global `table-widths` of the config (the global value used to shadow it).
+
+### Changed
+- The `AUTO TABLEWIDTH` note no longer says the tables "had no column widths" only: it also covers `table-widths: force`.
+
+## v3.30.42b — 2026-10-26
+
+Pre-edit state: commit `4efe2c5`. Documentation only (the README and the notes in `pdfmd.py` and `--setup`): `PDFMD_VERSION` stays 3.30.42.
+
+### Fixed
+- The notes on pipe-table column widths claimed more than the code does. Unequal separator dashes are kept only under Pandoc's own Markdown reader (a document with front matter or a linked metadata file); under `gfm` they carry no width and every table is balanced. Colons count as dashes. The balancing runs for the LaTeX engines only; the other writers take Pandoc's widths, equal columns for `---|---` with a long line under the Markdown reader. The behaviour itself is unchanged and queued.
+
+## v3.30.42 — 2026-10-26
+
+Pre-edit state: commit `0ae751a` (v3.30.41).
+
+### Fixed
+- **`--paper a4,landscape` (and `papersize: a4,landscape`) turned no page but the built-in renderers'.** Pandoc's `papersize` is a
+  LaTeX class option: on the LaTeX engines it printed `[a4,landscapepaper]`, LaTeX said "Unused global option" and the page was
+  Letter, silently; Calibre and the browsers lost the orientation too (the Word-file reader did not split the list item); WeasyPrint
+  ignored the paper altogether (A4 whatever `papersize:` said); Typst stopped on `a4,landscape`, and on a plain `--paper letter`
+  (pdfmd's translation to `us-letter` came as a second `-V papersize=`, and Pandoc joined the two into `letterus-letter`). One
+  function, `paper_variables`, now settles the paper for each engine: LaTeX gets the size as a class option and the turn as
+  `geometry:landscape`; Typst gets its own name (`us-letter`, `iso-b5`) once and `#set page(flipped: true)` through `typst.lua`;
+  WeasyPrint gets `@page { size: ... }` through `weasyprint.lua`; Calibre and the browsers read the list item. The same page comes
+  from `geometry: landscape` and `classoption: landscape`, and from the `pagesize:` typo, which now also beats a `papersize:` of the
+  settings in the Calibre, browser and Word readers (as it did for LaTeX).
+- Spellings that printed a Letter page on LaTeX: `a4paper` (became `a4paperpaper`), `A4`, `us-letter`, and `a3` (no class option;
+  `geometry:a3paper` now). `--paper landscape` alone keeps the size the settings name.
+- `--no-auto papersize` leaves all of this to Pandoc. Measured on Pandoc 3.12 with LuaLaTeX, Typst, WeasyPrint, Calibre and
+  the built-in renderer, for `a4,landscape`, `letter,landscape`, `a4`, `letter`, `a4paper`, `a3`, `us-letter,portrait`, `landscape`
+  and front matter `papersize`, `pagesize`, `geometry`, `classoption`.
+
+## v3.30.41 — 2026-10-26
+
+Pre-edit state: commit `c2732a2` (v3.30.40).
+
+### Added
+- **`mdpdf` answers the npm `mdpdf` too.** `--style FILE` and `MDPDF_STYLES` (a style sheet; `-e html` is added unless an engine is
+  named), `--format` (paper), `--orientation landscape` (`-V geometry:landscape`: the LaTeX route; `papersize: a4,landscape` is read
+  by the built-in renderers only), `--border` and `--border-top|-left|-bottom|-right` (margins as `geometry:` variables; px count as
+  0.75 pt). `--header`/`--footer` are told apart by the value: an `.html`, `.htm` or `.hbs` file, or any file that exists, is the npm
+  one's Puppeteer markup and is dropped; a template `"left,middle,right"` stays the PyPI one's. Dropped with a note on standard
+  error, never silently: those headers and footers, `--h-height`, `--f-height`, `--no-emoji`, `--gh-style`, `--debug`.
+- **`--doctor` names a command of pdfmd's that another program answers.** `pdfmd`, `mdpdf`, `md2pdf`, `inkmd` and the others are
+  shared by several tools, and the one installed last owns each name; a "Command names" section says which names on the PATH are not
+  pdfmd's and how to take them back (`pip install --force-reinstall --no-deps pdfmd-cli`). It reads the installed package's own list
+  of scripts, so it says nothing from a checkout, and nothing when every name is pdfmd's. Checked in a scratch virtualenv with a
+  different `md2pdf` ahead on the PATH.
+
+## v3.30.40 — 2026-10-26
+
+Pre-edit state: commit `e606b1b` (v3.30.39).
+
+### Added
+- **An `md2pdf` command.** Several tools install that name; pdfmd now answers the keys of all three: jmaupetit's `md2pdf`
+  (`-i -o -c -W`), `md-to-pdf` (`--stylesheet`, `--as-html`, `-w`, `--document-title`) and kxxoling's (`--theme file.css`). A style
+  sheet adds `-e html` unless an engine is named (only HTML engines read CSS). `-e` is an engine when its value is one and
+  jmaupetit's Markdown extension otherwise. What pdfmd has no counterpart for (extensions, `-C`, `--pdf-options`, `--config-file`,
+  `--launch-options`, a string given to `--css`, a built-in `--theme`) is named on standard error and left out.
+
+## v3.30.39 — 2026-10-26
+
+Pre-edit state: commit `e069268` (v3.30.38).
+
+### Added
+- **`mdpdf in.md out.pdf`: the output as a second positional.** The Go `mdpdf` and `md2static` name the PDF that way; the
+  `mdpdf` command now takes a last positional ending in `.pdf` that follows another positional as `-o`, whether or not options
+  come after it (`mdpdf notes.md notes.pdf -p A4`). It is left alone when `-o` is given, when it is the value of an option
+  (`--cover c.pdf`), when it is the only argument, and when the one before it is a PDF too. The original `mdpdf` never reads a PDF,
+  so nothing it accepted changes. `pdfmd` itself does not do this: for pdfmd a PDF argument is an input.
+- **`pdfmd x.pdf -o -`: the Markdown on standard output.** M1ck4's `pdfmd` (archived 2026-05-08) pipes that way; for PDF inputs it
+  now means batchocr's `--stdout` (it was the terminal view, which refuses a PDF). `pdfmd x.pdf --stdout` worked already. The setting reaches `-j` workers (`tests/test_jobs.py` caught the first version, which did not).
+
+## v3.30.38 — 2026-10-26
+
+Pre-edit state: commit `d4ae514` (v3.30.37).
+
+### Fixed
+- **A `.csv` block's caption with several attribute words was printed as text.** `Table: Raw data {#tbl:raw keep=9}` (or the `: Raw data {...}` form) after a `::: {.csv}` block gave the table no id and no attributes and left `{#tbl:raw keep=9}` in the caption: only a block of one word (`{#tbl:raw}`, `{.keep}`) was read. The block may hold several words now, every one an `#id`, a `.class` or a `key=value`, and a `key=value` block (`{keep=9}`) counts. A brace in the caption's prose (`Set {x} and {y}`) is still prose.
+
+### Added
+- **`keep` on a `.csv` div reaches the table.** `::: {.csv file="x.csv" keep=4}`, `::: {.csv .keep}` and `.nokeep` put `keep=4`, `keep` or `nokeep` on the table's own attributes, where a filter that keeps a short table on one page (nulabreport.lua) looks for them; the caption's own attributes win. `tests/test_csv_table.py`.
+
+## v3.30.37 — 2026-10-26
+
+Pre-edit state: commit `276f947` (v3.30.36).
+
+### Added
+- **`--no-rewrite`: keep the old output.** A build replaces an older `report.pdf`; with `--no-rewrite` it writes `report (1).pdf` (the first free number) and leaves the old file alone. `--rewrite` turns it back on for one run. Also `pdfmd-options: {rewrite: false}` (a document, a folder's `.pdfmd`, the config) and a `--setup` row ("Replace an older output of the same name", in the folder screen too). The name is a template, `rewrite-name` (`--setup`: "The name of the numbered copy"), default `{stem} ({n}){ext}`, with `{n}`, `{stem}`, `{ext}` and `{date}`; one without `{n}` or with a folder in it is refused with a warning. It applies to the final output of every build: the `-o` name, each file of a `-b` batch and of a parts build on its own, `pdfmd -` (`stdin (1).pdf`), `--to` formats; the cache stage's `.tex`, the `--view` scratch files and the builds pdfmd runs on itself (`--edit`'s rebuild, the labels pass, the Python API) are never numbered. A watch (`-w`) always rewrites. The first build of a name has no number. `tests/test_rewrite.py`.
+
+## v3.30.36 — 2026-10-26
+
+Pre-edit state: commit `bdc81b1` (v3.30.35).
+
+### Added
+- **The indent div works in Word and OpenDocument.** `::: {indent=false}` (and `noindent`, `indent=2em`, ...) printed a NOTE and changed nothing in a `.docx` or `.odt`, so a Word file did not match the PDF. `pdfmd_lua/indent.lua` now gives the plain paragraphs of the div a paragraph style named for the length, `pdfmd-indent-0pt`, `pdfmd-indent-2em` (Pandoc applies a custom-style div to the paragraphs directly inside it and leaves lists, quotes, code and tables in their own styles); `pdfmd_office` writes the first-line indent into the style afterwards (`w:ind w:firstLine` in a Word file, `fo:text-indent` in an OpenDocument file, where Pandoc only names the style and does not define it). An em is 12 pt there. The paragraphs after the div are the document's own again. A length in `%` or `rem` is still left out with the NOTE. Checked in LibreOffice: the div's first line starts at the margin (72 pt), `2em` at 96 pt, the body text after it at its own indent. `tests/test_indent_office.py`.
+
+## v3.30.35 — 2026-10-26
+
+Pre-edit state: commit `bbb6a47` (v3.30.34).
+
+### Added
+- **A LuaTeX that cannot start names why.** An unwritable TeX cache and a corrupt luaotfload database both reached pdfmd only as Pandoc's `lualatex failed (!  ==> Fatal error occurred, no output PDF file produced!)`: the cause is in the engine's own console, and the two looked alike although the fixes differ. When lualatex fails with that line and the text names no known cause, pdfmd runs a one-line page with the same engine in the same environment (once per run, 120 s at most) and classifies what it prints: `cause: the TeX cache folder is not writable; set TEXMFVAR and TEXMFCACHE to a folder you can write to`, or `the LuaTeX font database is corrupt; run luaotfload-tool --update --force, or delete the luatex-cache folders`. `--doctor --deep` shows the same cause after the reason an engine failed. The signature `no writeable cache path` is matched across a wrapped console line (macOS prints `quiting`, Linux `quitting`). Checked with a read-only `TEXMFVAR`/`TEXMFCACHE` on macOS. `tests/test_tex_cause.py`.
+
+## v3.30.34 — 2026-10-26
+
+Pre-edit state: commit `210497a` (v3.30.33).
+
+### Added
+- **`pdfmd -` builds the Markdown on standard input.** `echo '# Hi' | pdfmd -` writes `stdin.pdf` (`stdin.html`, `stdin.docx` ... with `--to`) in the current folder, or the file `-o` names. Before, `-` was "Could not find Markdown file for '-'", and only `--view` and `-o -` read a pipe. The text is kept in a hidden file in the current folder for the length of the run (a relative picture or include resolves there; it is removed on success, failure and ^C), and the OK line names it `stdin.md`. Standard input that is empty is refused with a reason. A plain `pdfmd` with a pipe is unchanged (it builds the folder's Markdown): the `-` is what says that the pipe is the document, so no script that runs `pdfmd` with an inherited stdin changes meaning. `tests/test_stdin.py`.
+
+## v3.30.33 — 2026-10-26
+
+Pre-edit state: commit `5fe0411` (v3.30.32b).
+
+### Fixed
+- `--doctor --deep` builds a page with a struck-out word. A LaTeX installation without `soul.sty` (xelatex, pdflatex) or `lua-ul` (lualatex) passed the check and then failed on the first document with `~~text~~`.
+
+## v3.30.32b — 2026-10-26
+
+Pre-edit state: commit `3b97509` (v3.30.32). A docs-only commit: `PDFMD_VERSION` stays 3.30.32.
+
+### Added
+- `TODO.md`: the open work, one line per item, grouped as next / decide first / agreed features / before 4.0 / investigate first / other repositories. `CLAUDE.md` says to delete an item in the commit that finishes it.
+
+### Fixed
+- `tests/test_doc.py` accepts a lettered newest changelog heading (`v3.30.32b`); it compared the heading with `PDFMD_VERSION` exactly, so the first docs-only commit under the 3.30.30 rule would have failed it.
+
+## v3.30.32 — 2026-10-26
+
+Pre-edit state: commit `0f6d680` (v3.30.31). Issue 15.
+
+### Fixed
+
+- A TeX Live or MiKTeX that is installed but not on `PATH` was reported as "no TeX engine installed": on Windows `--doctor` listed only Typst, the default run fell back to Typst without a word (a document with `\ce` or `\SI` built without LaTeX) and `-e tex` stopped with an error. When no TeX engine is on `PATH`, pdfmd now looks in the usual places (TeX Live: `C:\texlive\<year>\bin\*`, `%ProgramFiles%\texlive`, `~/texlive`, `/usr/local/texlive/<year>/bin/*`, `/Library/TeX/texbin`; MiKTeX: `%LOCALAPPDATA%\Programs\MiKTeX`, `%ProgramFiles%\MiKTeX*`), newest year first, and puts the folder it found behind `PATH` for its own runs. `PDFMD_TEX_BIN` names a folder for an install in an unusual place. `--doctor` prints `NOTE  TeX found at ..., which is not on PATH`. Nothing changes when a TeX engine is on `PATH`.
+- The message of `-e tex` with nothing found now says the engines are not installed "on PATH".
+- `-e lualatex.exe` (and `-e typst.exe,lualatex.EXE`): a trailing `.exe` is dropped from an engine word, so the name Windows shows for the engine works. A word with a path in it is left as written.
+
+### Tests
+
+- `tests/test_tex_bin.py`. `tests.test_calc.PartBuiltAlone` shows Pandoc's own error when its first run fails (it hid it behind `check=True`).
+- Windows with MiKTeX (the non-gating `windows-latex` job, found by a short debug run): the job puts poppler's folder in front of Git Bash's, whose `pdftotext` is xpdf's (no `-bbox`, Latin-1 output); the poppler calls in the tests decode UTF-8 with `errors="replace"`; `test_calc` writes Pandoc's discarded output to a file (Pandoc cannot open `nul`); `test_check` compares paths with `/`; `test_embedding` passes `-e lualatex`, not `lualatex.EXE` (which pdfmd now also accepts). Test code and CI only.
+
+## v3.30.31 — 2026-10-26
+
+Pre-edit state: commit `16fad47` (v3.30.30 + the CLAUDE.md rule).
+
+### Added
+
+- A failed TeX run names its cause when the log has a known signature: a second line under the `WARN ... failed` line, `cause: the LaTeX package soul.sty is missing; install it (tlmgr install soul; Debian/Ubuntu: apt install texlive-plain-generic)`. Known: a missing `.sty` (the package that has it for lmodern, soul, selnolig, lua-ul, luacolor; `tlmgr install NAME` for any other), a missing luaotfload, a corrupt luaotfload font database, an unwritable TeX cache. The signatures come from real logs of an outside reviewer's six cases (2026-10-14). Once per document, not once per engine tried.
+- Not done: the unwritable cache and the corrupt database reach pdfmd as Pandoc's bare `Fatal error occurred, no output PDF file produced!`, the cause is only in the engine's own console output, so those two are named only when the log text is at hand (not through Pandoc). Naming them needs a probe run (a one-page `lualatex` smoke document after such a failure, as `--doctor --deep` already has); queued.
+
+### Tests
+
+- `tests/test_tex_cause.py`.
+- `.gitignore` lists `pdfmd-reviews/` (an outside reviewer's raw logs, kept in the working folder for the classifier; not part of the package: `MANIFEST.in` names the files it ships).
+- Windows `native` CI (first run of the combined tree): `test_doc` reads `--help` output with `errors="replace"`, `test_install_calibre.Detach` and `test_sections.PartRanges` compare paths the way the platform spells them (`Path(...)`, `as_posix()`). Test code only.
+
+## v3.30.30 — 2026-10-26
+
+Pre-edit state: commit `69dc4a6` (v3.30.29). Issue 13.
+
+### Fixed
+
+- The PDF made by `-e calibre` lost its bookmarks with Calibre 9.16 (`tests.test_calibre.Builds.test_a_document` failed on every machine with it since 2026-10-14). The bookmarks were there in what `ebook-convert` wrote: pdfmd's own stamp of the finished PDF (`PdfmdVersions`, `Creator`) copied it with pypdf's `append()`, which drops the whole outline of a PDF whose bookmarks are typed `/Type /Outlines`, as Calibre 9.16 writes them. The stamp clones the document instead.
+- Every `subprocess` call of pdfmd that reads text names its encoding (`utf-8`, undecodable bytes replaced): `text=True` alone decodes with the ANSI code page on Windows, and Pandoc, TeX, `fc-list` and `kpsewhich` write UTF-8, so a byte the page could not decode made the reader thread die and `.stdout` come back as `None` (issue 13: every build stopped in `installed_font_families()` with TeX Live's `fc-list` on the PATH; that call itself was repaired by `ec8cbfe`, unreleased until now). 46 calls in `pdfmd.py` and five helper modules.
+
+### Tests
+
+- `tests.test_partial_provenance.OutlineSurvives`, `tests.test_probes.SubprocessDecoding` (no `run`/`Popen`/`check_output` call with `text=` and no `encoding=`).
+- `tests.test_chem.WhatItCannotConvert` (v3.30.25) runs pdfmd on a Typst route that needs Pandoc, so it is skipped without Pandoc, like its neighbours; the first CI run of the combined tree failed the `native` jobs on it.
+
+## v3.30.29 — 2026-10-26
+
+Pre-edit state: commit `470de88` (v3.30.28). Merged from PR 9 (`cloud/calc-checks`), squashed.
+
+### Added
+
+- `--check` reports the calculator's undefined names (`calc-undefined`, an error): a span, a `::: calc` line or an `{ans}` that uses a name nothing defines, with its line and its part, in document order. A document without a calculator never starts Pandoc for it.
+- `--check` notes a name defined more than once (`calc-redefined`, severity `note`, a third severity that is counted and never fails `--check`, not even with `--strict`). A normal build says nothing about it.
+- `calc: {export: FILE}`, `--calc-export FILE`, `PDFMD_CALC_EXPORT` (for `-j` workers): after a build, `name,value,digits` with one row per name, sorted, `%.17g`, written atomically, readable back as a `constants` file. Not written without names, with `calc` off, after a failed build, or for a part built alone without the seed. `--attach-source` and `--embed-metadata files` leave it out unless it is also read. A `--setup` row (`options.calc.export`), the inventory entry, the help topic, README and recipes.
+
+## v3.30.28 — 2026-10-26
+
+Pre-edit state: commit `b065576` (v3.30.27). Merged from PR 11 (`cloud/partial-provenance`), squashed; it met 3.30.23's partial history in `pdfmd.py`, resolved by keeping both.
+
+### Fixed
+
+- A partial parts build (`report#intro`, `@60`) keeps the provenance of its PDF (Creator suffix, `PdfmdVersions`, `PdfmdBuildDate`, and a new `PdfmdPartial` naming the parts) and never stamps the `.md`. Word and OpenDocument files never carried these properties. With `stamp: {partial: true}` the "partial" entry of the history (3.30.23) is still written, after the PDF's provenance, by one function (`stamp_build`) that replaces `stamp_unless_partial`; the cache route's intermediate `.tex` stage writes neither.
+- The snapshots of one build are one `BACKUP` line (`report.md + 6 parts -> .backups/, parts/.backups/ (...)`); the per-file lines follow only with `--verbose`.
+
+### Tests
+
+- `tests.test_partial_provenance`, `tests.test_backup_summary`.
+
+## v3.30.27 — 2026-10-26
+
+Pre-edit state: commit `b575748` (v3.30.26). Merged from PR 10 (`cloud/csv-notes`), squashed.
+
+### Fixed
+
+- The note under a cut `.csv` table states the fact only, only for the dimension that was cut (it said "2 of 2 columns" when no column was cut), without code spans. The advice moved to a once-per-table `WARN` on stderr.
+- `--extract-inline-csv`, `--expand-tables` and `--check` know the bare `::: csv`.
+- The stray `unittest.main()` in the middle of `tests/test_csv_table.py` is at the end.
+
+### Added
+
+- `note=short|off|full` (default `short`): a div's `note=`, `csv: {note}`, `--csv-note`, `PDFMD_CSV_NOTE`, a `--setup` row, the inventory entry, the help topic, README and recipes; in the Lua filter and in the built-in renderer. `full` is the only mode that keeps code spans (other writers get them as Pandoc writes them).
+
+## v3.30.26 — 2026-10-26
+
+Pre-edit state: commit `9b054bb` (v3.30.25). Merged from PR 8 (`cloud/portability`), squashed.
+
+### Fixed (Windows)
+
+- `report#section/sub` kept its slash on Windows (`Path()` turned it into a backslash, so the section was never found).
+- A pager or editor typed with a Windows path (`C:\Program Files\...`) keeps its backslashes (`shlex` in POSIX mode ate them): `split_command()`.
+- The calculator's seed run wrote Pandoc's output to the null device; Pandoc's binary writers cannot open `NUL` on Windows. It writes to a file in the scratch folder.
+- A file with a kept source (`--keep-source`) whose line ends had become CRLF (git's `autocrlf`, an editor) "kept no pdfmd source", `--restore` could not give it back, and it was reported as edited. The trailer is read as LF text and the hash ignores the difference.
+- The ASCII filter's helper (`--to ascii`) never started on Windows: its command and paths went through Pandoc's metadata with their backslashes. The paths have forward slashes, and the `WARN` says why the helper did not answer.
+- TeX engines were started with a temporary folder under its Windows short name (`C:\Users\RUNNER~1\...`); the engine reads its command line as TeX, where `~` is active, and MiKTeX's LuaLaTeX opened no file. The label draft pass, the pictures drawn for Word files and the cache build failed there. `tex_argument()` gives the long name.
+- A picture's folder was never taken out of a Word description on Windows.
+- `--verbose` says how the label draft pass ended when it left no `.aux`; `provide_writable_places` creates the temporary `texmf-var`/`texmf-config` folders it points at.
+- A busy disk image (macOS, `Calibre` install) is detached again before it is forced: four tries a second apart, then `-force`.
+
+### Added
+
+- The built-in parser (no Pandoc) draws an HTML `<table>`'s `colspan` and `rowspan` (`pdfmd_ansi/native.py`). Golden tests.
+
+### Changed (CI, tests)
+
+- The lint job runs `ruff check --select F` on the code and the tests (two unused locals, seven unused imports, a duplicated dictionary key; no behaviour changes). The Windows job (`windows-latex`) installs poppler, the fonts the tests name, and runs with Python's UTF-8 mode.
+- The tests: the OS separator in what a run prints, Lua paths in forward slashes, `TEXINPUTS` with `os.pathsep`, a file to discard instead of `NUL`, line ends as Pandoc wrote them, a closed `.docx` before the folder is removed. Two `test_readonly_home.Builds` tests are skipped on Windows (MiKTeX's LuaLaTeX stops in luaotfload when LOCALAPPDATA is redirected).
+
+## v3.30.25 — 2026-10-26
+
+Pre-edit state: commit `abb652a` (v3.30.24). Issue 12.
+
+### Fixed
+
+- siunitx 2 style `\SI{1.8e-5}{}` and `\qty{1.8e-5}{}` (an empty unit) print the number alone, as `\num{1.8e-5}` does; `\si{}` and `\unit{}`
+  print nothing; the same for `\SIlist`, `\SIrange` and their `qty` names. The empty unit made the converter refuse the command, so in
+  a Typst, HTML or text output the command was left out of the text without a word, and a formula holding one (even beside a `\ce`) stayed raw
+  TeX, with a warning that only blamed the missing `pdftocairo`.
+- A command or a formula the converter refuses is named in one `WARN` with the reason (`[pdfmd] WARN \SI{3}{\bogus} cannot be converted
+  (siunitx unit \bogus is not known); it is left out`), once per command, for the outputs the LaTeX filter does not run for.
+
+### Tests
+
+- `tests.test_chem.Siunitx.test_an_empty_unit_prints_the_number_alone`, `tests.test_chem.WhatItCannotConvert`.
+
+## v3.30.24 — 2026-10-25
+
+Pre-edit state: commit `de9c29a` (v3.30.23).
+
+### Added
+
+- `history:` is accepted in `pdfmd-options` (a document, a metadata file, the config) as another name for `stamp:`: the build history is that
+  one setting (`enabled`, `store`, `mode`, `scope`, `packages`, `partial`, ...), not a second one. `history: {store: file, partial: true}` is
+  `stamp: {store: file, partial: true}`; a field both set is taken from `stamp`. Older pdfmd versions do not know `history:`, so a shared
+  metadata file that must work with them keeps `stamp:`.
+
+### Tests
+
+- `tests.test_partial_history.HistoryAlias`.
+
+## v3.30.23 — 2026-10-25
+
+Pre-edit state: commit `4e38e85` (v3.30.22).
+
+### Added
+
+- **Draft builds in the history.** The `.hst` held full builds only: a build of some parts or sections (`pdfmd @60`, `doc#section`) writes no
+  BUILD NOTES line, and nothing took its place. With `pdfmd-options: {stamp: {partial: true}}` (or `--stamp-partial`; `--no-stamp-partial`
+  overrides a document that set it; a `--setup` row, `options.stamp.partial`) and the history in a file (`store: file` or `both`), such a build
+  leaves a new kind of entry, `partial`:
+  `... | partial | parts 50-calculations, 60-discussion; changed: 60-discussion; with nulabreport v1.28.20, pdfmd v3.30.23 | parts=... changed=... new=... shas=... out=...`.
+  `changed` compares each part's text with the last entry that saw it; a full build in parts mode now records every part's hash (`shas=`) for
+  that, and a part no entry has seen is `first seen` (`new=`). `--history` lists the entries as `partial`. Off by default (a history that
+  held full builds only gains lines); older pdfmd versions keep a `partial` line as a comment. A `partial` entry has no `sha`, so it is
+  never offered by `--history-restore`.
+
+### Tests
+
+- `tests.test_partial_history` (the entry round trip, the key, parts built and changed against a full build, first seen, off by default,
+  the flags, a section of a plain document).
+
+## v3.30.22 — 2026-10-25
+
+Pre-edit state: commit `85a9283` (v3.30.21).
+
+### Added
+
+- **A range of parts:** `pdfmd @45-60` (or `--section 45-60`, `doc#45-60`) builds every top-level part numbered from 45 to 60, ends included,
+  whether or not a part has that exact number; a reversed range is the same, and it joins other names (`@10,45-60`). A part literally named
+  `45-60` still wins, and a range that covers no part is the usual "matches no part" error. Only digits on both sides count, so
+  `10-introduction` is a name as before.
+
+### Tests
+
+- `tests.test_sections.PartRanges`.
+
+## v3.30.21 — 2026-10-25
+
+Pre-edit state: commit `b20d62b` (v3.30.20).
+
+### Fixed
+
+- **A build printed `{ans}` lines and bare names instead of numbers (a regression of 3.30.20).** The new `.calc-table` handler was chained
+  to the `::: calc` handler with `calc_div(div) or calc_table_div(div)`, and `or` keeps only the first of the two values the first handler
+  returns, so the walk went into the div it had just written and the second pass counted its places twice: every span and `{ans}` line after
+  the first calc div failed with "the passes disagree about this place" (LR5: 71 lines in the Calculations, the numbers of the Discussion as
+  code). The two results are passed on now.
+
+### Added
+
+- When three or more places of a document could not be evaluated, the calculator ends with one line,
+  `WARN  calc: 21 places were not evaluated (each is above); the output shows their code or text where the numbers belong`, so a build
+  that failed on a whole section is not mistaken for one that printed a single odd span (`--strict` already fails on any WARN).
+- A `.calc-table` caption can be written inside the div: a line `Table: Student's *t*, 95%` (or `: ...` after a blank line); `caption="..."` still works.
+
+### Tests
+
+- `tests.test_calc.Statistics`: a silent span glued to an `{ans}` line (the four-line example of the report), the summary line, the three
+  caption spellings.
+
+## v3.30.20 — 2026-10-25
+
+Pre-edit state: commit `4f34b63` (v3.30.19).
+
+### Added
+
+- **Statistics in the calculator:** `sum mean median`, `var sd stdev sem` (sample, n - 1), `rsd` (relative standard deviation in percent),
+  `ci(0.95, x1, x2, ...)` (half-width of the confidence interval, t * s / sqrt(n), through the existing `qt`), `gstat(x1, x2, ...)`
+  (Grubbs' G) and `gcrit(n, alpha)` (its two-sided critical value; agrees with SciPy to 10 figures). They take names as well as numbers:
+  `` ~`R_E4 / mean(R_A, R_B2)`{=0dp} times lower `` works as written. These names stay free for a variable (`mean = 5` and `mean(1, 3)`
+  side by side, so no existing document breaks); the older function names are still reserved.
+- **`::: calc-table`, a line `t# tinf`, `:::`** (or `::: {.calc-table names="t# tinf"}`): a real table (Pandoc `Table`, so the document's table styling, widths and numbering apply)
+  of calculator names with their values, in the digits each was defined with (`digits="3dp"` for all). The names are the text of the div or `names=`: names and patterns
+  (`*` any characters, `?` one, `#` a run of digits, so `t#` leaves out `t_welch` and `tinf`), a pattern in natural order (t2 before t10); `labels="t1=$t_{1}$; V=Volume"` by name or one per row in order (Markdown and math
+  work); `head="Symbol; Value"` or `none`; `caption="..."` (Markdown); the identifier, other classes and attributes go to the table, so
+  `{#tbl:t}` can be cited. A name counts as defined at the place of the div, as for a span there; in a part built alone the names of the
+  parts above it are known (3.30.19). A name that is not defined, a pattern with no match, a value that cannot be computed: one `WARN
+  calc-table` naming it; a div without names prints its own code. `::: {.calc-table t*}` is not a div for Pandoc (braces take only
+  `.class`, `#id`, `key=value`) and gets one WARN with the right spelling instead of printing as text.
+
+### Tests
+
+- `tests.test_calc.Statistics` (13): the summary functions against Python's `statistics`, `ci` and `gcrit` against SciPy, the sentence of a
+  Discussion, bad calls (one WARN each, the code kept), the new names still free for a variable and the old ones reserved, the table
+  (natural order, labels by name, header, caption and identifier on a real `Table`, the place of the div, digits, everything that goes
+  wrong, the malformed spelling), and the detection for a document with only a table.
+
+## v3.30.19 — 2026-10-24
+
+Pre-edit state: commit `65dc1da` (v3.30.18).
+
+### Fixed
+
+- **A part (or a section) built alone knows the calculator's names from what stands above it.** `pdfmd @60` printed nothing where
+  `` `mean_A`{=2dp} `` had been (the name is defined in part 50), and the build was silent about it. Before the real pass pdfmd now has
+  Pandoc read the scaffold and the parts left out that stand above the last one built, with `calc.lua` only (`-t native -o /dev/null`,
+  about a second for 128 names); `calc.lua` writes every name with the value of its last definition (`%.17g`, full precision) and its
+  digits (`-M pdfmd-calc-dump=FILE`), and the build reads the file back (`-M pdfmd-calc-seed=FILE`) as definitions above everything in the
+  document, after the constants file. A section of an ordinary document (`doc#discussion`) does the same with the sections above it. The
+  build says `NOTE  calc: 128 names taken from parts 10-50 (evaluated, not typeset)`. Nothing is stored between builds, so nothing is
+  stale. HTML, Word, Typst and the other writers that number the whole document and keep the part already evaluated everything.
+- **A span the calculator cannot evaluate no longer vanishes.** `` `name`{=2dp} `` is a raw inline of the format `2dp` for Pandoc; the
+  filter put that item back, and the LaTeX and other writers drop a raw inline of a format they do not know, so the sentence had a hole and
+  the WARN's "the code is kept" was untrue. The code is kept now (printed as code), with the one WARN, which names the format as written
+  (`` `ghost`{=2dp} ``).
+
+### Added
+
+- `pdfmd-options: {seed-calc: auto|scan|off}` and `--seed-calc MODE` (a `--setup` row under Cache): `off` gives the seeding up. `auto` and
+  `scan` are the same.
+
+### Tests
+
+- `tests.test_calc.PartBuiltAlone`: the dump and seed through the filter alone (the last value of a redefined name at full precision, its
+  digits, a name with no digits); a split report's part 60 built alone against the full build (same text, the NOTE); an unknown name printed
+  as code with exactly one WARN in both builds; the setting in the document and on the command line; a part that redefines a name is not
+  overridden; a part with no calculator and a document without one are built as before; sections above a section (`doc#Discussion`,
+  `doc#Notes`).
+
+## v3.30.18 — 2026-10-24
+
+Pre-edit state: commit `ad8efcd` (v3.30.17).
+
+### Fixed
+
+- **Every file pdfmd rewrites is written atomically**: to a temporary file in the same folder, then renamed over the old one (`os.replace`),
+  so a crash, a full disk or ^C leaves the old file whole. The mode of the replaced file is kept and a symlink is written through. Covers the
+  BUILD NOTES stamp, outputs, `--history-restore`, the backup options, `--extract-tables`, restored attachments, the config and metadata
+  files of `--setup` and `--init-backups --global`, `--init-config`, the places that rewrite a finished PDF, and the built-in renderers. A
+  process killed between write and rename leaves a `.NAME....part` file.
+- **A read-only home, cache or document folder no longer stops a build.** LuaLaTeX failed with `luaotfload: no writeable cache path`, `--cache`
+  crashed on a `PermissionError`, and the import itself died when the home could not be looked into. What cannot be written goes to a
+  temporary folder of the run (the cache folder, `TEXMFVAR`, `TEXMFCONFIG`, also for child processes), with one `NOTE`; Pandoc runs in a
+  temporary folder when the document's folder is read-only, the document's folder staying on `--resource-path` and `TEXINPUTS`.
+- **Probes have a timeout.** A version or capability probe (`pandoc --version`/`--help`/`--list-extensions`, `kpsewhich`, `lualatex`/`typst
+  --version`, the checks after `--install typst|node|d2|tectonic`, the Pandoc reference-document probe) is cut after 10 seconds
+  (`PROBE_TIMEOUT`); one that does not answer counts as "not available" (an `AUTO PROBE` line under `--verbose`). Build commands never get a
+  timeout.
+- **A missing `pdfmd_lua` is loud.** A lone copy of `pdfmd.py` gave silence while the Lua filters did nothing; it is one `WARN lua:` per run
+  now. A document that needs no filter says nothing.
+- **Windows: a font list the console could not decode** came back as `None` and stopped the whole build. `installed_font_families()` and the
+  fontconfig and `luaotfload-tool` calls decode the child's output themselves, replacing what cannot be read.
+
+### Changed
+
+- **CI** (`test.yml`, which `publish.yml` calls; `publish.yml` itself is untouched): a `linux-pandoc` job (Pandoc 3.1.3 and latest, LuaLaTeX
+  and XeLaTeX, the whole suite) and a `golden` job (`scripts/vendor_inkmd.py --check` and the golden test) now gate a release. A `lint` job
+  (`ruff --select F`, 39 findings, none silenced) and a `windows-latex` job (MiKTeX, the whole suite) run but do not gate.
+
+### Tests
+
+- New `tests.test_atomic`, `test_readonly_home`, `test_probes`, `test_lua_missing`; `test_auto_states` no longer
+  flakes when a scratch folder name ends in `a`.
+- From the cloud session (branch `cloud/robustness-ci`, PR 7). The `windows-latex` job fails on 55 tests and 14 errors of 1652 (Windows paths
+  in test Lua files, a `\` in `--section`, MiKTeX refusing to run as an administrator, missing fonts); it was the first whole-suite run on
+  Windows and the job does not gate.
+
+## v3.30.17 — 2026-10-24
+
+Pre-edit state: commit `fbe5640` (v3.30.16).
+
+### Added
+
+- **`--to ansi` / `--view` draw spanning table cells.** A cell with a colspan or rowspan is drawn across the merged columns and rows, its text
+  wraps to the merged width, the borders inside it are left out and each crossing uses the box character its neighbours ask for. A table
+  without spans is drawn exactly as before.
+- **Coloured code.** Fenced code in python, bash/sh/shell/zsh, json, yaml, c, cpp, java, javascript/typescript, rust and go (and the usual
+  aliases) gets keywords, strings, comments and numbers in four 256-colour codes, with no dependency. With colour off (`NO_COLOR`,
+  `--color never`, a pipe) or an unknown language the block is exactly as before.
+- **Stacked display math.** A `$$..$$` that is the whole paragraph is drawn on several rows where it has `\frac`/`\dfrac`/`\tfrac`, `\sqrt`
+  (with an overbar, and `\sqrt[n]{x}`), big operators with limits (`\sum \prod \coprod \int \iint \iiint \oint`) and `\lim`/`\max`/`\min`/
+  `\sup`/`\inf` with the limit below. A formula with anything that cannot be stacked, or wider than the line, prints its linear form whole,
+  never half stacked. Inline math stays linear.
+- **`options.pager_command`** (`pdfmd-options: {pager_command: "bat --paging=always"}`, also spelled `pager-command`; a word list works too),
+  the pager of `--view`. Order: `$PDFMD_PAGER`, `$PAGER`, the setting, `less -FRX`. `--setup` row `options.pager_command`, also offered per folder.
+
+### Tests
+
+- `tests.test_ansi` extended with golden tests (a header spanning two columns, a rowspan of 2, both at once; the code colours; stacked math).
+  A fuzz run of about 9000 random span tables had no misaligned line.
+- From the cloud session (branch `cloud/ansi-limits`, PR 6). Not verified: a real terminal and pager (checked through a pipe). The no-Pandoc
+  tier (`pdfmd_ansi/native.py`) builds tables without spans.
+
+## v3.30.16 — 2026-10-24
+
+Pre-edit state: commit `05c6e73` (v3.30.15).
+
+### Fixed
+
+- The built-in renderers (inkmd, md2pdf) set `b5`, `a6`, `b4`, `b6`, `executive`, `folio`, `a0` to `a2`, `c4` and `c5` as A4 in silence;
+  they have real sizes now and honour `landscape` (`papersize: a4,landscape`, `classoption`, `geometry`). A paper they do not know is a
+  `NOTE` and A4.
+- `pdfmd --doc changelog 1` returned a block hidden in an HTML comment: `--doc` skips HTML comments now, and `--doc search` skips the
+  README's contents list.
+- `docs/agents.md` counted its commands wrongly and called attaching the source the default (it is off unless asked). The README's
+  `pdfmd --doc readme tectonic` example and its sample search output were invented; they are real output now. The README no longer calls
+  macOS's Python 3.9 too old.
+- The zipapp carries the documents, so `pdfmd --doc` works in a `.pyz`. `pyproject.toml` requires `setuptools>=77` (PEP 639 license fields).
+
+### Changed
+
+- README: a contents list at the top and a shorter "Why".
+- `pdfmd_docs.version()` derives the version the docs name from `PDFMD_VERSION`, and `tests.test_docs_consistency` fails on drift.
+- `CHANGELOG.md` header: the patch rule and the `PDFMD_VERSION` location are described as CLAUDE.md states them, and the "why this starts
+  at 2.0.0" paragraph is visible text instead of a comment.
+
+### Removed
+
+- Four unused functions: `pandoc_missing_message`, `kpsewhich_path_text`, `normalize_stamp_value`, `normalize_backup_value`.
+
+### Tests
+
+- New `tests.test_docs_consistency`; `test_native`, `test_doc` and `test_packaging` extended.
+- One reviewer finding was skipped as wrong: the stamp is written before the backup on purpose (a backup per compile would flood the folder).
+- From the cloud session (branch `cloud/review-fixes`, PR 5). Not verified: md2pdf with `executive` and `folio`.
+
+## v3.30.15 — 2026-10-24
+
+Pre-edit state: commit `c43923e` (v3.30.14).
+
+### Added
+
+- **An indent div takes its value in the class word.** `::: .indent=3in`, `::: indent=3in`, `::: indent-3in`, `::: {.indent-3in}` and
+  `::: {.indent=3in}` (and `::: .indent`, `::: .noindent`) all mean `{indent=3in}`, through the same length parser (false, true, a number,
+  units). Pandoc reads the unbraced forms as a single class word, so only the braced `{indent=...}` carried a value before.
+- **A near miss warns.** A class that looks like an indent div but is none of the accepted spellings (`.indent3in`, `.noindent=2em`) gets one
+  `WARN  indent: '<class>' is not an indent div; write ::: {indent=3in} (or ::: noindent)` per run and is left as written. A project's own
+  `.indented`, `.indentation` and `.indent-block` are not looked at.
+- **A bare `::: csv` builds a table** like `::: {.csv}`, in the Pandoc route and in the built-in renderer, when it holds inline data.
+  `file=` and `align=` still need the braces; `::: csvfile` and `::: csv-x` do not match.
+- **`csv: off`** (`pdfmd-options: {csv: off}`, short for `csv: {enabled: false}`), `--csv` / `--no-csv` and `PDFMD_CSV` (for `-j` workers)
+  switch the csv-in-a-div feature off: the filter is not added and the div stays a plain div with its text, with no WARN, also in the
+  no-Pandoc renderer. A mapping such as `csv: {rows: 30}` still works and leaves tables on. The command line wins over the options.
+  `--setup` row `options.csv.enabled`.
+
+### Tests
+
+- New `tests.test_csv_switch` (17 tests); `tests.test_indent` extended (every accepted spelling, a measured x position in a real PDF, near
+  misses that warn, `.indented` that does not). One assertion fixed: it now accepts Pandoc 3.1's `\hypertarget` as well as `\label`.
+- From the cloud session (branch `cloud/small-patches`, PR 4).
+
+## v3.30.14 — 2026-10-24
+
+Pre-edit state: commit `2c0b9a3` (v3.30.13).
+
+### Added
+
+- **Room around a `::: calc` div, and optional centring.** The block ran straight into the paragraphs above and below it. It has `0.75em`
+  of room on each side now (`calc: {space: 0.75em}`, `--calc-space LENGTH|off`, `PDFMD_CALC_SPACE`; pt, mm, cm, in or em; a `--setup` row):
+  `\par\addvspace{..}` for LaTeX and Beamer (it merges with the paragraph skip next to it instead of adding to it), `#v(.., weak: true)`
+  for Typst, vertical padding on a wrapping `<div>` for HTML and the other HTML writers. `calc: {align: center}` / `--calc-align center`
+  (left is the default; a `--setup` row) centres the lines: a `\begingroup\centering` group, `#align(center)[..]`, `text-align: center`.
+  Markdown, Word and the plain writers get the block as before. A hidden `::: {.calc .hide}` div has no room, as it prints nothing.
+- **Ctrl-C is one line.** An interrupted run printed a page of traceback. It prints `Interrupted (Ctrl-C).` and exits with status 130 now
+  (`main()` wraps `run_main()`); Pandoc and the engines get the signal from the terminal, and the temporary folders are removed.
+
+### Tests
+
+- `tests.test_calc.Switches.test_a_calc_div_has_room_around_it_and_can_be_centred`, `test_a_bad_space_or_align_is_an_error_and_the_other_writers_get_nothing`;
+  the exact argument lists now carry `pdfmd-calc-space=0.75em`; `tests.test_interrupt`.
+- Measured in a LuaLaTeX PDF: the gap between the paragraphs around a calc line grew by the room set (2 cm: +113 pt), and `align: center`
+  moved the block's left edge from the margin to the middle of the line.
+
+## v3.30.13 — 2026-10-24
+
+Pre-edit state: commit `67e53d2` (v3.30.12).
+
+### Added
+
+- **A trailing comment in a statement block.** In a ```` ```{=calc} ```` block, a `::: {.calc .hide}` div and the constants file a `#` starts
+  a comment to the end of the line, so `M_Mg <- 24.305 # g/mol` defines `M_Mg`; a whole-line `#` was skipped already. Before, the `#` was read
+  as arithmetic: the WARN "'#' is not arithmetic" and an undefined name for every later use. `--` is not a comment (it can be a double minus).
+
+### Tests
+
+- `tests.test_calc.Blocks.test_a_hash_starts_a_comment_at_the_end_of_a_line_too`.
+
+## v3.30.12 — 2026-10-24
+
+Pre-edit state: commit `52f3d0f` (v3.30.11).
+
+The calculator's constants file is part of the source that `--attach-source`, `--keep-source` and `--embed-metadata files` carry.
+
+### Fixed
+
+- **A constants file named in `metadata.yaml` was left out.** `calc: {constants: tables/constants.csv}` was found only when the document's own
+  text mentioned the path (the scan for referenced files), so a file named in a metadata file, the usual place for a report, was not attached
+  and `pdfmd --restore` gave back a source that failed with "no file". It travels now like the `.hst` history file (`add_calc_constants`),
+  and comes back under the same relative path. A constants file outside the document's folder gets the usual "outside" warning.
+
+### Tests
+
+- `tests.test_calc.Blocks.test_the_constants_file_named_in_a_metadata_file_travels_with_the_source`.
+
+## v3.30.11 — 2026-10-24
+
+Pre-edit state: commit `2e35666` (v3.30.10).
+
+Definitions in bulk for the calculator: a report that needs 14 constants (t values, a stock concentration, molar masses) kept them as a run of
+hidden `` `name = value`{=} `` spans on one line (issue file 2, B).
+
+### Added
+
+- **A block of statements.** ```` ```{=calc} ```` (Pandoc's native raw block, lines intact), one statement per line, each as the text of a
+  `{=}` span: `name = value` or `name <- value` stores and prints nothing, a line with `{ans}` prints (one paragraph per line), blank lines and
+  `#` lines are skipped, a failing line is kept as code with one WARN and the rest goes on.
+- **```` ```{=} ```` works as ```` ```{=calc} ````.** Pandoc does not read an empty raw format as a block: it is a paragraph with one code
+  span whose line breaks are gone. `calc.lua` finds those paragraphs and reads the lines again from the input files Pandoc was given
+  (`PANDOC_STATE.input_files`), matching them by their text in document order; a fence shown inside a longer fence is not touched. From
+  standard input there is no file: one WARN says to write `{=calc}`.
+- **`::: {.calc .hide}`** (also `.hidden`): the same statements, nothing printed. Its lines are read as Markdown.
+- **`` `code`{=calc} ``** is `` `code`{=} `` (Pandoc's own raw attribute). A ```` ```{.calc} ```` code block stays a code block, never calculated.
+- **`calc: {constants: FILE}`**, `--calc-constants FILE`, `PDFMD_CALC_CONSTANTS`, a `--setup` row: a CSV (comma, semicolon or tab; columns
+  `name,value[,digits[,note]]`; header row optional; `#` lines skipped) read before the document, found beside the document, beside its
+  metadata files, then in the current folder. The `digits` column is the format that name remembers for `{subs}` and a bare `` `t18`{=} ``.
+  pdfmd turns the file into statements and passes them as `-M pdfmd-calc-constants`; the document defining a name again gets the usual WARN.
+- The filter is also added for a document that has only such a block.
+
+Tests: `tests.test_calc.Blocks` (12: the block, the empty-format fence from a file and from standard input, a fence inside a longer one,
+fourteen constants, the hidden div, failing lines, detection, the constants file by option, flag and variable, a semicolon file, the errors).
+README "Calculations inside the text" 6, `docs/recipes.md` 1.11.
+
+## v3.30.10 — 2026-10-24
+
+Pre-edit state: commit `735569e` (v3.30.9).
+
+The calculator gets the normal and Student's t distributions, for a lab report that needs a 95 % two-tailed t at 13, 16, 18, 93 or
+13.947 degrees of freedom, none of which a printed table lists.
+
+### Added
+
+- **`qt(p, df)`, `pt(t, df)`, `qnorm(p)`, `pnorm(z)`** in `pdfmd_lua/calc.lua`, lower tail as in R, no library. `qnorm` is Wichura's AS 241;
+  `qt` inverts the incomplete beta function (continued fraction, bisection on the tail so a small `p` keeps its figures), exact for 1 and 2
+  degrees of freedom, and a Cornish-Fisher series above 1000. `df` may be a fraction or `Inf` (`qt(0.975, Inf)` is `qnorm(0.975)`), a name
+  works (`qt(0.975, df_w)`). `p` outside (0, 1) or `df <= 0` keeps the text with one WARN. The constant `Inf` is new.
+- Accuracy against R 4.6.1 and SciPy: `qnorm` and `pnorm` about 1e-15; `qt` about 1e-12 (3e-11 for `p` near 1e-12); `pt` about 1e-12 up to
+  1000 degrees of freedom and 1e-9 above. `qt(0.975, df)` equals R's to the 12 figures it prints for df 1, 2, 3, 6, 8, 9, 10, 13, 16, 18, 93,
+  96, 13.947016149 and Inf.
+- **Changed:** `qt`, `pt`, `qnorm`, `pnorm` and `Inf` are now built-in names, so a variable called `pt` is refused like `sin` (it was free
+  before; the calculator is unreleased).
+
+Tests: `tests.test_calc.Distributions` (R's table, 105 SciPy values, `Inf`, the symmetry, a name as df, the domain errors). README, the
+docstring.
+
+## v3.30.9 — 2026-10-24
+
+Pre-edit state: commit `cbcd7a5` (v3.30.8).
+
+A `::: calc` div has no first-line indent. The author wrote `::: noindent` around every calc block of a report whose document indents
+its paragraphs; the div now does it itself.
+
+### Added
+
+- **`calc: {noindent: true}`, on by default.** `pdfmd-options: {calc: {noindent: false}}` gives the div the document's own indent again;
+  `--calc-noindent` / `--no-calc-noindent` (the command line wins), `PDFMD_CALC_NOINDENT` for `-j` workers, a `pdfmd --setup` row.
+  `calc.lua` puts `indent="false"` on the finished div and `indent.lua` (now also added whenever a calc div is in the text and the
+  calculator and this option are on) does the rest per writer: LaTeX and Beamer `\begingroup\setlength{\parindent}{0pt}` ... `\endgroup`,
+  Typst a `#set par(first-line-indent: 0pt)` block, HTML a `text-indent` style. Markdown, Word and the plain-text writers get no attribute
+  and no NOTE (Word follows with the indent item queued for docx/odt). An `indent=` or `.indent` / `.noindent` on the same div wins, and
+  an outer `::: noindent` works as before. The default is on because the `::: calc` div was never published (3.30.6 onward).
+- A div that carries both classes is written `::: {.calc .noindent}`; `::: calc noindent` is not a Pandoc div (one bare word only) and is
+  left as text.
+
+Tests: `tests/test_calc.py` (the default, an `indent=` and `.indent` that win, the option, the flags, the variable, other writers) and a
+real LuaLaTeX PDF: body text starts at 86.9 pt, the calc lines at 72.0 pt. README "Calculations inside the text", `docs/recipes.md` 1.11.
+
+## v3.30.8 — 2026-10-24
+
+Pre-edit state: commit `56fe65a` (v3.30.7).
+
+Two fixes and three additions to the calculator, found converting a whole Calculations part of a real lab report (about 130 `{ans}` lines)
+to `{=}`, `{ans}` and `::: calc`.
+
+### Fixed
+
+- **A `` `...`{=} `` span inside a `::: calc` div sees the definition above it, not the last one.** The div's lines were registered before
+  the spans in them, so in `a = 1 + 1 = {ans:1dp}, so `a * 10`{=}` followed by the same line with `3 + 3`, both spans took the last `a`
+  (60 twice, no WARN). Lines and spans are now read together, line by line, in the order of the text, and the div no longer hands its
+  paragraphs to the document-wide pass a second time.
+- **A `::: calc` line may carry anything after its last `{ans}`.** `y = 2 + 2 = {ans:1dp} ppm \ce{Ca^2+}` (raw TeX), a superscript, bold,
+  a link or `$..$` after the value used to leave the whole line as written, `{ans}` and all. Only the text up to the last marker has to be
+  plain; the rest is copied as it is. Formatting before the last `{ans}` is still refused with the WARN.
+
+### Added
+
+- **More than one `{ans}` in a span or a line.** After text that does not end in `=` it repeats the value just shown in its own format
+  (`= {ans:1dp}, so {ans:0dp}`); after text that ends in `=` it is a new calculation whose expression is the longest tail of that text
+  that reads as one (`so round(n) = {ans:0dp}`; `so k = round(n) = {ans:0dp}` also stores `k`).
+- **`{subs}`: the expression with the names replaced by their values.** `ppm1 = C_dil * V / 100.0 * 40.078 * 1000 = {subs} = {ans:2dp} ppm`
+  prints `... = 0.002039 * 34.41 / 100.0 * 40.078 * 1000 = 28.12 ppm`. Each name shows the digits it was defined with (a hidden span's use
+  `calc: digits`); the computation always uses the full values. Literals, operators, functions, `pi` and `deg` stay as typed; a negative value
+  gets parentheses (`(-0.5)^2`) unless nothing before it could be read as a sign. `calc: {subs: true}` (also `--calc-subs` /
+  `--no-calc-subs`, `PDFMD_CALC_SUBS`, a `pdfmd --setup` row) puts the copy before every `{ans}` that follows an expression with names; a
+  lone name, an expression without names and a repeated `{ans}` get none. `{subs}` forces it on a line, `{nosubs}` or `{subs:off}` stops it.
+- **`<-` assigns like `=`**: `` `t18 <- 2.10092204`{=} ``, `ppm1 <- C_dil * V = {ans:2dp}`.
+
+The Unicode operators (`×`, `·`, `÷`, `−`) are now read by the tokenizer itself (the parser needs byte positions for `{subs}`). Queued, not
+done: `qt(p, df)` and `qnorm(p)`.
+
+## v3.30.7 — 2026-10-24
+
+Pre-edit state: commit `230ff0b` (v3.30.6).
+
+### Fixed
+
+- **A partial build lists its metadata again.** `pdfmd @10,40` (or `report#section`) printed `FOUND nulabreport.lua, 2 parts` and
+  `DEFAULTS packages mhchem`, without the metadata file, the preamble, the global metadata or the balanced tables a full build lists.
+  The files were used all along (the Pandoc command had them); only the summary was wrong. The hidden pass over the whole document, which
+  gives the left-out parts their numbers, printed its own summary to nowhere and emptied the items already recorded. The summary is now saved
+  before that pass and put back after it (`AutoLog.snapshot` / `restore`). Test: `tests/test_autolog.py` (`Builds`).
+
+## v3.30.6 — 2026-10-24
+
+Pre-edit state: commit `1725405` (v3.30.5).
+
+### Added
+
+- **`{ans}`: the calculator prints the text it was given.** Inside a `` `...`{=} `` span, `` `V = 20.60 - 0.00 = {ans:2dp} mL`{=} `` becomes
+  "V = 20.60 - 0.00 = 20.60 mL" (the text as typed, `{ans}` replaced); the expression is what stands between the last `=` before `{ans}` and that
+  `= {ans}`, and what stands before it is a label. `` `2-4={ans}`{=} `` works unspaced and prints as typed. Several `{ans}` may share a span.
+- **Names.** A plain identifier on the left (`C_EDTA = ... = {ans}`, or the word after a `:` `;` `,` of a label: `Run 1: V = ...`) is stored with the
+  FULL value, not the displayed one, so later calculations cannot drift from what the page shows. `` `A = 4 - 2`{=} `` only stores (prints nothing);
+  `` `A`{=} `` and `` `A * 2`{=} `` print values. A name is found anywhere in the document, parts included (Results may cite Calculations): the
+  nearest definition above its use, else the first below; a name may be defined again; a cycle, an unknown name or a name that is a function or
+  constant (`pi`, `sqrt`) is a WARN and the text is kept. A stored name remembers the digits it was given.
+- **Number formats.** `{ans:4sf}` four significant figures (trailing zeros kept: 20.60; the digits before the point are never dropped, 1049 at 3sf is
+  1049; scientific only below 1e-6 or from 1e15), `{ans:2dp}` two decimal places, and after a span `` `1/3`{=3sf} `` (Pandoc reads `{=3sf}` as a
+  raw attribute: the filter takes `NNsf` / `NNdp` raw inlines and leaves every other raw format alone).
+- **`::: calc`** (also `::: {.calc}`, `::: {#id .calc}`; the class alone, as in Pandoc) calculates every line that holds `{ans}`, in paragraphs, list
+  items and quotes, without backticks; other lines are plain text; a line with bold, a link or math is left as written with a WARN. The detection
+  adds the filter for the div as well. It is the opt-in form of calculating prose: nothing outside it is read.
+- `--calc-digits 4sf|2dp` (and `PDFMD_CALC_DIGITS` for `-j` workers) and `pdfmd-options: {calc: {digits: 4sf}}` set the default format of a document
+  (unset: as R prints, up to 7 figures); a span's own format wins. `--setup` rows. README "Calculations inside the text" (for anyone writing with it),
+  docs/recipes.md 1.11.
+
+### Changed
+
+- **The calculator's options live under `calc:`** (like `csv:` and `backup:`): `pdfmd-options: {calc: {enabled, digits, round}}`, `--setup` rows
+  `options.calc.enabled|digits|round`. `calc: off` / `calc: false` stays as the short form of `enabled: false`. The flat `calc-round` key of 3.30.4
+  is gone (3.30.4 was not released); `--calc`, `--no-calc`, `--calc-round` are unchanged. A wrong `digits` or `round` is an error naming the key.
+- `tests/test_calc.py`: 33 tests (the new ones: 16 statement forms, 20 formats, the div in its spellings, two placeholders in a line, the warnings,
+  the options, flags and variables, and a PDF in which Results cites a name that Calculations defines in a `::: calc` div).
+
+### Not done (queued)
+
+- Spacing the operators for you (`C=n/V={ans}` printed as `C = n / V = 0.0203`), calculating plain prose without `{=}` or a div, `$..$` math, statistics
+  (mean, stdev, rsd, a t quantile, Grubbs), a check mode for a number already typed, significant-figure tracking, `.qmd` spellings.
+
+---
+
+## v3.30.5 — 2026-10-24
+
+Pre-edit state: commit `2d56ccf` (v3.30.4).
+
+### Fixed
+
+- **A symlink in `parts/` crashed the build** (`ValueError: '...' is not in the subpath of '.../parts'`). `collect_parts()` resolved every part to its real
+  path, so a `.md` file linked into the parts folder, or one inside a linked folder, no longer lay under it and `part_key()` / `select_parts()`
+  could not name it. A part now keeps the path it has in the parts folder (`os.path.abspath`, not `resolve()`), so a linked file or folder is built
+  as a part, in its place in the order and under its link's name. (A folder in `parts/` is always walked: to keep a reference folder beside the parts
+  without building it, name it with a leading `_` or `.`.)
+
+### Added
+
+- **`@` for `#` in the section shorthand**: `pdfmd report@methods`, `pdfmd doc@@yield` (a level-2 heading), `pdfmd @yield` (the folder's only Markdown
+  file), `doc@a+b`. An interactive bash (and some other shells) takes a `#` for the start of a comment and never passes it on, so `pdfmd #10` ran
+  without its argument. A real file whose name has an `@` still wins, as with `#`; `--section` is unchanged. `tests/test_symlinked_parts.py`.
+
+---
+
+## v3.30.4 — 2026-10-24
+
+Pre-edit state: commit `b55a83b` (v3.30.3).
+
+### Added
+
+- **An inline calculator: `` `2026 - 2006`{=} `` becomes `20`.** Inline code followed at once by a bare `{=}` is replaced by its value, in every
+  output format a Pandoc build writes. `pdfmd_lua/calc.lua` has its own small parser and runs nothing (no `load`, no R, no Python), so a document from
+  anybody is safe and nothing asks for trust. Operators: `+ - * /`, `^` and `**` (right to left; `-2^2` is -4), `%` and `%%` (remainder, floored:
+  `-7 % 3` is 2), `//` and `%/%` (floor division: `7 %/% 2` is 3), parentheses, unary minus. `|a - b|` is the absolute value. A `%` that no operand follows is a percent sign, a label and not an operator (`0.5 / 4 * 100%` is 12.5, as a lab report
+  writes it); `×`, `·`, `÷` and `−` are `*`, `*`, `/` and `-`. Numbers: `12`, `.5`, `6.022e23`. Constants `pi` and `deg`
+  (= pi/180, so `sin(30*deg)` is 0.5). Functions (angles in radians): `sin cos tan cot sec csc`, `asin acos atan acot` (`atan(y, x)` is the two-argument
+  arctangent), `sinh cosh tanh asinh acosh atanh`, `sind cosd tand` (degrees in) and `asind acosd atand` (degrees out; `asin(x) / deg` is the same), `exp ln log` (`log(x, base)`), `log10 log2 sqrt cbrt abs sign`,
+  `floor ceil trunc`, `round(x)` and `round(x, digits)` (an exact half goes to the even digit, as in R and Python: `round(2.5)` is 2, `round(3.5)` is 4; `calc-round: away` makes it 3), `min max` (any number of
+  arguments), `hypot factorial`. A trig result closer to 0 than 1e-15 is 0 (`sin(pi)`). The value prints as R does: up to 7 significant digits, `20`
+  and not `20.0`, `0.3` for `0.1 + 0.2`, `1.2044e+24` for a very large one.
+- What the parser cannot evaluate (a name it does not know, a division by zero, `asin(2)`, an unfinished expression, an infinite or undefined
+  result) is kept as the code it was, without the `{=}`, with one `WARN  calc: ...` naming the span and the reason. Inline code without `{=}`, code
+  blocks and a `{=}` anywhere else are never touched.
+- `--calc` / `--no-calc` (and `PDFMD_CALC=on|off`, which is how a `-j` worker gets it) and `pdfmd-options: {calc: off}` (the document, a metadata file or the
+  config file, in that order of precedence after the flag) turn the calculator on or off, with a `--setup` row;
+  `--calc-round even|away`, `pdfmd-options: {calc-round: away}` and a `--setup` row choose how `round()` settles an exact half (default even, like R and Python); the filter is
+  attached only to a document that has a `` `...`{=} `` span. Without Pandoc the built-in renderer shows the span as written. docs/recipes.md 1.11.
+- `tests/test_calc.py`: 88 expressions with their text, 23 failures with their warning, the neighbouring text, code that must stay, the HTML, LaTeX
+  and Typst writers, the detection, the switch (document and metadata file), and real PDFs (a part included) read back with `pdftotext`.
+
+### Not done (queued)
+
+- spellings for `.qmd` (`` `{r} 2 + 2` ``, `{python}`) and an `all` mode that evaluates every
+  arithmetic-only code span.
+
+---
+
+## v3.30.3 — 2026-10-24
+
+Pre-edit state: commit `ab380d1` (v3.30.2).
+
+### Added
+
+- **`--to ansi`: a document as styled text for a terminal.** Bold, italic, inline code, strikethrough, links, headings, ordered and bullet lists, block
+  quotes, code blocks, rules, footnotes (listed at the end), a title block from the front matter, and every table as a box-drawn grid: a rule between
+  rows, a bold header, each column as wide as its widest cell, the alignment the table gives, cells wrapped when the window is narrower than the table,
+  wide (East Asian) characters counted as two cells. The text is wrapped to `--width N`, else the terminal's width, else 120. It is a build like the others:
+  Pandoc reads the document through the usual steps (metadata files, filters, `pdfmd-options`, citations, `\ce`, the CSV tables) and writes its JSON AST,
+  which the new package `pdfmd_ansi/` (a pure function, no other pdfmd module imported) draws; the file is `NAME.ansi`, and `-o x.ansi` selects the format.
+  Without Pandoc the built-in parser (`pdfmd_inkmd`) reads the Markdown instead, with a NOTE: no filters, citations, footnotes or metadata files.
+- **Math as text, level (a).** `MathText` (the converter the built-in renderer uses) gets an ANSI back-end: Greek letters, operators, Unicode sub- and
+  superscripts, `(a+b)/(c+d)`, `√(...)`, variables in italic, a function name after a variable set off by a space (`RT ln K`); a formula alone on its line is
+  centred; one the converter cannot read is shown as its TeX.
+- **`--view`: read a document in the terminal.** = `--to ansi -o -` + a pager. It takes files (a folder: its Markdown files), `-` or a pipe on standard
+  input (written to a hidden temporary `.md` beside the cwd so relative pictures resolve, and removed), else the Markdown files of the current folder, else
+  what is typed or pasted into the terminal (ended with Ctrl-D; a hint says so on standard error). Several files are one stream in the order given, with a
+  dim rule naming each. Each file is built on its own by a child pdfmd into a scratch folder, so all discovery and notes apply; the notes (`OK`, `DEFAULTS`)
+  stay off the screen unless a build fails or `--verbose` is given, every other message goes to standard error. The styling stays when the output is piped
+  (`pdfmd --view x.md | less -R`). `--view -o FILE` saves the file and shows nothing; `--view` with another `--to` is an error.
+- **The pager** (on by default, `--pager` / `--no-pager`, `pdfmd-options: {pager: false}`, a `--setup` row, also in the folder screen): only when
+  standard output is a terminal, through `$PDFMD_PAGER`, else `$PAGER`, else `less -FRX` (`-F` quits at once when the text fits one screen, `-R` keeps the
+  colours; a `less` given without `-R` gets it).
+- **`-o -` is standard output**, for `--view` and for any format built from a file or a pipe: the build goes to a scratch folder and its bytes are copied to
+  stdout; several documents are joined only for text formats (a binary format, `pdf` or `docx`, with several inputs is refused). `--color auto|always|never`:
+  a file and `--view` are styled, `-o -` into a pipe is plain, `NO_COLOR` turns `auto` off, `always` wins over it.
+- Links are `words (address)`, or OSC 8 hyperlinks in a terminal known to draw them (iTerm2, WezTerm, Ghostty, VS Code) when the text is not paged. Text
+  from a document is cleaned before it is shown: control characters (an ESC would start a terminal sequence) and bidi overrides are dropped.
+- `--help view` lists `--view --pager --color --width`; `--view` is on the short help page. The flags are in `pdfmd_setup/inventory.py` (`--pager` is the row
+  `options.pager`; `--view` a command; `--color` and `--width` per run); `pdfmd_ansi` is in `pyproject.toml` and `scripts/build_zipapp.py`.
+
+### Known limits
+
+- A cell that spans rows or columns is drawn in its first cell only. A formula is linear (stacked fractions, roots and sums with limits, and pictures of
+  display math in terminals that show them, are later patches). Raw LaTeX, HTML and Word pieces are left out (`--verbose` counts them). Code is not highlighted.
+- The vendored built-in parser reads a `>` quote that follows a list, after a blank line, as a paragraph plus a one-line quote; that is in `pdfmd_inkmd`
+  (to be fixed upstream in inkmd, the vendored copy is not edited by hand), so it shows only without Pandoc.
+
+Tests: `tests/test_ansi.py` — widths and wrapping, escape-code cleaning, inline styles with and without colour, links, grid widths at several window
+widths (wide characters, shrinking, wrapping), lists/quotes/code, math through the callback; and through the full pipeline: `--to ansi` to a file, `-o x.ansi`,
+`--view` into a pipe, `NO_COLOR` / `--color`, `-o -`, several files, a pipe and `-`, `--to docx` refused, `-o` replacing `--view`, no Pandoc.
+
+---
+
+## v3.30.2 — 2026-10-22
+
+Pre-edit state: commit `814acf5` (v3.30.1).
+
+### Added
+
+- **`--table-keep N` and `pdfmd-options: {table-keep: N}`.** pdfmd passes `-M tablekeep=N` to Pandoc, for a Lua filter that keeps a short Markdown
+  table on one page (nulabreport.lua, v1.28.16: a table of up to `N` body rows moves to the next page whole instead of splitting; its built-in 10 was
+  hard-coded before). `0` lets every table break. Order: the command line (it reaches `-j` workers as `PDFMD_TABLE_KEEP`), then `pdfmd-options.table-keep`
+  (document, metadata files, config), then nothing: pdfmd passes no `-M`, and the metadata's own `tablekeep:` or the filter's default stands. Pandoc's `-M`
+  wins over a metadata file, so the option also overrides a `tablekeep:` there. A value that is not a whole number stops the run with a message naming the
+  file. It is set at all three places the command is built (PDF and the other outputs, the Office route). A row in `pdfmd --setup` (Tables), in the
+  folder screen too. A filter that does not read `tablekeep` ignores it. Tested through the full pipeline: the flag, the option, the metadata key and
+  their order, and a bad value.
+
+---
+
+## v3.30.1 — 2026-10-21
+
+Pre-edit state: commit `5617970` (v3.30.0).
+
+### Fixed
+
+- **The closing line names the PDF, not the `.tex` the cache made on the way.** A build through the cache folder (a part alone, `report#second`, with `cache:` on,
+  as the lab reports have it) printed `OK    report.md > ~/.cache/pdfmd/b888f4388b-report/report.tex  (lualatex)` although the PDF was written beside the source:
+  the nested Markdown-to-`.tex` stage of `convert_via_cache()` recorded its own file as the build's output, and nothing put the PDF back. It is restored after the
+  stage, so the line is `OK    report.md > report.second.pdf  (lualatex)`; `--to latex` still names the `.tex`, and `--verbose` still shows the cache folder (the
+  `CMD` and `TEXDIRECT` lines). Tested with the cache route on, which fails without the fix (`tests/test_build_record.py`).
+
+---
+
+## v3.30.0 — 2026-10-21
+
+Pre-edit state: commit `a030424` (v3.29.36).
+
+### Added
+
+- **A paragraph indent for a stretch of text: `::: {indent=false}`.** A fenced div with `indent=` (`false`, `no`, `off`, `0`; `true`, which is 1.5em; or a
+  length: `2em`, `12pt`, `5mm`, a bare number is em), or the classes `.noindent` / `.indent`, sets the first-line indent of the paragraphs inside it and puts the
+  document's own back at the closing `:::`, so there is no "turn it back on" line to forget. Divs nest (the inner one wins, the outer comes back after it), and
+  the div's `#id` and other classes stay. The new `pdfmd_lua/indent.lua` does it per writer: LaTeX and Beamer set `\parindent` in a `\begingroup` ...
+  `\endgroup`, Typst a `first-line-indent` rule in a content block (not in a `#block`, where it did not reach a paragraph that followed another), HTML and
+  EPUB a `text-indent` style on the div. Pandoc Markdown, GFM and CommonMark keep the div as written; Word, OpenDocument and the rest have no per-block indent,
+  so the text stays and a NOTE says the setting was left out. A value that is not an indent is a WARN and changes nothing. The filter is added only for a
+  document (or one of its parts) that has such a div (`indent_filter_args()`, `INDENT_DIV_RE`); there is no switch, since the div is the opt-in. Found with the
+  calculations of a lab report, where the lines of arithmetic should not be indented but the prose between them should. New `tests/test_indent.py`: the
+  detection, every writer, and real PDFs measured with `pdftotext -bbox` (a plain document and a report in parts). `docs/recipes.md` 1.9.
 
 ---
 
@@ -8260,6 +9750,27 @@ package being built.
   page shape trips the same "wrongly rebalanced" or "wrongly left alone"
   symptom in the other direction.
 
+**Why this starts at 2.0.0, not 1.0.0.** `pdfmd.py` began as a one-line
+`pandoc file.md -o file.pdf` wrapper and was revised many times since — across
+ChatGPT, ChatGPT Codex, Claude Chat, Cowork, and Claude Code sessions — with no
+version marker or changelog kept at any point. `backups/pdfmd.py.bak-*` has
+snapshots from a handful of points in that history, but not from the
+ChatGPT/Codex/Cowork era at all, so reconstructing an honest "v1.x" changelog
+from what's actually on disk isn't possible — only a partial,
+misleadingly-precise-looking one. Decided 2026-09-16 (the author): start real
+changelog tracking now, at 2.0.0, rather than fabricate the gap. If the full
+history ever matters, it would need pulling the actual chat transcripts from
+each of those tools, not guessing from diffs between inconsistent backup
+snapshots.
+
+**Update, 2026-10-05:** an approximate outline of the earlier history has since
+been reconstructed, at the very end of this file (see "Before 2.0.0 —
+reconstructed history"), from the saved Codex transcripts and the surviving
+backup snapshots. It is explicitly NOT reliable: its 1.x numbers are invented,
+snapshot-based entries cover windows of days rather than single changes, and
+anything done in unsaved sessions (other ChatGPT chats, claude.ai, Cowork) is
+missing. Real tracking still begins at 2.0.0.
+
 ---
 
 # Before 2.0.0 — reconstructed history (NOT reliable)