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

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

@@ -17,28 +17,782 @@ PDFMD_VERSION = "2.0.0"
 `pdfmd --version` prints it. Bump it there and add an entry here in the
 same commit as the change.
 
-**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.
+## 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
 
@@ -8996,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)