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

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

@@ -19,6 +19,279 @@ same commit as the change.
 
 ---
 
+## v3.32.12c — 2026-11-03
+
+Tests only; `PDFMD_VERSION` stays 3.32.12. The second CI run (41546953982) failed in three tests of the 3.31.x-3.32.8 commits, which had never run on CI before; none is a bug in pdfmd:
+
+- `test_tables`: a document with no front matter used to be read as gfm, so its grid and simple tables were "left as they are" with a NOTE. Since 3.32.5 such a table switches the reader to Pandoc's Markdown, and the tables are read (and skipped, if they cannot be CSV) like any other. The gfm test now asks for `--from gfm+fenced_divs` explicitly, and a new test pins the switch (no NOTE, the two `SKIP` lines).
+- `test_cellalign`: Pandoc's Typst writer gives a cell its own alignment (`table.cell(align: ...)`) only from 3.1.13, so the Typst half of the test is its own test and is skipped on older Pandoc (`needs_pandoc(3, 1, 13)`); the HTML half runs everywhere.
+- `test_md_macro`: Pandoc before 3.1.7 wraps a heading as `\texorpdfstring{Head with\n\emph{em}}{...}`; the test looks for `Head with` followed by white space and `\emph{em}`, which both forms satisfy.
+
+## v3.32.12b — 2026-11-03
+
+Tests and lint only; `PDFMD_VERSION` stays 3.32.12. The first CI run of the pushed 3.31.47-3.32.12 commits (run 41540900210) failed in the `native` jobs (no Pandoc), the Windows `which` test and `lint`:
+
+- The end-to-end ranking tests (`test_ranking_bare`, `_layers`, `_lists`, `_generated`) run `pdfmd --stop-at markdown`, which still needs Pandoc: they are skipped where there is none (the `native` jobs). `--which`, the watch pin and the engine tests need none and still run there.
+- `test_ranking_which` compared `.pdfmd/ranking.yaml` where Windows prints `.pdfmd\ranking.yaml`: it builds the path with `Path`.
+- `ruff --select F` (the `lint` job): three unused imports from the kits commits (`io` and `dataclasses.field` in `pdfmd_kits/install.py`, `Source` in `tests/test_kit_install.py`) removed.
+
+## v3.32.12 — 2026-11-03
+
+Pre-edit state: commit `1bb68be`. Entry 3eu (the author: "isn't which already taken? if not, let's use it. whatever. it can just become multi-purpose if needed at some point in future"). Kept in 3.32. Not pushed. Last of the four commits of the line.
+
+`pdfmd --which` explains a choice and builds nothing.
+
+- **`pdfmd --which`** in a folder: `WHICH  bare pdfmd in . builds report.final.md`, one row per Markdown file (what it says: its `priority`, its name's suffix; what happened to it: `BUILT`, `left: name: draft`, `left: priority: never`, `left: older`, `tied`; when it last changed), then `RULES`: the files the settings came from (nearest first, ending in the built-in default), `names`, `by`, and the classes low to high (`pdfmd_ranking.Ranking.describe()`). The tie WARN is printed as in a build; a choice that would stop says so (`would stop: ...`, exit 1). `--newest`, `--all` and `--no-auto priority` act in it as they do in a build.
+- **`pdfmd --which NAME ...`**: which file each name finds, by the same lookup a build uses (`report  ->  report.md`), and the lookup's own error for one it cannot find. Meant to grow: the author wants `--which` to be the one place that says what pdfmd would decide.
+- `--which` is a command in `pdfmd_setup/inventory.py` and in the `modes` topic of `--help`. Tests: `tests/test_ranking_which.py` (rows, rules and their origin, a tie, a stop, `--newest` / `--all`, one file, names, a mistake in the ranking). README, module docstring.
+
+## v3.32.11 — 2026-11-03
+
+Pre-edit state: commit `fada070`. Entry 3eu (the author: "yes, but there should be a new key like `-b all` or smth that will override never keys" and "pdfmd --newest will look at the modification time and render the newest thing"). Kept in 3.32. Not pushed. Third of four commits of the line.
+
+`never` leaves the folder lists, and two flags.
+
+- **`priority: never` (or another word of a class with `exclude`, or a negative number) in `-b`, `-r` and the viewer**: the document is left out of what a folder gives, with one `NOTE` naming what was left out. `draft` and the numbers do not matter there (they only choose one document). A document named on the command line (`pdfmd NAME`, `-r a.md b.md`) is always built. `--no-auto priority` switches the leaving-out off with the rest.
+- **`--all`** (alias `--include-never`; `-b all` could not be the spelling: `-b` takes paths and would read `all` as a file): the `never` documents count again. `-b`, `-r` and `--view` include them; a bare `pdfmd` ranks them as if they had written nothing.
+- **`--newest`**: a bare `pdfmd` (or `pdfmd '#section'`) builds the most recently changed file of the folder, by modification time alone (priority and names are not consulted; `never` documents stay out unless `--all`), with no tie warning: it was asked for. It is honoured even with `--no-auto priority`. With a named file, `-b` or `-r` it does nothing, and says so (a WARN). The default `ranking: {by: [priority, newest]}` uses the time only for documents of equal priority.
+- A `never` in a file name (`report_ignore.md` beside `report.md`) hides it from a bare `pdfmd` only; the lists look at the `priority:` key (reading every name of a big `-b -r` tree for it was not worth it).
+- Both flags are `RUN` entries of `pdfmd_setup/inventory.py`. Tests: `tests/test_ranking_lists.py`. README (*Several documents in a folder*, *A whole folder*), module docstring, `--help`.
+
+## v3.32.10 — 2026-11-03
+
+Pre-edit state: commit `5702fb0`. Entry 3eu UPDATE 2 (the author: "let's make it possible to define ranking.yaml somewhere globally ... living in .pdfmd per directory or in parent directory's .pdfmd" and "all depend on proximity to the file itself"). Kept in 3.32. Not pushed. Second of four commits of the line.
+
+The words of `priority`, and their order, are settings.
+
+- **`ranking`**: classes of words on a ladder (`classes: {fruit: {words: [cherry, banana], above: numbers}}`: banana beats cherry, every fruit beats every number, `final` still beats them all), `ladder:` (a nested list is one level), `names: family | folder | off` (whether an inferred `final` beats an unrelated document: the author's "let's make it adjustable"), `by:` (what settles equal priority: `newest`, `oldest`, `name`; `[priority]` makes a tie the error of 3.32.9 again, `[newest]` ignores priority). A class takes `ordered: false`, `degrees`, `exclude`, `names: false`, `above:` / `below:`; a word may hold `{n}`. YAML's `names: off` (read as `false`) works, and `by` may be a comma list (`priority, oldest`), which is what the setup row stores.
+- **Where it is read, nearest first**: the documents' own `pdfmd-options: {ranking: ...}` and a metadata file named after one (classes and ladder only; `by`, `names` and `inherit` are the folder's: a WARN), then folder by folder from theirs upward `.pdfmd/ranking.yaml` > the folder's `metadata.yaml` > the folder settings' `options.ranking`, then the global `ranking.yaml` (beside the config file) and the config's `options.ranking`. `inherit: false` stops the climb. A nearer `ladder`/`names`/`by` replaces a farther one, classes merge by name. Nothing is read, or parsed, until bare `pdfmd` has several documents to choose from, so a broken file never spoils another build.
+- **Two documents that define a class (or the ladder) differently**: a WARN naming both; the newer one's is used. **Mistakes** (a word in two classes, an unknown class on the ladder, a bad `above:`) stop the choice with the file that defined it; a class on no ladder is a WARN and its words are ignored.
+- **`--setup`**: two rows, *Equal priority, when bare pdfmd must choose a document* and *Names that rank versions of a document*, also in a folder's setup; `pdfmd_setup/inventory.py` lists `ranking.by` and `ranking.names` as rows and `ranking.ladder` / `ranking.classes` as left out on purpose (a file's lists). The tie WARN and error now name the `by` setting.
+- Tests: `tests/test_ranking_layers.py` (through pdfmd itself: every place, the order of the places, `inherit`, documents, strict ties, `names`, a custom ladder, mistakes, nothing read for one file), more in `tests/test_ranking_rules.py`. README (*Several documents in a folder*: the settings), module docstring.
+
+## v3.32.9 — 2026-11-03
+
+Pre-edit state: commit `8c8293c`. Entry 3eu (the author's idea of 2026-11-03: "a small pdfmd-option called ignore or whatever that will exclude a document from autodiscovery ... actually, let's make it `priority` with different tiers"). Kept in 3.32. Not pushed. First of four commits of the line: the choice and the `priority` key (next: custom classes and the `ranking` settings, `--newest` and `--all`, `--which`).
+
+Bare `pdfmd` in a folder with several Markdown files chooses one instead of stopping with the list.
+
+- **`priority:`** at the root of a document's front matter or in its `pdfmd-options` (the second wins, with a WARN when both are set and differ). A number (higher wins, floats too), `final` / `last` / `max` (above every number; degrees of lastness: `final final`, `FINAL FINAL!!!`, `final2` and `final67` each beat the one before), `draft` or `0` (loses to every other document, builds when alone), `never` / `ignore` / `skip` / `exclude` or a negative number (not in the list), and nothing at all (`none`, `null`, `nil`, `nill`, `~`, blank: normal, between `draft` and `1`). A value that is neither a number nor a word is a WARN and counts as unset.
+- **Names**: `report.final.md`, `report.rewritten.md`, `report_v3.md` beat `report.md`; `report_draft.md`, `report.old.md` lose to it. They act only inside a family (a base name plus trailing known words, compared ignoring case and separators), so `report_draft.md` beside an unrelated `notes.md` is just another document and `lab2.md` is never a version of `lab.md`; `final_draft` counts as final. A `priority` written in any member of a family switches the names off for it.
+- **Equal tops**: the newest file (modification time) is built, with a WARN that names them all; identical times stop the run with the list and what raised each. The `AUTO MD` line now says what the chosen document beat and why (`over report.md [name: bare name], notes.md [priority: draft]`).
+- **Unchanged**: one Markdown file in the folder; an exact name (`pdfmd report`, still the override); `-b`, `-r` and the viewer. **New kind** `--no-auto priority` brings the old "Multiple Markdown files found" list back.
+- **The rules are pure and in their own package**, `pdfmd_ranking` (words and classes in `rules.py`, the choice in `choose.py`), written as a ladder of word classes from the start: the built-in behaviour is its default setting (`DEFAULT_RANKING`), so the customisation of the next commits adds layers, not new logic.
+- `priority` is a document-only `pdfmd-options` key (`pdfmd_setup/inventory.py`: Omitted, "document"); the `--no-auto` kind has its `--setup` text.
+- **Fixed before the release** (this line is not on PyPI yet; the fixes are one commit after `c19582d`, so they go into the entry of the version that had the bugs, as the versioning rule says): (1) pdfmd's own Markdown output (`X.assembled.md`, `X.gfm.md`, `X.ascii.md`, `X.ascii.gfm.md` beside `X.md`, any assembled file, hidden files such as the temporary `.name.pdfmd-*.md`) was a candidate, so "the newest wins" would have built the last build's output on the next run: `source_markdown()` leaves them out (`--which` names them in a NOTE); (2) `pdfmd -w` re-ran the original command line, so a bare `pdfmd -w` chose again at every rebuild: `pinned_watch_argv()` puts the chosen document in the re-run (and drops `--newest`); (3) `no-auto: [priority]` / `auto: {priority: off}` from a folder or the config file did nothing, only `--no-auto priority` worked: `priority_enabled(folder)` reads the same layers as `effective_no_auto()` (command line, folders, config) for the folder; the module-global `PRIORITY_PICK` is gone, `NO_AUTO_CLI` takes its place and reaches `-j` workers (`tests/test_jobs.py` caught the first). Tests: `tests/test_ranking_generated.py`.
+- Tests: `tests/test_ranking_rules.py` (the engine alone: values, names, classes, ladders, errors, the choice) and `tests/test_ranking_bare.py` (through pdfmd itself, `--stop-at markdown`). README section *Several documents in a folder*, the module docstring and the `--no-auto` help.
+
+## v3.32.8 — 2026-11-03
+
+Pre-edit state: commit `1d992bd`. `[kits]`, entry 3et UPDATE 2 (the author: "let's do it. no-auto geometry"). Kept in 3.32. Not pushed.
+
+A kit can take pdfmd's own margin, font and table-width defaults over with `no-auto:` in its `.kit` file.
+
+- **The key**: `no-auto: [margin]` (a word or a list of `margin`, `mainfont`, `monofont`, `mathfont`, `font`, `tablewidth`). Before, a class kit had to write `geometry: " "` into its metadata to stop the automatic `geometry:margin=...` from clashing with the class's own page; now the kit says what it means, and the metadata can stay about the document.
+- **Where it ranks**: under the command line, the document and the folders' files, over the config file (the same place a kit's metadata has). So a document can turn the default back on with `pdfmd-options: {auto: {margin: on}}`, and `--no-auto` and `-y` still mean what they meant. Applied to a single document and to a report or book (`-r`).
+- **What a kit cannot name**: a kit is chosen from the layers and from the files pdfmd found, so it cannot switch off the finding of metadata, Lua filters, preambles or kits themselves; those kinds, and `true` for everything, are a WARN naming the kind and are ignored.
+- **Not before**: an older pdfmd reads the key as an unknown one (a WARN) and goes on, so a kit that has it still builds there.
+- The kits' own `active_kits` cache is keyed on the two `--no-auto` kinds that decide the kit search (`kit`, `kpsewhich`) instead of the whole list, so one run makes one choice of kits, and prints a kit's warnings once, whatever else is switched off.
+- `pdfmd --kits NAME` shows the kit's `no-auto`. The module docstring now has a short Kits paragraph (it had none), the README's Kits section the key and its ranking.
+- Tests: `tests/test_kit_no_auto.py`, through pdfmd itself (a real build with a kit that has no `geometry:`).
+
+## v3.32.7 — 2026-11-03
+
+Pre-edit state: commit `d14c00a`. `[kits]`, entry 3et UPDATE 1 (the author: "make it possible for `pdfmd --install kit` to fetch an arbitrary git repo ... it'll look at all folders of it so nulabreport, which has `.kit` at root, and this one, pdfmd-kits, which has kits in child dirs, would work"). Kept in 3.32. Not pushed.
+
+`pdfmd --install kit:SOURCE` installs the kits of any repository.
+
+- **Sources**: `owner/repo` (GitHub, its default branch; the tarball over https, no git needed), `owner/repo@REF` (a tag, branch or commit), `#NAME` after either picks one kit, any git URL (https, ssh, scp-like; `git clone --depth 1` with only the https, ssh and file transports, `ext::` refused), `file:///path` (a local git repository, committed state), `./x` `~/x` `/x` (a folder, copied as it is), and a bare `NAME` (a kit of that name in the repositories of `kit-sources`). Plain `http://` and `git://` are refused. `pdfmd --install kit` alone lists the installed kits; `pdfmd --uninstall kit:NAME` removes one.
+- **What it finds**: a folder with `.kit` or `NAME.kit` is a kit; the repository root first, then every folder below it down to `kit-search-depth` (3) levels, hidden folders skipped, and a kit's own sub-folders are the kit's, never searched. So a repository that is one kit (the root shape of a package like nulabreport) and one with a kit per folder (a collection) both work. Each kit is checked with the kit loader; a faulty one is skipped with a WARN and the rest installed.
+- **Where it goes**: `kits/NAME/` beside the config file (kit discovery already reads it), the whole kit folder, with `.pdfmd-install.json` (source, ref, commit, SHA-256 of the archive, path in the repository, date). `pdfmd --kits` shows where an installed kit came from. Installing again updates it (a staged copy, then a swap); a folder there that pdfmd did not install is never replaced; a kit of another source needs `--yes`.
+- **Safe by construction**: nothing of the repository is run (no script, no hook, no kit Lua filter). The archive is read as data: a name that leaves the folder stops the install, links, devices and fifos are dropped, and the files and bytes are capped by `kit-install-max-files` (5000) and `kit-install-max-mb` (200). The install lists the kits that carry a Lua filter and says to read it: pdfmd runs it when a document selects the kit.
+- **Settings** (`options:` of the config file, read at install time, no `--setup` row; the inventory lists them as omitted): `kit-search-depth`, `kit-install-max-mb`, `kit-install-max-files`, `kit-sources` (the repositories a bare name is looked for in).
+- New module `pdfmd_kits/install.py` (pure; the downloader is handed in), `install_kits()` and `uninstall_kit()` in `pdfmd.py`, `kit` in `INSTALL_KINDS`.
+- Tests: `tests/test_kit_install.py` (the forms of a source, both repository shapes, depth and `#NAME`, a faulty kit, the commit from the tarball's folder, update and refusals, uninstall, hostile tarballs, caps, a folder with links, a real local git repository with a tag). Checked through pdfmd itself with a throw-away config: the author's kits repository (ten kits in child folders) and the real nulabreport repository (one kit at the root) were installed, listed, used for a build and uninstalled.
+- README: "Getting a kit" in the Kits section; `--help` and `--install`'s error text name `kit:SOURCE`.
+
+## v3.32.6 — 2026-11-03
+
+Pre-edit state: commit `f528e53`. `[kits]`, entry 3et (the author: "yes, follow pdfmd repo rules"). Kept in 3.32 as the author asked on 2026-11-02, though `CLAUDE.md` still names the kits line 3.31.x. Not pushed.
+
+A kit's folders reach Tectonic.
+
+- **The bug**: a kit puts its folder and its `carry:` folders on `TEXINPUTS`, which Tectonic does not read. With `-e tectonic` a kit that ships a LaTeX class (the apa7 kit of the kits repository, a class with its `config/` files) was never loaded: Tectonic built, without a word, with the copy of that class in its own bundle, or failed when its bundle had none. Found with a copy of the class that stops when it is loaded: xelatex stopped, Tectonic built.
+- **The fix**: for the engine `tectonic`, each chosen kit's folder and every folder under the `carry:` entries that are folders go to Tectonic as `-Zsearch-path=DIR` (`tectonic_search_folders()`; the option names one folder, not a tree, so a carried tree is listed folder by folder, hidden folders left out). The Pandoc route passes them as `--pdf-engine-opt=-Zsearch-path=DIR`; the direct route (`.tex` files, drawn fragments) gets them through the environment `tex_search_env()` already builds (`PDFMD_TECTONIC_SEARCH`) and `latex_engine_command()`. Other engines and a document with no kit are unchanged. Needs a Tectonic that has `-Z search-path` (0.17 has it).
+- Checked through pdfmd itself: the marker copy now stops under `-e tectonic` and the real apa7 kit builds; xelatex and lualatex were never affected.
+- Tests: `tests/test_kit_texinputs.py` (the folders one by one, no hidden folder, no walk of the kit's whole folder, nothing without a kit, the command line of the direct route for Tectonic only).
+- README: the paragraph "A kit needs no install" says it. No new setting.
+
+## v3.32.5 — 2026-11-02
+
+Pre-edit state: commit `b5cd684`. Entry 3eo, step 2a of the Obsidian flavour line (the author: "any Pandoc or whatever detected syntax switches the reader, unless those are like examples in fenced code blocks"). Not pushed.
+
+- **No more "gfm leaves X as text" NOTE: pdfmd acts on what it finds.** A file with no front matter was read as gfm and, when it used `H~2~O`, `x^2^`, `{#id}` attributes, raw LaTeX or `:::` divs, a NOTE said gfm printed them as text. Now a table of detectors (`READER_NEEDS`, `reader_needs()`) decides, and each syntax needs one of two things: an extension Pandoc accepts on gfm, which is added to the reader (`gfm+subscript`, `+superscript`, `+attributes+bracketed_spans`, `+fenced_divs`, `+definition_lists`, `+fancy_lists`, `+raw_attribute`; the definition-list and `.csv` div cases were added on need before), or Pandoc's own Markdown reader, which the file is switched to (`^[inline footnotes]`, raw LaTeX, grid tables, simple tables, `(@)` example lists, as `@citations`, Org captions and `\md{}` already did). `--verbose` says which syntax decided: `reading as gfm+subscript (it uses subscripts (H~2~O))`, or `it uses raw LaTeX (...), which gfm cannot read; keeping the default markdown reader`.
+- **Only prose is looked at**: fenced code, inline code, math (`$..$`, `$$..$$`; `$5 or $10` is not math) and HTML comments are taken out first, so an example of the syntax in a code block changes nothing. The line that opens a fence is the one exception (a fence with attributes, ```` ```{.smiles} ````, needs `+attributes`). Lettered and Roman-numeral lists count only as two items in a row (`a.` `b.`, `(i)` `(ii)`): `I. Introduction` alone stays text, as in GFM. Not looked for: indented code blocks, line blocks, multiline tables, inline `^x^` inside words (listed in the notes).
+- **Cost, accepted by the author**: Pandoc's Markdown reader sizes pipe-table columns differently from gfm (the reason gfm was chosen); a file with raw LaTeX or an inline footnote and no front matter now gets that reader, so its tables size as they do in a file with front matter.
+- Removed with it: `reader_notice()`, `gfm_blind_spots()`, `GFM_BLIND_SPOTS`, `FENCE_ATTRIBUTES`, `has_definition_list()` (the table replaces them); the NOTE is gone from the output.
+- Tests: `tests/test_reader.py`: the old blind-spot tests became `ReaderNeeds` (the extension each syntax needs, what only Pandoc's reader reads, code and math and comments not counting, a fence's attributes, lettered lists) and the command-line tests (nothing said but under `-v`, the extension added and `<sub>` in the output, a switch to Pandoc's reader for an inline footnote and for raw LaTeX, the same syntax in a code block changes nothing). Checked through the whole `pdfmd` on the three notes of the Obsidian test vault (all read as plain gfm, nothing to add) and on small files.
+- README: the "It decides per document" paragraph and the `READER` row say what is added and what switches.
+
+## v3.32.4 — 2026-11-02
+
+Pre-edit state: commit `834e135`. Entry 3eo, step 1 of the Obsidian flavour line: the gfm-or-Pandoc choice made reliable. Not pushed on its own (see the last bullet).
+
+- **The global metadata no longer decides the reader.** The file `pdfmd --setup` writes (`metadata.yaml` beside the config, and the presets) was counted as "a linked metadata file", so on a machine that has one every file with no front matter was read as Pandoc's Markdown and the gfm rule never fired: the same file read differently on another machine (found with the author's own notes: `AUTO READER ... metadata.yaml is linked; keeping the default markdown reader instead of gfm` for a file that had none). Now only a metadata file of the document (beside it, `-y`, a folder's) counts. Everything the global file sets still applies: Pandoc reads a metadata file's strings with its own Markdown whatever the reader (measured with Pandoc 3.13: `title`, a `header-includes` macro and `H~2~O` in an `abstract` come out the same under `-f gfm` and `-f markdown`), a global `pdfmd-options: {reader: markdown}` still wins, and `promote_bare_title()` is unchanged (pinned by a test).
+- **`has_yaml_frontmatter()` says what Pandoc says.** It was "the first line is `---`", so a file that opens with a thematic break (`---`, a blank line, text) counted as having front matter and was read as Pandoc's Markdown. Now: blank lines may come first, then `---` and a line that is not blank, and a later `---` or `...` closes it; `---` straight after `---` is an empty block and still counts (the documented way to ask for Pandoc's reader); a BOM and CRLF are fine. Measured against `pandoc -f markdown -t json` for 14 shapes. About twenty other places in `pdfmd.py` read a front-matter block with their own regex (`papersize`, margins, `pdfmd-options` ...); they all require a closing line, so they differ from this only for a file that opens with a rule and has another rule later. Left as they are, listed in the notes.
+- Tests: `tests/test_reader.py` (+8): the truth table both ways, and through the whole `pdfmd` with a config and a global `metadata.yaml` (gfm is chosen and the NOTE is printed; the global title, a raw-LaTeX `header-includes` and Markdown in a metadata string still arrive; a global `reader:` still wins; a `metadata.yaml` beside the document still means Pandoc's Markdown; a leading rule is not front matter; a bare `# Title` is left alone). Run with the modules that use a global file (`test_presets`, `test_setup_folder`, `test_standalone_source`, `test_path_display`, `test_mathfont`, `test_config`, `test_typst_input`, `test_setup`).
+- README: "It decides per document" and the `READER` row say what counts.
+- **Behaviour change to know about:** on a machine with a global metadata file, a file with no front matter that uses `H~2~O` or `x^2^` now prints the existing NOTE and shows them as text, instead of silently rendering them as Pandoc does (a file with `@citation` syntax or a `metadata.yaml` beside it still keeps Pandoc's reader). A document with front matter (every `nulabreport` report has some) is untouched. Step 2 of the line (the `pdfmd` flavour) adds subscripts, superscripts and the other Pandoc blocks to the gfm reader so the NOTE goes away; that is why this patch is not pushed alone.
+
+## v3.32.3 — 2026-11-02
+
+Pre-edit state: commit `4613a5a`. Entry 3en, the second look at 3.32.1 and 3.32.2.
+
+- `diagram-timeout` without a runner: a copy of pdfmd with no `pdfmd_lua/limited_run.py`, or a Python that does not know its own path (`sys.executable` empty), made every diagram fail with "does the source parse?". Now the filter is told nothing about a limit, the tools run as before, and pdfmd prints one NOTE saying the setting is not applied. (A wheel and the zipapp both carry the file: a wheel ships a package's `.py` files, the zipapp unpacks to real files.)
+- `limited_run.py` waits at most 5 s after it has stopped a tool for the pipes to close (a grandchild in a session of its own can hold one open). It is a constant, not a setting: a safety stop in a helper that decides nothing about the output, and nothing a user would tune.
+- `tests/test_slide_notes.py`: the header reaches the `.tex` of a deck (`--stop-at tex`, no LaTeX needed) with the deck's own `aspectratio=169` and `header-includes` macro still there (3 tests: the header and the deck's own settings, `off`, the setting in a `-y` metadata file). Also checked by hand: a `metadata.yaml` found beside the deck. `tests/test_diagram_timeout.py` (+3): the limit and runner reach the filter, `0` turns diagrams off, a negative number passes no limit, no interpreter means no limit and a NOTE.
+
+## v3.32.2 — 2026-11-02
+
+Pre-edit state: commit `c9d0f0a`. Entry 3en (the author: "the setting --- yes, and document it" for a named slide-notes setting).
+
+Speaker notes in a Beamer deck. A `::: notes` block was dropped by `pdfmd -p` (0 note lines in the PDF); Pandoc has the feature, Beamer's `show notes`, but it was reachable only through a variable and undocumented.
+
+- `slide-notes: off | show | only` (`pdfmd-options` key, config key, `--setup` row "Speaker notes ..." under Output; default `off`, today's behaviour). `show`: a notes page after each slide. `only`: the notes pages alone, for printing. `true` and `on` mean `show`; a bad word stops the build and names the three, like `md-macro`.
+- Written as a header file (`\setbeameroption{show notes}` / `{show only notes}`, cached by mode under the cache's `tex/`), added next to the other pdfmd headers for a `-p` build with a LaTeX engine, NOT as `-V classoption=notes=show`: measured on 3.32.0, that variable replaces the deck's own `classoption`, and a 16:9 deck (`aspectratio=169`, 454 x 255 pt) came out 4:3 (363 x 272 pt). With the header the size stays.
+- Other builds (not `-p`, other writers, a non-LaTeX engine) ignore the setting without a message: a config-level `slide-notes: show` is meant for decks and would otherwise talk on every other document. Pandoc's own revealjs already shows notes.
+- `slide_notes_mode()` and `slide_notes_args()`; `tests/test_slide_notes.py` (7 tests: the default, `show` / `only` / `true`, a bad word, a header only for a deck; and, when `lualatex` and poppler are installed, a 16:9 deck built three ways: 3 pages and no notes by default, 5 pages with `show`, 2 with `only`, the page size 454 x 255 pt each time). README: "Speaker notes" under Slides, with an example; `docs/recipes.md` 7.4 has a line. The `--help` text has no new flag.
+- Not done: Beamer's `show notes on second screen=right` (notes beside the slide, for a presenter view), which would be a fourth value; the native tier and a Typst deck (pdfmd has none).
+
+## v3.32.1 — 2026-11-02
+
+Pre-edit state: commit `c52dd09`. Entry 3en (the review of two research reports on Markdown-to-PDF pain points; the author: "diagram limit on at 120 s. the setting --- yes, and document it").
+
+A diagram tool that never answered hung the build with no message: a stub `mmdc` that sleeps was still being waited for after 60 s. `pandoc.pipe`, which `pdfmd_lua/diagram.lua` ran the tools with, has no time limit.
+
+- `diagram-timeout` (`pdfmd-options` key, config key, `--setup` row "Time limit of one diagram tool run" under Checks and limits): seconds one run of `mmdc`, `dot`, `d2`, or of the `rsvg-convert` / `inkscape` that converts their SVG, may take. Default 120, ON. `0`: no diagram is drawn (the fences stay as code, one WARN naming the setting; it overlaps `--no-auto diagrams`, kept so the value means what `soffice-timeout: 0` means). A negative number: no limit, and no runner.
+- New `pdfmd_lua/limited_run.py`, started by the filter under the limit with the interpreter pdfmd runs on (so no `timeout` command is needed, which macOS and Windows lack): it passes standard input and output through as bytes (a picture written to standard output stays intact), leaves the tool's error output where it was, and when the time is up stops the tool with every process it started (a process group; `taskkill /T` on Windows), prints a marker and exits 124. 127 for a missing program.
+- The filter: a stopped tool leaves its diagram as code with a WARN that says which program did not finish in how many seconds and names the setting (`--strict` makes it an error, like any undrawable diagram), and the tool is not tried again in the build, with one WARN for the first skipped fence: a browser that cannot start would otherwise cost the limit once per diagram. A stopped `dot` is not asked a second time for an SVG to convert. Nothing from a stopped run reaches the cache.
+- Known cost, not fixed: the Word and OpenDocument route runs Pandoc twice, so there a hung tool costs the limit twice (each run remembers on its own).
+- `diagram_timeout_from()` and `diagram_timeout_for()` (the document's key, its metadata files', the config's); the filter gets `pdfmd-diagram-timeout`, `-python` and `-runner`, or `pdfmd-diagram-off`, in the metadata map it already had.
+- `tests/test_diagram_timeout.py` (6 tests: the value as seconds, a document's own limit, bytes through the runner, exit code and error output through the runner, a run stopped with its child, a missing program) and four in `tests/test_diagrams.py` (a hanging `dot` is stopped and the second fence does not start it again, nothing in the cache, `--strict` fails; a hung Graphviz is not asked for an SVG next; `0` runs nothing; `-1` lets a slow tool finish). Not tested on Windows: the runner uses `taskkill /T` and `shutil.which` for `mmdc.cmd`; the end-to-end tests there use shell-script stand-ins and are skipped, as the others in that file.
+- README: "Diagram time limit" beside the LibreOffice one, and a sentence in the diagrams section. The `--help` text has no new flag.
+
+## v3.32.0 — 2026-11-02
+
+Pre-edit state: commit `394e482`. Opens the `\md{}` feature line, entry 3dc (queued 2026-10-26; the author, 2026-11-02: "i guess it is a good time to create that \md{} feature we were thinking of").
+
+Markdown inside raw LaTeX. Raw LaTeX in a Markdown file reaches LaTeX untouched, so `*emphasis*`, `$x^2$` or `[@key]` inside a `\textbf{...}`, a `\caption{...}` or a hand-written `tabular` stayed as typed.
+
+- `\md{...}` (one line or several) and `\begin{md}...\end{md}` hold Markdown: new `pdfmd_lua/md_macro.lua` splits the raw TeX Pandoc hands over into [raw TeX, the argument read as Markdown, raw TeX] with `pandoc.read`. It is the first of pdfmd's Lua filters, before pandoc-crossref and `--citeproc`, so a citation, an `@fig:x` reference, math or a footnote in the argument belongs to the one document.
+- Where: a raw inline (`\textbf{\md{x}}`, a paragraph, heading, list item, table cell, caption) for every writer; a raw block such as a whole `tabular` or `figure` as one Plain block for LaTeX, Beamer and ConTeXt (the other writers drop that raw block as before); `\begin{md}` as real blocks (paragraphs, lists, tables) for every writer, also inside another raw environment. Several paragraphs in an inline `\md{}` are joined with a line break.
+- The argument's braces must balance; a backslash escapes the next character (`\{`, `\}`), `%` and `#` are Markdown, not a TeX comment or parameter. A `\md` followed by a letter (`\mdseries`) is another command. An unbalanced `\md{` is read by Pandoc as plain text; the filter says so once with a WARN. `\begin{md}` has no brace counting, which is the way to write a code span with a lone brace.
+- `md-macro: on` (the default) | `off` in `pdfmd-options`, with a `--setup` row (Input). The filter is loaded only for a document that has a macro outside code; a document that defines `\md` itself (`\newcommand`, `\def`, `\newenvironment{md}`) keeps its own and gets one NOTE.
+- `contains_citations()` asks Pandoc with the filter on, so `--citeproc` is added for a document whose only citations are inside `\md{}`. A file with no front matter that uses the macro is read with Pandoc's `markdown` reader, not `gfm` (no raw LaTeX there), with the usual notice.
+- Not done: the native (no-Pandoc) tier, a `.tex` source compiled directly, and the identity `.sty` for `~/dev/tex` (so the same `.tex` compiles without pdfmd), which is a step in the other repository.
+- `tests/test_md_macro.py` (14 tests: detection outside code and own definitions, a macro inside `\textbf`, in a heading / bare line / list / table cell, in a raw `tabular` for LaTeX and HTML, the environment for tex / html / typst / md and inside `center`, citations resolved and listed, no front matter, `off`, a bad word, an own definition, an unbalanced brace, `\mdseries`). README: "Markdown inside raw LaTeX".
+
+## v3.31.52 — 2026-11-02
+
+Pre-edit state: commit `bd497d7`. Still under 3.31. `[tables]`, entry 3el (the author: "it shows that some features we've added are thin ... record it and add todo line to revise the full functionality ... and start with all those three").
+
+Three things the author's own example showed missing: a caption above a table that needs no repair, the `#+` lines of Org, and a cell's own alignment.
+
+- `#+CAPTION:` (any case) and `#+NAME: tbl:id` above ANY pipe table become its caption, one that needed no repair included (with or without outer bars: `1 | 2 | 3` and `:-|:-:|-:`). That table is otherwise not touched, and nothing is printed for it unless a `#+` line was dropped.
+- `#+ATTR_*:` lines directly above an Org or rule-less table are consumed: `:align lcr` (letters l, c, r; `|` and other characters ignored) sets the alignment when no cookie row does; every other option is dropped with a WARN. Above a valid pipe table its separator row decides and `:align` is reported as not used. `#+TBLFM:` lines directly below are dropped with a WARN naming them (the cells hold the result; nothing is calculated).
+- A cell that starts with `<l>`, `<c>` or `<r>` keeps that alignment: `pdfmd_lua/cellalign.lua` cuts the tag (and the space after it) off. HTML, Typst, Word and the rest use the cell's alignment; Pandoc's LaTeX writer ignores it, so LaTeX and Beamer get raw TeX, `\multicolumn{1}{c}{...}` in a column of natural width and `{\centering ...\par}` in a column with a width, which is why the filter goes in after the table-width filter (a new `cellalign_args()` after every `width_filter_args` call). The Markdown writers keep the text; a cell with more than one block is left alone. `pdfmd-options: cell-align: on|off` (default on, a `--setup` row), loaded only for a document that has such a cell.
+- `tests/test_cellalign.py` (9 tests: detection, natural and wrapped LaTeX columns, Typst, HTML, `off`, a bad word, the Markdown writers, no filter without a tag, the author's example whole); `tests/test_table_ascii.py` (40 tests: captions above valid tables, ATTR and TBLFM, `#+` lines in code, others kept). README: the cell-alignment section and the Org bullet.
+- Not done: the native tier; `#+TBLFM:` is never evaluated. TODO: a line to revise the thin features of this line (the pre-pass kinds, line breaks, table captions, `<c>` cells, Org extras) against unusual input during the documentation programme.
+
+## v3.31.51 — 2026-11-02
+
+Pre-edit state: commit `70963c6`. Still under 3.31. `[tables]`, entry 3el (the author, asked whether Org's alignment cookies and `#+CAPTION:` would be useful: "let's do it").
+
+An Org table keeps its alignment and its caption.
+
+- A row of alignment cookies (`| <l> | <r> | <c> |`, with a width `<r10>`, or `<10>` alone) is dropped from the table and sets the separator row: `:----`, `----:`, `:---:`. Every separator cell has the same width when any column is aligned, because Pandoc's `markdown` reader takes unequal dashes for a choice of column widths. A width alone sets no alignment.
+- `#+CAPTION: text` (also `#+CAPTION[short]:`; several lines are joined) directly above a repaired Org or rule-less table becomes a `: text` line below it; `#+NAME: tbl:id` adds `{#tbl:id}`. A plain `#+NAME:` is dropped (before Pandoc 3.8.2 a plain `{#id}` would show as words in the caption). Other `#+` lines (`#+ATTR_LATEX:`, `#+TBLFM:`) stay as written, and a `#+CAPTION:` that is not directly above such a table stays.
+- A caption needs Pandoc's `markdown` reader (gfm has no table captions), so a file with no front matter that has a `#+CAPTION:` line is read with `markdown` instead of `gfm`, with the usual notice, unless `table-ascii` is `note` or `off`.
+- `pdfmd_tables/ascii.py` (`org_caption`, `COOKIE`, `assemble(aligns=)`), `pdfmd.py` (`ORG_CAPTION_RE`, the reader choice), the `--setup` row text, README. Tests: `tests/test_table_ascii.py` (cookies, caption and name lines, a build with no front matter).
+
+## v3.31.50 — 2026-11-02
+
+Pre-edit state: commit `fe19049`. Still under 3.31. `[tables]`, entry 3el (the author, after the explanation of Org-mode: "do the orgmode then").
+
+Org-mode tables, and `|` lines with no separator row, are read as pipe tables, with the setting of 3.31.47 (`table-ascii`).
+
+- Org: `| a | b |` lines with a rule `|---+---|` or `|-` (a lone `|---|` is a one-column pipe table's separator and stays). Pandoc's `markdown` reader reads the `+` rule, `gfm` and `commonmark_x` make a paragraph of it, so pdfmd rewrites it for both. The rows above the first rule are the header (several are joined like a wrapped header), later rules only group rows and are dropped, leading and trailing rules too; one line is one row (Org has no wrapped cells). A row with another number of cells than the header is fitted, with a WARN of its own.
+- `|` lines with no separator row (an Org table without a rule, what some chat models write): Pandoc reads a paragraph (`gfm`) or a line block (`markdown`). Every line must start and end with an unescaped `|`, have two cells or more and the same number as the others, at least two lines, and none may be a separator row; the first row is the header. A real pipe table, a line block (`| roses`), a lone line and a table with a separator row are never touched.
+- The table keeps its indent (a table inside a list item). `pdfmd_tables/ascii.py` (`org_table`, kinds `org` and `pipe`), the `--setup` row text, README (two more bullets). Tests: `tests/test_table_ascii.py` (header above the first rule, group rules, a ragged row, no separator row, an indent, real pipe tables and line blocks untouched, a build under both readers).
+- Not done: Org's alignment-cookie rows and `#+CAPTION:` lines stay as written; the no-Pandoc native renderer does not do it.
+
+## v3.31.49 — 2026-11-02
+
+Pre-edit state: commit `765ce9e`. Still under 3.31. `[tables]`, entry 3el (the author: "`<br>` ... `\par` destroys table, and `<br>` is ignored in latex route. let's do it"; "let's not limit it to `<br>` html only and make it interconvertable, like pagebreak syntax").
+
+One line break for every writer.
+
+- Pandoc reads `<br>` as raw HTML, which every writer but HTML drops: `one<br>two` printed `onetwo` in LaTeX, and a table cell, where a blank line or `\par` breaks the table, could not hold two lines. `pdfmd_lua/linebreak.lua` (new, in the manner of `pagebreak.lua`) reads `<br>`, `<br/>`, `<br />` (any case), a raw TeX `\newline`, `\linebreak`, `\linebreak[n]`, a raw Typst `#linebreak()`, a raw Word break run and a raw ConTeXt `\crlf`, and gives the target Pandoc's LineBreak (LaTeX `\\`, in a cell a box of lines; Typst `\`; Word a break run; HTML `<br />`).
+- A spelling already in the target's own language stays as written; the Markdown writers keep everything, except pdfmd's flat Markdown (`--to gfm`, raw HTML off), where `<br>` would be dropped and becomes a hard break. A paragraph or cell of nothing but breaks is left alone (the `space` markup kind reads a lone `<br>`); a break at the very start or end of a run of text is dropped.
+- Mirrors pagebreak, with another default (the author: "2. equivalent of auto ... everything else mirrors pagebreaks, with all and families"). Families: `html` (`<br>`, `<br/>`, `<br />`), `tex` (`\\newline`, `\\linebreak[n]`), `typst` (`#linebreak()`), `word` (a raw break run), `context` (`\\crlf`). `pdfmd-options: linebreak:` not set or `auto` carries every family inside table cells only; `true` / `all` every family everywhere; a list those families everywhere; `false` none. `--linebreak [KIND ...]` (bare: all, everywhere) and `--no-linebreak` for a run; a `--setup` row (a multi choice of the families, in Universal markup; unset is `auto`) and the inventory entries. pdfmd passes the families and where as `-M pdfmd-linebreak=html,tex` and `-M pdfmd-linebreak-where=cells|all`; the filter is added only for a document that has a spelling (`LINEBREAK_RE`). A word that is no family is said and ignored. Not done: the native (no-Pandoc) tier.
+- README: "A line break inside a table cell". Tests: `tests/test_linebreak.py` (the default in cells, `true`, the target's own spelling, Typst and Word, families, `false` and the command line, a bad word, the Markdown writers, lone and trailing breaks).
+
+## v3.31.48 — 2026-11-02
+
+Pre-edit state: commit `6253c34`. Still under 3.31. `[tables]`, entry 3el (the author: "yes, build all of it as 3.31.48").
+
+More text tables are read as pipe tables, with the setting of 3.31.47 (`table-ascii`).
+
+- Lazy ASCII forms: a border as short as `+-+` (no inner `+`), rows without outer bars (`1 | 2`), middle borders left out. The table must be bordered at both ends and have a line with two cells. With no border between the body lines, a line whose first cell is empty continues the row above and any other line starts a row; with a border between rows, the lines between two borders are one row, as before.
+- Box-drawing tables (`┌─┬─┐ │ ├─┼─┤ └─┴─┘`, double, rounded and heavy): cells split on `│ ┃ ║`, a `|` inside a cell escaped; the first rule that contains `═` or `━` and is not the first or last is the header rule.
+- psql output: the header line (no outer bars) above `----+----`, rows with as many bars, the `(N rows)` line dropped with the table.
+- MySQL console output: a real grid table, no `=` rule, exactly three rules, a one-line header and two or more body lines, which Pandoc read as one joined row; each line is a row now. A body line with an empty first cell leaves the table alone, so a real grid table with a wrapped row is not touched; any other real grid table is never touched.
+- The WARN names the form (`a box-drawing table was read as a pipe table (2 columns, 2 rows)`); the `--setup` row and the README section ("Text tables Pandoc cannot read") list the four spellings. Not done: the native tier, `<br>` in cells, org `|---+---|` and a pipe table without a separator row (queue items).
+- Tests: `tests/test_table_ascii.py` (`Forms`, and a build for each of box, psql and lazy).
+
+## v3.31.47 — 2026-11-02
+
+Pre-edit state: commit `4761d60`. Still under 3.31. `[tables]`, entry 3el (the author pasted a table that NotebookLM wrote; "just implement it now under 3.31").
+
+An ASCII table with no `+` at its column boundaries is read as a pipe table.
+
+- Chat models write a "plain-text table" with `+-----+` borders that have no inner `+`, no `+===+` under the header, and `|` bars that drift by a character. Pandoc read it as one column without a header (every line a cell, the text off the page), and `table_width.lua` had nothing to balance. `pdfmd_tables/ascii.py` (new) repairs it before Pandoc sees it: a row is split on `|` (the bars' positions are not trusted), the lines between two borders are one row (wrapped cell lines joined with a space), the first row is the header (every row above a `+===+` line, if there is one), and the result is a pipe table with equal columns, which pdfmd's own width filter balances as it does any other. Rows with another number of cells than the header are padded or cut, each with a WARN.
+- A real grid table (an inner `+`), a grid table of one column (no line with two cells), and anything inside a fenced or indented code block, an HTML comment or the YAML front matter are left alone. A literal `|` in a cell must be written `\|`.
+- The text is changed in memory: `prepared_title_source()` (the document and a section built alone) and `scaffold_inputs()` (every part; the new `transform` argument) hand Pandoc a temporary copy, the file is never touched. One `WARN  table-ascii: FILE, line N: ...` for each table. Not done: the native (no-Pandoc) tier.
+- `pdfmd-options: table-ascii: repair` (the default) | `note` (leave it, say so once for each table) | `off`; a `--setup` row (`pdfmd_setup/registry.py`) and its inventory entry. A word that is none of them stops the build. No number is a threshold.
+- README: "A plain-text table from a chat model". Tests: `tests/test_table_ascii.py` (the function, then real builds: the default, `note`, `off`, a bad word, a real grid table, a part).
+
+## v3.31.46f — 2026-11-02
+
+Pre-edit state: commit `f47c019`. No shipped code changes (a manifest, a script, a workflow and docs; none of it is in the PyPI package), so no version bump. Entry 3ej.
+
+A Scoop bucket for Windows, in this repository.
+
+- `bucket/pdfmd.json`: depends on Python, Pandoc and Typst (suggests Tectonic); its install script makes a virtual environment in the app folder and has pip install `pdfmd-cli==<version>` into it; `pdfmd.exe` is the shim. `scoop bucket add pdfmd https://github.com/aliperdehan/pdfmd`, then `scoop install pdfmd/pdfmd`.
+- `scripts/bump_scoop.py` (shares the PyPI lookup with `bump_formula.py`): changes the manifest's `version` and nothing else; `tests/test_scoop_bucket.py` checks the manifest and the script.
+- `.github/actions/scoop-test` installs Scoop on a Windows runner, installs pdfmd from the manifest, builds a document with Typst and uninstalls it. `scoop.yml` runs it by hand; the new `scoop` job of `publish.yml` points the manifest at the release, runs it, and commits the manifest to `main` as the bot, next to the Homebrew job (both pushes now pull and try again, since they can meet).
+- README: the Scoop install in the install section.
+
+## v3.31.46e — 2026-11-02
+
+Pre-edit state: commit `418ac50`. No shipped code changes (a Dockerfile, a workflow and docs; none of it is in the PyPI package), so no version bump. Entry 3ej, the author's wish: "let's try docker and scoop", with Tectonic and Typst instead of a full TeX Live and Calibre and LibreOffice optional.
+
+A container image, `ghcr.io/aliperdehan/pdfmd`.
+
+- `docker/Dockerfile`: one file, four variants by build argument. `latest` is Python, pdfmd from PyPI, Pandoc and Typst (`--install full`), Tectonic (`--install core:tex`), the default fonts, and one warm-up build so Tectonic's own files are in the image and a run needs no network (0.8 GB). `TEX=1` adds TeX Live's LuaTeX and XeTeX for documents that set `engine: lualatex`; `OFFICE=1` adds Calibre (`--install calibre`, with the Qt libraries it needs) and LibreOffice (3.4 GB); both are `full` (4.4 GB). The tools and caches are in `/opt/pdfmd`, open to every user, so `docker run --user` works. The default fonts come from a CTAN mirror that sometimes stalls, so the build gives that step a time limit and tries again.
+- `docker/smoke.sh`: what CI runs on every image before it is pushed, as another user than root and with no network: the default engine, Typst, Tectonic (and lualatex for TeX Live); Word, EPUB and ODT output, Calibre and LibreOffice for the office variants. It caught a missing Qt library of Calibre in the first office image.
+- `.github/workflows/docker.yml`: the four variants for amd64 and arm64 (on the native runners, no emulation), the smoke test, a push by digest and one multi-platform tag per variant (`latest`, `tex`, `office`, `full`, and `X.Y.Z[-variant]`). `publish.yml` calls it after the PyPI upload; run by hand from the Actions tab it builds and tests without pushing, or publishes the images of a release that is already on PyPI.
+- README: the container in the install section. `CLAUDE.md`: the release also builds the images.
+
+## v3.31.46d — 2026-11-02
+
+Pre-edit state: commit `50e7ed1`. No shipped code changes (a docs file only), so no version bump.
+
+- `CLAUDE.md` (Releasing): after a release the `homebrew` job has committed the formula bump to `main`, so the local `main` must be pulled (`git pull --ff-only`) before the next push.
+
 ## 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.