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

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

@@ -2,42 +2,778 @@
 
 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 —
+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.
--->
+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.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.
 
 ---