pdfmd-cli 3.25.20__tar.gz → 3.28.49__tar.gz

{pdfmd_cli-3.25.20/pdfmd_cli.egg-info → pdfmd_cli-3.28.49}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: pdfmd-cli
-Version: 3.25.20
+Version: 3.28.49
 Summary: One command from Markdown to a good-looking PDF: a Pandoc wrapper with smart defaults, project-file discovery and a multi-engine fallback chain
 Author: Ali Perdekhan
-License-Expression: MIT
+License-Expression: MIT AND Apache-2.0
 Project-URL: Homepage, https://github.com/aliperdehan/pdfmd
 Project-URL: Changelog, https://github.com/aliperdehan/pdfmd/blob/main/CHANGELOG.md
 Keywords: pandoc,markdown,pdf,latex,cli
@@ -16,6 +16,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: pdfmd_inkmd/LICENSE
 License-File: pdfmd_inkmd/assets/fonts/DejaVuSans-LICENSE.txt
+License-File: pdfmd_mhchem/LICENSE
 Requires-Dist: pyyaml
 Requires-Dist: pypdf
 Provides-Extra: math
@@ -46,10 +47,20 @@ Word or OpenDocument file that follows its page setup, fonts and LaTeX (see
 
 ```console
 $ pdfmd lecture
-AUTO: READER TITLE MARGIN MONOFONT. Use --verbose to see in full
-OK    lecture.md
+FOUND     metadata: metadata.yaml + preamble.tex
+DEFAULTS  margin 1in, font STIX Two Text, code in JetBrains Mono, title from heading
+AUTO: READER. Use --verbose to see in full
+OK    lecture.md > lecture.pdf  (lualatex)
 ```
 
+`FOUND` is what pdfmd picked up from the folder, `DEFAULTS` what it applied because nothing said otherwise
+(the global metadata of `pdfmd --setup`, the title taken from a leading `# ` heading, a wide table whose columns it
+balanced), and the `AUTO:` line the other decisions it made. Files of one folder are listed under it once
+(`metadata: metadata.yaml + preamble.tex`; `--setup` can list each with its path instead). Each line is cut at the
+width of the terminal (110 characters when the output is piped): `+3 more (--verbose)`. `--verbose` prints every
+decision with its reason. The closing line names the file the build made, `OK    lecture.md > lecture.pdf`; `--setup`
+sets what stands between the two.
+
 In a folder with a single Markdown file you do not even need the name: `cd` into the folder and run `pdfmd`. It finds
 the file, its metadata, preamble and filters, and writes the PDF beside it (with several Markdown files it asks for
 one, or for `-b` to convert all of them or `-r` to join them). `pdfmd --help` is one short page; `pdfmd --help all`
@@ -90,6 +101,7 @@ turns that knowledge into defaults:
   given a Word recipe; what is left (tikz, chemfig, math Pandoc cannot convert) is drawn by LaTeX in the document's
   own preamble and embedded as vector pictures. `pdfmd-options: {office: {latex: auto|images|off}}`, `--no-auto
   officelatex` and `pdfmd --setup` switch it (see [Word and OpenDocument output](#word-and-opendocument-output)).
+  The file's properties hold the document's title and authors, and nothing of the machine that built it.
 - **It handles every script and emoji.** Text the main font cannot draw (Arabic,
   Hebrew, Chinese, Japanese, Korean, Greek, Cyrillic with Kazakh letters, Indic and
   more) is set run by run in an installed font for its script, emoji become colour
@@ -164,6 +176,11 @@ sudo pacman -S python-pipx pandoc-cli typst texlive   # Arch
 
 On any Linux, `pdfmd --install full` (Pandoc and Typst) needs no package manager and no root.
 
+The extras that are Python packages (`pdfmd --install math`, `tui`, `translit`, `batchocr` ...) go into the Python pdfmd runs
+from; when that Python is managed by the system (Homebrew's, Debian's: "externally-managed-environment", PEP 668) pdfmd puts
+them in its own folder instead, `~/.local/share/pdfmd/python/3.14` (one per Python version), which it adds to the end of
+the module path when it starts. Nothing is installed into the system's Python.
+
 ```powershell
 py -m pip install --user pipx; py -m pipx ensurepath          # Windows
 winget install --id JohnMacFarlane.Pandoc; winget install --id Typst.Typst
@@ -210,12 +227,27 @@ OK    7. weasyprint  (/opt/homebrew/bin/weasyprint)
 MISS  8. wkhtmltopdf
 ...
 OK    14. soffice  (/Applications/LibreOffice.app/Contents/MacOS/soffice)
+OK    calibre (only when named: -e calibre)  (/opt/homebrew/bin/ebook-convert)
 OK    quarto (only needed for .qmd files)  (/usr/local/bin/quarto)
 ```
 
 The numbers are the fallback order, and also shortcuts: `-e 6` means
 `-e typst`.
 
+**An order of your own.** `-e` takes a comma list, tried in the order written and nothing else:
+`-e typst,calibre,lualatex` tries Typst, then Calibre, then LuaLaTeX. A word is an engine (or its alias), a family
+(`tex`, `html`, `typst`: its installed members, in place) or `pandoc` (every engine Pandoc drives; never Calibre). A word
+whose engine is not installed is passed over with a NOTE while another one of the list can run, and the build stops only
+when none can. `pdf-engine:` in `pdfmd-options`, the front matter, a metadata file or the config takes the same list
+(`pdf-engine: [typst, lualatex]`). Without `-e` the chain is the numbered one above, unchanged.
+
+`-e calibre` prints the document with [Calibre](https://calibre-ebook.com)'s `ebook-convert`
+instead: Pandoc writes one HTML page (math as MathML, which Calibre draws with its own
+MathJax) and Calibre turns it into a PDF with the document's paper, margins, `fontsize:` and
+language, page numbers, and bookmarks from the headings. LaTeX in the document is made native
+or drawn as a picture, as for a Word file. Calibre is never tried on its own: only when you
+name it (`-e calibre`, or `pdf-engine: calibre` in `pdfmd-options:`).
+
 For everything at once, `pdfmd --doctor` is one page on the Markdown-to-PDF tools, fonts
 and emoji, PDF reading (batchocr, Tesseract, Poppler, OCR languages), your config file and
 the cache, ending with the command that fixes each missing piece:
@@ -233,6 +265,21 @@ MISS  poppler: not found
        brew install tesseract poppler
 ```
 
+"Installed" is not "works": a LaTeX engine can be on the PATH and still fail on a missing package or font.
+`pdfmd --doctor --deep` also builds a small page (maths, code, a table) with every engine it found, by running pdfmd
+itself in a scratch folder, and says which one built it and how long that took, or why it could not:
+
+```console
+$ pdfmd --doctor --deep
+...
+Smoke test (a small page with maths, code and a table, built with each engine):
+OK    lualatex: built a PDF in 8.7 s
+MISS  xelatex: could not build it (! LaTeX Error: File `stix2.sty' not found.)
+OK    typst: built a PDF in 1.1 s
+```
+
+It takes a few seconds per engine (a minute or more if TeX has to fetch packages); without `--deep` nothing is built.
+
 ### Tab completion
 
 `pdfmd --completion bash|zsh|fish` prints a completion script, generated from the command
@@ -248,7 +295,7 @@ pdfmd --completion fish > ~/.config/fish/completions/pdfmd.fish
 
 The oldest Pandoc `pdfmd` is tested with is **3.1.3** (what the claude.ai sandbox has); the whole test suite runs against
 it. An older one may work, and the first build with it says so once; `pdfmd --doctor` lists what a given Pandoc does
-without. With 3.1.3: Typst PDFs cannot show a picture `pdfmd` drew itself (before 3.2), a numbered equation in a Word file
+without. With 3.1.3: a numbered equation in a Word file
 sits in a plain table instead of a borderless one (before 3.4), and `--extract-tables` leaves a table whose caption has
 a `{#tbl:id}` (before 3.8.2: Pandoc reads that as words, so the change could not be checked). A `pandoc-crossref` must be
 the release built for the Pandoc you run; one built for another is not run, with a warning, because it would put `??` where
@@ -276,7 +323,7 @@ $ pdfmd notes.md
 NOTE  Pandoc was not found: building with the built-in renderer (inkmd). The output is plain ...
 NATIVE  notes.md via inkmd
 WARN  native (inkmd): notes.md: 2 math expression(s) set as plain text (Unicode, sub/superscripts, display math centred); ...
-OK    notes.md
+OK    notes.md > notes.pdf
 ```
 
 - **[inkmd](https://github.com/eagredev/inkmd)**, written by Dylan Moir (MIT
@@ -299,6 +346,9 @@ OK    notes.md
   where the built-in renderer and every engine that can draw colour emoji
   (Typst) find it; without it emoji print as `[rocket]`-style labels in the
   built-in renderer.
+- `pdfmd --install math:mathjax` (MathJax 4 and its STIX Two math font, about 12 MB to download, about 2 MB on
+  disk) and `pdfmd --install math:katex` (KaTeX, about 1.5 MB) are for WeasyPrint's PDFs, not the built-in
+  renderer: they typeset its math (see "WeasyPrint does not typeset math itself" below).
 - `pdfmd --install full` leaves the fallback behind: it installs **Pandoc** (the
   real binary from PyPI's `pypandoc_binary`, about 35 MB, also `--install pandoc`
   / `pdfmd-cli[pandoc]`) and **Typst** (Typst's own release from GitHub, about
@@ -309,7 +359,8 @@ OK    notes.md
 
 Every input is treated as GitHub-flavoured Markdown. Pandoc-only syntax is
 converted where possible (`\newpage` and `<!-- pagebreak -->` become a page
-break, footnotes become endnotes for inkmd, `$` prices are not mistaken for math)
+break, as they do through Pandoc with `pagebreak:`, see *Page breaks in every
+format*; footnotes become endnotes for inkmd, `$` prices are not mistaken for math)
 and removed otherwise (heading and image attributes, `:::` divs, raw LaTeX,
 `<!-- comments -->`), with one warning per kind. CSV tables
 (`::: {.csv file="data.csv"}`) work as they do with Pandoc. The title, author and date in the
@@ -368,6 +419,39 @@ letters, no tones, vowels left out where the script leaves them out. Names that
 romanize alike (homophones) are listed as ambiguous, never picked between. The
 same spelling rules find a section by its heading (`doc#tyche`).
 
+### Check a document before you build it
+
+```sh
+pdfmd report --check                  # read report.md (a scaffold and its parts too) and list what is wrong; builds nothing
+pdfmd a.md b.md --check               # several files, one report each
+pdfmd report --check --strict         # warnings fail too (exit 1), for CI
+pdfmd report --check --check-ignore heading-jump,link-missing
+```
+
+`--check` reads the source, with no Pandoc and no LaTeX, and prints compiler-style lines
+(`report.md:12: error: image not found: figs/a.png  [image-missing]`) that an editor can jump to, then
+`CHECK  report.md: 1 error(s), 2 warning(s)`. It exits 1 on an error, and on a warning too with `--strict`. It finds:
+
+| check | |
+|---|---|
+| `image-missing`, `file-missing`, `link-missing` | an image (`![](..)`, `<img>`, `\includegraphics`), a `file=` of a `.csv` div or a link to a local file that is not there |
+| `anchor-missing` | `[x](#methods)` with no heading or `{#id}` of that name (the ids Pandoc and GitHub make from a heading count) |
+| `id-duplicate`, `crossref-missing`, `ref-missing` | the same `{#id}` twice; a `@fig:x`, `@tbl:x`, `@eq:x`, `@sec:x`, `@lst:x` or `\ref{x}` nothing defines |
+| `cite-missing`, `cite-no-bibliography`, `bibliography-missing` | a `@key` the `.bib`, CSL JSON or `references:` lacks (with a "did you mean"), citations with no bibliography set, a bibliography file that is missing |
+| `footnote-missing`, `footnote-unused` | `[^1]` with no text, a `[^1]:` nobody uses |
+| `heading-jump`, `heading-space`, `heading-empty` | `#` then `###`; `#Heading` (a paragraph); a heading with no text |
+| `fence-open`, `comment-open`, `div-open`, `div-stray`, `math-open` | a code fence, `<!--`, `:::` div or `$$` that is never closed, or a stray `:::` |
+| `front-matter`, `front-matter-duplicate` | YAML that does not parse (with its line) or never closes; a key set twice |
+
+Code, comments, math and URLs are not read, so `@decorator` in a code block or `me@x.org` is not a citation. A
+document in parts is checked as one: a link to `#methods` in the scaffold is found in a part. A file with no front
+matter is taken for a fragment and its citations are not held against a missing bibliography, and neither are those of
+a document with a Lua filter or `citation-engine` (something else may do the citing). A part checked on its own cannot
+see the other parts' labels, so check the scaffold, not a part, to judge links across parts.
+Leave a check out for the project with `pdfmd-options: {check-ignore: [heading-jump]}` (a document, a metadata file or
+the config), or on one line with `<!-- pdfmd-check: ignore image-missing -->` on it or on the line above. `pdfmd --check`
+is for Markdown; the build's own `WARN` and `--strict` still catch what only a build can see.
+
 ### A small editor
 
 ```sh
@@ -381,15 +465,74 @@ Ctrl-G go to a line, Ctrl-K / Ctrl-U cut and paste a line, Ctrl-Z / Ctrl-Y undo
 when there are unsaved changes); F1 lists them. Options given beside it (`pdfmd --edit lecture -e lualatex`) are used
 for the build, and a name that does not exist yet starts a new file. It is deliberately rough: a base for what comes later.
 
+**Edit a PDF in place.** A PDF that carries its source (`--attach-source`; `pdfmd --check-source` says which do) can be
+edited and rebuilt where it lies:
+
+```sh
+pdfmd --edit report.pdf                          # the built-in editor, on the source as one file in a temporary folder
+pdfmd --edit report.pdf --editor "code --wait"   # your own: the folder is watched and rebuilt on every save
+```
+
+A document is edited as the ONE file its source is: the text with its metadata, preamble, bibliography and style, and the `.tex`
+and CSV files it reads, as blocks after the text (`<!-- pdfmd-at: ... -->` comments say on which line each one is); only what
+is not text (your package, pictures, files in sibling folders) is beside it. You edit that file; Ctrl-B (or each save with
+`--editor`) builds it, and when you leave, `report.pdf` is replaced by the rebuilt one, which carries the source again, and
+the old one is kept in `.backups/` beside it. Before it is replaced pdfmd checks that the rebuilt PDF still carries its source
+and everything the old one carried; a PDF without its source is refused (yours stays as it was), and what is missing is named.
+The temporary folder is removed when you leave. For the files it was made from, `pdfmd --restore report.pdf` (or `--unpack`). Nothing
+changes when you leave without editing, or when the last version does not build. The options of the first build are the
+ones the document and its metadata record; the command-line ones are the ones you give now, and the global metadata of
+`pdfmd --setup` is this machine's (a rebuild on another one can differ). A book built with `-r` is edited as a book: your editor gets every
+chapter file and each save rebuilds all of them in the order the book was built (the built-in editor opens the first chapter and names the
+others). `--editor CMD` also works on a Markdown file
+(a watch that rebuilds on every save, until the editor closes), and `pdfmd --setup` keeps a default editor.
+
 ### In VS Code
 
-`pdfmd --init-vscode` writes a `.vscode/tasks.json` here (build, build and open, watch, extract tables; Terminal > Run
+`pdfmd --init-vscode` writes a `.vscode/tasks.json` here (build, build and open, watch, check, extract tables; Terminal > Run
 Build Task). The [`vscode/`](https://github.com/aliperdehan/pdfmd/tree/main/vscode) folder of the repository is a small
 extension over the same command line: build (`Cmd/Ctrl+Alt+B`), build and open, build as Word/HTML/Typst/slides, extract
 tables (all, or chosen ones), file history, compare and restore, restore the source a PDF carries (right-click it). Every
 command it runs is written to the *pdfmd* output panel. Install it with `npx @vscode/vsce package` and
 `code --install-extension pdfmd-vscode-*.vsix`.
 
+### A size budget for images and output
+
+```sh
+pdfmd report --max-asset-mb 5 --max-output-mb 20     # warn about an image over 5 MB and an output over 20 MB
+pdfmd report --check --max-asset-mb 5                # list the images over 5 MB (asset-large), nothing is built
+```
+
+```yaml
+pdfmd-options:
+  max-asset-mb: 5        # one image or data file
+  max-output-mb: 20      # the file that is made (a mail server's limit, a course site's upload limit)
+```
+
+There is no budget unless one is set. With one, a build says which image is over it before it starts
+(`WARN  report.md: figs/scan.png is 14.2 MB, over the 5 MB asset budget`) and, when the file made is over the output
+budget, names it and the three largest images behind it. They are `WARN` lines, so `--strict` fails them. `--max-asset-mb 0`
+switches a document's budget off for one run.
+
+### Start from a template
+
+```sh
+pdfmd --init                          # the templates: article, report, notes, slides, book, and yours
+pdfmd --init article my-paper         # my-paper/my-paper.md + refs.bib, title, author and date filled in
+pdfmd --init report .                 # into this folder, if none of its files exist yet
+pdfmd --init notes week3 -V author="A. Author" -V title="Week 3"
+```
+
+Each template builds as it is (they are checked with `--check --strict` and built in the tests): an `article` with an
+abstract, an equation, a table and a citation with its `.bib`; a `report` with a contents page, numbered sections and a
+table read from a CSV file; `notes` (headings, math, a code block); `slides` (build with `-p`); and a `book`, a scaffold
+with its chapters in `parts/`. The title comes from the name, the author from `-V author=` or `git config user.name`.
+Nothing that exists is overwritten: pdfmd names the files in the way and writes nothing. Your own templates are a
+folder (or a single `.md` file) in the `templates/` folder of pdfmd's config folder (`pdfmd --init` shows where), or any
+folder or `.md` file named by its path. In their files and file names `{{name}}`, `{{title}}`, `{{author}}`, `{{date}}`
+and `{{year}}` are replaced (`__name__.md` becomes `my-paper.md`); any other `{{...}}` stays as written. A
+`description.txt` (one line, for the list) and a `next.txt` (what to type next) in a template folder are not copied.
+
 ### One section
 
 `pdfmd doc#onlyapart` builds just the section whose heading is "Only a Part"
@@ -417,6 +560,113 @@ pdfmd lecture --to typst -o lecture.typ
 pdfmd lecture -o lecture.tex      # a complete, compilable .tex, not a fragment
 ```
 
+### Plain Markdown: `--to gfm`
+
+```sh
+pdfmd report --to gfm                # report.gfm.md, beside report.md, never over it
+pdfmd report --to gfm -o README.md
+pdfmd report --to gfm+raw            # Pandoc's own gfm writer, with its HTML, as it was
+```
+
+`--to gfm` writes Markdown that any viewer shows as it is (GitHub, VS Code, Obsidian, a chat window): no HTML, no
+`{#id .class}` braces, no Pandoc-only syntax. pdfmd runs everything it runs for any other target first (includes, parts,
+`::: {.csv}` tables, pandoc-crossref, citations, your filters), then flattens what is left:
+
+- the title block is written (`# Title`, an `*Author, Author — date*` line, the abstract), since the front matter is not;
+- a table caption becomes `**Table 1.** text` above the table, a figure caption the same below the figure (the label
+  is split at the number pandoc-crossref wrote, in any language); `{#tbl:x}` and `{#fig:x}` are gone;
+- `<div>`, `<span>`, `<figure>` and the bibliography's wrappers are unwrapped; section numbers (`number-sections`) are
+  written into the headings; a link to a heading points at the anchor GitHub gives it, a link to a vanished id is text;
+- subscripts and superscripts are Unicode where every character has one (`H₂O`, `x²`, `CO₃²⁻`) and `_(..)` / `^(..)`
+  where not (`--gfm-scripts unicode`, the default; `html` keeps `<sub>`, `drop` writes the plain text, `ascii` always
+  writes `_2`, `^(q+z)`); math stays `$..$` and `$$..$$` (`--gfm-math fenced` writes ```` ```math ````);
+- raw HTML and raw LaTeX are read into Markdown (`<b>x</b>` becomes `**x**`, `\textbf{x}` too); a raw Typst piece, a LaTeX
+  picture (`tikzpicture`, `\chemfig`, drawn with your preamble), a PDF image and an `<img src="x.pdf">` become SVG files in
+  `<name>_files/` beside the output, linked relatively;
+- definition lists become a bold term and a paragraph; a table Markdown cannot hold (spans, several header rows, block
+  cells) is written as an HTML table, the one piece of HTML that stays, and counted in a `NOTE`;
+- what no Markdown can carry (Word XML, a LaTeX macro nothing read) is left out, and a `WARN` counts it and shows the
+  first.
+
+```yaml
+pdfmd-options:
+  gfm: {scripts: unicode, math: dollars, title: true}
+```
+
+`-o notes.gfm.md` is `--to gfm` (it is also the name a flat file gets by default from `notes.md`); `-o notes.md` alone still means Pandoc's Markdown, so name the target (`--to gfm -o notes.md`) to get the flat one under that name. The paragraphs are single lines (`--wrap=none`; pass `--wrap=auto` to Pandoc to change it). Image links stay as the document wrote them, relative to the document's folder (a `NOTE` says so when the output is written elsewhere). The result is meant to be
+final: what the flattening removes (ids, cross-reference numbers become text, citations become text) is not recoverable
+from it.
+
+#### The flat file that carries its source: `--keep-source`
+
+Flattening cannot be undone (ids, cross-reference numbers, citations and scripts are text now). So a Markdown output
+can end with its whole source in one HTML comment, the same set of files `--attach-source` puts into a PDF (the
+assembled Markdown, a manifest of the layout, the `.csv` data), and `--restore` writes them back:
+
+```sh
+pdfmd report --to gfm --keep-source            # report.gfm.md ends with the source, compressed (packed)
+pdfmd report --to gfm --keep-source readable   # the same, as escaped text you can read and diff
+pdfmd --restore report.gfm.md --list           # what it carries
+pdfmd --restore report.gfm.md                  # writes report.gfm.restored/ (never overwrites anything)
+```
+
+```yaml
+pdfmd-options:
+  keep-source: true        # or readable; --no-keep-source turns it off for a run
+```
+
+Nothing in the source can close the comment early: `packed` is base64 of the compressed source (no `-`, `<` or `>`
+in it), `readable` escapes every `>` (so no `-->` or `--!>`), a backslash, a carriage return and a line-initial `<` or `=`,
+and undoes it exactly. A source with `<!-- a <!-- b --> c -->`, `-->` in a code block, CRLF line endings or the marker
+itself comes back byte for byte. The comment also stores a hash of the Markdown above it, so `--restore` can tell
+you the file was edited since. Comments are stripped from the kept copy unless `strip-comments` says otherwise (as for
+`--attach-source`); a whole build keeps its source, a part or a section built alone does not; a kept source over 1 MB
+gets a warning, since GitHub stops showing a Markdown file that large. It works for every Markdown output: `--to gfm`,
+`gfm+raw`, `markdown`, `commonmark`.
+
+### Plain text: `--to txt`
+
+```sh
+pdfmd report --to txt                # report.txt; the same as -o report.txt
+pdfmd report --to txt --columns=100  # Pandoc's wrapping, 72 columns unless you say otherwise
+pdfmd report --to plain              # Pandoc's own plain writer, as it was
+```
+
+`--to txt` is the flat build of `--to gfm` written by Pandoc's plain writer: includes, parts, `::: {.csv}` tables,
+pandoc-crossref, citations, raw HTML and LaTeX and your filters all run first. What a text file shows: the title, the
+author line and the abstract, then headings underlined with `=` (level 1) and `-` (level 2) and numbered when the
+document numbers its sections; `Table 1. caption` above a table and `[Figure 1. caption]` for a figure; a link as
+`words <https://address>` (just the words when they are the address, or the link points into the document); no `**` or
+`_`; Unicode sub/superscripts (`H₂O`, `x²`, else `_(..)` / `^(..)`; `--gfm-scripts drop` or `ascii` change that, `html`
+means `unicode` here); math as Pandoc's plain writer sets it (`E = mc²`). A picture cannot be shown: its caption stands
+for it, and a Typst or LaTeX picture piece is left out with a `WARN`. `pdfmd-options: {txt: {scripts: unicode, title:
+true}}` holds the settings. Until 3.26.7 `--to txt` and `-o x.txt` meant Pandoc's own plain writer; that is `--to plain`.
+
+### ASCII only: `--to ascii`
+
+```sh
+pdfmd report --to ascii               # report.ascii.txt: no byte above 127
+pdfmd report --to ascii:gfm           # report.ascii.gfm.md (also ascii:markdown, commonmark, rst, org, asciidoc, plain)
+pdfmd report -o notes.ascii.txt       # the name asks for it, as notes.gfm.md asks for --to gfm
+pdfmd report -o notes.ascii.rst       # any text ending after .ascii: .gfm.md, .md, .rst, .org, .adoc
+pdfmd report --to ascii --ascii-missing escape    # what has no ASCII form: \u65e5 instead of ?
+```
+
+For a terminal, an old mail gateway, a legacy system. The build is that of the format after the colon (`txt` when there
+is none), with the words mapped to ASCII before the writer sees them, so the writer escapes what the new spelling needs:
+a `−` at the start of a line that becomes `-` is written `\-`, not taken for a list; a table's columns are measured on the
+ASCII text. What is mapped, in this order: punctuation and spaces (curly quotes, `—` as `--`, `…` as `...`, no-break
+spaces, soft hyphens), symbols (`≤` `<=`, `±` `+/-`, `→` `->`, `°` `deg`, `½` `1/2`, `©` `(c)`), Greek letters by name
+(`α` `alpha`, `Δ` `Delta`, `μm` `um`; a Greek word is spelt: `Σοφία` `Sophia`), Cyrillic with its case (`Привет`
+`Privet`), accents (`é` `e`, `ß` `ss`, `ł` `l`), subscripts and superscripts (`H_2O`, `x^2`, `CO_3^(2-)`; `--gfm-scripts
+drop` writes `H2O`), then the romanization packs for Hebrew, Arabic, Armenian, Georgian, Korean and Japanese kana, and
+Chinese and the rest when `pypinyin` or `anyascii` is installed (`pdfmd --install translit`). Math stays TeX, with macros
+(`$\alpha \geq 2$`); a link's address is percent-encoded (`%C3%A9`), not spelt. A character with no ASCII form is
+counted and named in a `WARN`, and written as `?` (`--ascii-missing question`, the default), as `\uXXXX` (`escape`), as
+nothing (`drop`), or the file is not written at all (`fail`); `pdfmd-options: {ascii: {missing: escape}}` sets it per
+document. `--keep-source` on an ASCII file keeps the source packed (the readable form would be Unicode). It applies to text
+formats only: `--to ascii:docx` is refused.
+
 ### Word and OpenDocument output
 
 Plain Pandoc ignores `papersize`, `geometry`, `mainfont` and `fontsize` when it writes `.docx`
@@ -468,6 +718,13 @@ office:
   reference-doc: house.dotx
 ```
 
+The same file can list `lua:` (Lua filters beside the document besides `<package>.lua`, which a document that loads the
+package gets by name anyway), `draft-skip:` (`commands:` that take one argument and `spans:` of a start macro up to its stop
+macro, which the label scan's draft pass need not draw, as it skips `chemfig`) and `picture-cache:` (the macro names and the
+request-file suffix a package used for the picture cache before the protocol had neutral names, see "For a package author").
+pdfmd names no package: all of this is found by reading the packages a document loads, in its preamble files or its
+`header-includes:`.
+
 ```yaml
 pdfmd-options:
   office:
@@ -482,14 +739,20 @@ pdfmd-options:
 **LaTeX in the document.** Pandoc turns `$x^2$` into a Word equation and drops everything else of
 LaTeX. For `.docx` and `.odt` pdfmd adds a filter that makes it native where it can:
 
-- `\ce{Ag+(aq) + Cl-(aq) -> AgCl(s)}` (mhchem) and `\si{\gram\per\mole}`, `\SI{5}{\milli\liter}`,
+- `\ce{Ag+(aq) + Cl-(aq) -> AgCl(s)}` (mhchem) and `\si{\gram\per\mole}`, `\qty{5}{\mL}`,
   `\num{1.5e-3}` (siunitx) become formatted text with real subscripts, charges and units, and, inside
-  math, Word equation pieces;
+  math, Word equation pieces. `\ce` is read by a port of mhchem's own parser, so it comes out as LaTeX sets it;
+  siunitx follows your `\sisetup`, `\DeclareSIUnit`s and unit shortcuts, those of your own packages too. A
+  formula with words over its arrow is an equation;
+  the same in an HTML, EPUB, Markdown, text or Typst file and a PowerPoint deck, whose writers would drop them;
 - `\begin{equation}`, `align`, `reaction`... become Word equations with their number at the right;
 - raw `figure`, `tabular`, lists, `\emph`, `\newpage`... are read by Pandoc's own LaTeX reader;
 - `\ref`, `\eqref`, `\cref`, `\Cref`, `\pageref` and the "Figure 3." in front of a caption use the numbers
   LaTeX itself gave (pdfmd builds the PDF once, in its cache, and reads the `.aux`; reused while the sources
-  are older), with the caption separator (`labelsep=`) and `\crefname`s of your preamble;
+  are older), with the caption separator (`labelsep=`) and `\crefname`s of your preamble. Each reference is a link
+  to what it names. A `\label` in a caption, in a block drawn as a picture or on any line of an equation becomes a
+  bookmark there. In OpenDocument a labelled table, figure or div, and a citation's entry in the references, get one
+  too, since its writer bookmarks none of them;
 - **what is left is drawn by LaTeX**: tikz, chemfig, a house style's own macros, math Pandoc cannot convert are compiled in
   *your document's own preamble* (the same fonts, packages and macros as the PDF, one fragment to a page), and the
   pages go into the Word file as vector pictures: an SVG with a 300 dpi PNG fallback (Word 2016 and later draw the SVG,
@@ -518,9 +781,10 @@ quick way to see what is left to give a recipe (see the profile below).
 (Pandoc's own behaviour). `office: {labels: off}` skips the PDF build (numbers are then counted).
 
 The same filter serves the other outputs when LaTeX is the problem: **the soffice fallback** (the Word file above, then LibreOffice: `pdfmd -e soffice report.md` is the `.docx` as LibreOffice draws it) now
-keeps the page size, margins and fonts, shows equations and draws what LaTeX can; a **Typst or WeasyPrint run after LaTeX
-failed** gets what the document says in LaTeX as native text or pictures instead of nothing; and HTML, Typst and
-WeasyPrint builds do it on request (`pdfmd-options: {office: {latex: auto}}`).
+keeps the page size, margins and fonts, shows equations and draws what LaTeX can. A **Typst or WeasyPrint PDF** (named
+with `-e`, or after LaTeX failed) gets what the document says in LaTeX as native text or pictures instead of nothing,
+whenever it has LaTeX they would drop; `raw: {typst: [typst]}` (or `office: {latex: off}`) keeps Pandoc's own behaviour.
+HTML and Typst *files* (`-o x.html`, `--to typst`) do it on request (`pdfmd-options: {office: {latex: auto}}`).
 
 ### Stopping part-way
 
@@ -543,6 +807,7 @@ them beside it. What the text points at otherwise (images, files a preamble
 the assembled file.
 
 ```sh
+pdfmd report --merge                                           # everything: one file that builds alone, anywhere
 pdfmd report --assemble-only --embed-metadata                  # metadata.yaml, preamble.tex, Lua filters, .bib/.csl
 pdfmd report --assemble-only --embed-metadata metadata preamble   # only those
 pdfmd report --assemble-only --embed-metadata --lua-mode ref   # name the filter instead of copying it
@@ -598,22 +863,36 @@ file you can edit again. Ask for it, on the command line or in the document:
 
 ```sh
 pdfmd report --attach-source     # the source goes into report.pdf as an attachment
-pdfmd report --bundle            # ... and the data and files its LaTeX reads
+pdfmd report --bundle            # ... and the image files too (the data and LaTeX inputs are carried anyway)
 pdfmd --restore report.pdf       # write the folder back into report.restored/
+pdfmd --check-source             # which PDFs in this folder carry their source (a file or folder works too)
 ```
 
+```console
+$ pdfmd --check-source
+NONE      WA1.pdf  no WA1.md beside it
+SOURCE    WA3.pdf  WA3.md, 52 lines, pdfmd 3.28.22
+NONE      WA5.pdf  WA5.md is beside it: pdfmd WA5.md --attach-source
+CHECK     3 PDFs: 1 with the source, 2 without
+```
+
+`--check-source` (alias `--sources`) only reads the attachment list, so it is quick on a whole folder; it notes a
+Markdown file beside the PDF that is newer than the build, and exits 1 when a PDF has no source.
+
 ```yaml
 pdfmd-options:
   attach-source: true            # alias: embed-source
-  bundle: true                   # or `all`: the whole folder, not just what the text points at
+  bundle: sources                # the default: the files the text reads, no images
+                                 # `true`: and the images · `all`: the whole folder · `false`: the source alone
   bundle-packages: true          # also your own LaTeX packages (see below)
   strip-comments: true           # the default for the attached copy; see "Comments"
   attach-bibliography: used      # or `all`
+  attach-csl: false              # the default: the citation style is named, not attached (see below)
 ```
 
 Put these in the shared metadata file and every document that finds it carries
 its source. The attachment is the assembled Markdown with the metadata,
-preamble, Lua filters, bibliography and CSL style folded in (the file
+preamble, Lua filters and bibliography folded in, and the CSL style too when `attach-csl: true` (the file
 `--assemble-only --embed-metadata` writes), plus a manifest of the original
 layout, so `--restore` gives back `report.md`, `metadata/`, `parts/` and the rest
 where they were, each as a standalone file (a symlinked metadata file or
@@ -626,17 +905,41 @@ style, a compound library, a shared bibliography and parts.
   a plain attach needs no bundle for them: a JPEG comes back byte for byte, a PNG
   as the same pixels (alpha kept), and an SVG or PDF figure as a vector PDF
   (`fig.svg` becomes `fig.pdf`, and the restored Markdown follows).
-- **`--bundle` is for what the PDF does not draw:** CSV data, LaTeX included
-  with `\input`, listings. They are stored as separate attachments (`files/...`),
-  found from the text, the preamble and, in turn, from the files found; also
-  those only your own TeX tree resolves (`\input{library}` from `texmf-home`).
-  `--bundle all` takes the whole folder except output and housekeeping. Over
-  100 MB (`bundle-max-mb`) only the source is attached. Data whose file name a
-  macro builds cannot be found: use `all`.
+- **The files the text reads travel with it.** CSV data, LaTeX included with `\input`, listings: stored as
+  separate attachments (`files/...`), found from the text, the preamble and, in turn, from the files found;
+  also those only your own TeX tree resolves (`\input{library}` from `texmf-home`). A restored report builds
+  again; only images are left out (the PDF has them). Over 100 MB (`bundle-max-mb`) only the source is
+  attached. `bundle: false` (or `--no-bundle`) keeps the source alone; `--bundle` (`bundle: true`) stores the
+  image files too, `--bundle all` the whole folder except output and housekeeping. Data whose file name a
+  macro builds cannot be found: use `all`. A Markdown output (`--keep-source`) has no PDF to take pictures
+  from and keeps the source alone unless you ask.
+- **`--restore` and `--unpack` stay short.** They count what they write by folder; `--verbose` lists every
+  file, and `--restore --list` always does.
 - **Your own LaTeX packages** (a house style in `texmf-home`) are recorded with
   their version, and `--restore` tells you what is missing; `--bundle-packages`
-  stores them too (with what they `\input` and the graphics they name).
-  The TeX distribution's own packages, fonts and Pandoc are not carried.
+  stores them too: the style file, the `<package>-pdfmd.yaml` beside it (what the package tells pdfmd: its
+  title-page keys, its picture-cache names), what it `\input`s and the graphics it hands to `\includegraphics`
+  (a logo named by `\newcommand{\LogoFile}{logo}`, not every word that happens to be a file's name). A package that sits
+  in the document's own folder, as it does in a restored source, is kept when the source is attached again. Together
+  with `attach-csl` a report that sets both in its shared metadata rebuilds on a machine with nothing of yours
+  installed (checked in an empty home folder). The TeX distribution's own packages, fonts and Pandoc are not carried.
+- **The text files are in the source's text.** The `.tex` files a document reads and its CSV data are blocks of the
+  attached `pdfmd-source.md`, after the text (`.tex` first, then the data) and before the bibliography and style at the
+  very end, so one file holds everything you edit; the pictures and your package stay separate attachments (and a file
+  that is not text, or too big, or whose line ends are mixed). `<!-- pdfmd-at: ... -->` comments say on which line each block is (an index after the front matter and one
+  before each part of the text that names a file); pdfmd writes them whenever it writes the source and removes them
+  wherever it reads one, so they never reach a build and a restore gives back your text as it was.
+- **Files in sibling folders** (`\input{../schemes/x.tex}`, a CSV in `../ir/`) are stored too, up to two folders above
+  the document's (never the home folder or above), as blocks of the text like the rest (their path starts with `..`),
+  and `--restore` puts the folder back in the same layout: the document in `<folder>/<its folder's name>/`, the siblings
+  beside it. A file with Windows line ends (CRLF all through) is a block with an `eol: crlf` line and comes back byte for
+  byte. `pdfmd --edit report.pdf` writes those files where the document reads them before every build, so editing a
+  block is editing the file; a build of the source file alone (no `--edit`) never writes outside its own folder and
+  says so when a file it reads from there is missing. A bibliography the metadata names by the real
+  folder of a symlinked metadata file (a shared `nulab.bib`) is embedded, pruned to the entries the text cites.
+- **A newer source is refused, not half restored.** The manifest has a format number (2 since v3.28.45, when the chain of
+  folders, the text files as blocks and the `..` files came in). A pdfmd that reads up to 1 stops with `was made by a
+  newer pdfmd (...); upgrade pdfmd to restore it`, and this one restores both 1 and 2.
 - **Comments.** Notes to yourself do not travel: the attached source loses its
   `<!-- -->` comments, the LaTeX preamble's `%` comments, the text between a
   `.bib`'s entries, a CSL file's XML comments and the `#` comments of YAML
@@ -649,9 +952,18 @@ style, a compound library, a shared bibliography and parts.
   comments and quoting included; `--restore` of such a PDF is a full source
   copy. The data files of `.csv` blocks (`tables/*.csv`) are always stored
   with the source.
+- **Your global metadata (`pdfmd --setup`) stays yours.** It counts in the
+  source below the document's own files, as in a build, but `--restore` does
+  not write it back. It names its keys instead, and a build of the restored
+  folder uses the global metadata of the machine it runs on.
 - **Only the bibliography entries you cite** are attached (and what they
   cross-reference), not a shared file of hundreds; `attach-bibliography: all`
   keeps it whole, and `nocite: '@*'` keeps every entry.
+- **The citation style is not attached unless you ask** (`--attach-csl`, `attach-csl: true`, `--embed-metadata csl` for an
+  assembled file). A style is 10-90 KB (apa.csl 86 KB, nu-labreport.csl 72 KB, ieee.csl 18 KB) and the global metadata sets
+  one for every document, cited or not. A style is only ever attached when the document cites something. Without it the
+  manifest records the name and `--restore` says that a build needs a style of that name (Pandoc's own `csl/` folder, or
+  beside the document); a house style that exists nowhere else should travel, so set `attach-csl: true` for it.
 - **It is opt-in, and it is everything you wrote.** An attached source includes
   what the author would not send in an email; check `--list` before sharing.
 - `--restore` never overwrites a file and never writes outside its folder. A
@@ -753,9 +1065,9 @@ stamped or backed up unless you ask (`stamp=True`, `backup=True`). A failure rai
 `variables=` a dict of Pandoc variables, `extra_args=` anything else the command line takes, `cwd=` the folder it runs
 in and `timeout=` seconds.
 
-### Other command names: `mdpdf` and `inkmd`
+### Other command names: `mdpdf`, `inkmd` and `batchmd`
 
-pdfmd also installs `mdpdf` and `inkmd` commands that take those tools' own keys
+pdfmd also installs `mdpdf`, `inkmd` and `batchmd` commands that take those tools' own keys
 and do what they did, with pdfmd behind them:
 
 ```sh
@@ -763,8 +1075,14 @@ mdpdf -o out.pdf -f ",,{page}" -a "Name" -p A4 chapter1.md chapter2.md
 inkmd notes.md -o notes.pdf --page-size a4 --family times
 cat notes.md | inkmd > notes.pdf            # standard input and output, like inkmd
 inkmd notes.md -e lualatex                   # naming another engine uses it instead
+batchmd ~/notes                              # every .md in the folder, as pdfmd -b ~/notes
+batchmd -e inkmd                             # the current folder, with the built-in renderer
 ```
 
+`batchmd` is `pdfmd -b`: each Markdown file in the folder becomes its own PDF beside it.
+It takes the current folder when you name none (`pdfmd -b` alone refuses), and every
+other option is pdfmd's.
+
 `mdpdf` turns bookmarks and attached links on and combines several inputs into one
 PDF. `inkmd` is `pdfmd -e inkmd`; like inkmd it writes the PDF to standard output
 when you give `-o -`, or no `-o` while output is piped (at a terminal it writes
@@ -787,16 +1105,17 @@ pdfmd slides -p                   # Beamer slides; each heading starts a slide
 
 ```console
 $ pdfmd notes -b
-AUTO: READER TITLE MARGIN MONOFONT. Use --verbose to see in full
-AUTO: MARGIN. Use --verbose to see in full
-AUTO: MARGIN. Use --verbose to see in full
-OK    notes/lecture.md
-OK    notes/week1.md
-OK    notes/week2.md
+DEFAULTS  margin 1in, font STIX Two Text, code in JetBrains Mono, title from heading
+AUTO: READER. Use --verbose to see in full
+OK    notes/lecture.md > lecture.pdf
+OK    notes/week1.md > week1.pdf
+OK    notes/week2.md > week2.pdf
 ```
 
 `-b` converts every `.md` in the folder into its own PDF, in parallel
-(`-j N` sets the number of workers). Add `--recursive` to include
+(`-j N` sets the number of workers). `--bopen SPEC` opens some of the finished files when
+the batch is done: `f5` the first five, `l5` the last five, `fl10` the first five and the last five, `e3` the third, sixth, ninth ... file, `s3` the first, fourth, seventh ... (Python's `[::3]`),
+`f2,l3` a mix, or none for all (any number works; the files open in the order the batch lists them). Add `--recursive` to include
 subfolders, and `-o DIR` to collect the PDFs somewhere else.
 
 ### A book or report from several files
@@ -805,7 +1124,7 @@ subfolders, and `-o DIR` to collect the PDFs somewhere else.
 $ pdfmd book -r -o book.pdf
 OK    book/01-intro.md
 OK    book/02-methods.md
-AUTO: MARGIN. Use --verbose to see in full
+DEFAULTS  margin 1in, font STIX Two Text
 OK    REPORT  book.pdf
 ```
 
@@ -851,7 +1170,36 @@ The parts are joined in filename order into one Pandoc run, so the result is
 identical to the same text in a single file: labels, citations and numbering
 work across parts, and paths are written relative to the scaffold's folder
 whichever part they are in. A part rebuilt alone is much faster to compile
-but cannot see the others, so references to them print as `??`. See
+and still shows the numbers of the others: before it is typeset, pdfmd has
+Pandoc write the LaTeX of the whole document once more (about a second, no
+images, no engine), reads which headings, captions, equations and labels it
+holds, and has LaTeX replay them at the start of the part. A reference to a
+section, figure, table or equation outside the part then prints its number
+(`Section 2`, `Equation (3)`, a `\cref` too), in the document's own number style
+(Roman sections, numbers per chapter), as a link that leads nowhere; the part's
+own sections, figures and equations continue from the parts before it. What the
+scan cannot count is whatever the document defines itself (a macro that opens
+a figure, say): that label stays `??`, and the build says the numbers are
+approximate. So does a label after a caption in an environment the document
+defines itself (a table wrapper of a house style): it prints `??`, never the
+number of the heading before it, and the build says how many there were.
+`\pageref` is always `??`. The last full build's `.aux` (cache on,
+below) is exact and is used first; the scan fills in what it does not know.
+`pdfmd-options: {seed-labels: auto|aux|scan|draft|off}` or `--seed-labels` picks
+the source (`draft` runs LaTeX once over the whole document without output and
+without drawing its pictures, TikZ, pgfplots, chemfig and images, for exact
+numbers at a fraction of a compile, though a page reference into what was left out
+prints `??`; `--no-auto draftpictures` draws them); `off` brings back the `??`. A section of an ordinary document
+(`doc#results`) gets the same for the references it makes, but keeps numbering
+its own headings from 1.
+
+For HTML, EPUB, Word, OpenDocument, Typst and PDF through an engine that is not LaTeX the
+same idea works differently: pdfmd hands Pandoc the whole document with each part in a
+marked div, lets pandoc-crossref number and resolve everything, and then keeps only the
+part you asked for (`select.lua`). Its headings, figures, tables and equations keep the
+full document's numbers, and `[@sec:x]`, `[@fig:y]` to the rest resolve (as links that
+lead nowhere). Raw LaTeX `\ref{..}` is a LaTeX-only reference: use pandoc-crossref's
+syntax for those writers. See
 [`examples/parts/`](https://github.com/aliperdehan/pdfmd/tree/main/examples/parts/).
 
 #### Faster rebuilds: the cache
@@ -863,15 +1211,32 @@ pdfmd-options:
 
 keeps LaTeX's cross-reference files between builds (in `~/.cache/pdfmd`), so
 an unchanged document is typeset once instead of two or three times, and a
-part built on its own shows the real numbers of the parts left out (taken
-from the last full build) instead of `??`. It never skips a build: Pandoc and
+part built on its own shows the exact numbers of the parts left out (taken
+from the last full build; without the cache they are counted from the
+sources, above). It never skips a build: Pandoc and
 LaTeX still process the whole document from the current sources and package
 every time, so a change shows in the next build. `cache: {plots: true}` (or
-`--cache-plots`, with nulabreport >= 1.26.0) additionally stores each plot as a
-PDF and reuses it until the package, the preamble, the engine or the plot's
-data file changes. Off by default; `--no-cache` for one build; `pdfmd --clear-cache`
+`--cache-plots`; LuaLaTeX) additionally stores each whole picture of a package that takes part
+(nulabreport's plots and chemical schemes do) as a
+PDF in the document's cache folder and reuses it (a part built alone uses the whole
+document's, unless its preamble differs by more than the title) until the package,
+the preamble, the engine, TeX Live's packages (a `tlmgr update`) or a file the plot
+read changes (its data file, a file of the package's own: checked by
+SHA-1 of the contents before every build). Off by default; `--no-cache` for one build; `pdfmd --clear-cache`
 (or deleting the folder) is always safe.
 
+*For a package author:* the protocol names no package. A style file that mentions `pdfmdCacheDir` takes part; pdfmd then
+defines `\pdfmdCacheDir` (the folder, with a trailing slash) and `\pdfmdCacheVersion` (3: the markers below are version 3) before the document. The package looks
+a picture up by its own key as `<folder>/<key>.pdf` with its size in `<key>.dim` (`\pdfmdCacheWd`, `Ht`, `Dp`), typesets
+inline on a miss, and appends `<key>@@|@@<macro>@@|@@<arguments>@@|@@<context>` to `<job>.pdfmdreq`. After the build pdfmd
+runs each request in a standalone job with the same preamble (`\pdfmdCacheRender` defined, so there is no lookup): the
+context, then `\setbox0\hbox{<macro><arguments>}`; that box is the page. A context may hold `@@plain@@` (what follows is read
+with ordinary catcodes, not expl3's: settings with spaces in their names), `@@runs=2@@` (typeset twice, for a picture
+whose arrows point at its own nodes) and `@@margin=56pt@@` (the page is the box plus that on every side, `\pdfmdCacheMargin` in
+the `.dim`: for ink that overflows its box, which you include shifted back). If the job defines `\pdfmdCachePost` after the
+box, its text comes back as `\pdfmdCachePostStored` in the `.dim`, for you to run on a hit (a global the picture changes). nulabreport's first names (`\LabPlotCacheDir`, `.plotreq`, `\Lab@pc@wd`) still work as
+aliases.
+
 **Where the cache lives.** By default in `~/.cache/pdfmd`, one folder per document.
 Folders get moved (a lab report from Downloads into OneDrive), and a cache keyed by
 the old path would be lost: so each cache folder records which document it is, and a
@@ -924,16 +1289,25 @@ Water,18.015,1.20
   braces, with the identifier as `#tbl:id` there too. A caption in the attributes wins over a line after the block.
 - A relative `file=` is found beside the document (and along the resource path), wherever Pandoc runs. With both
   `file=` and data inside the block, the file is used.
-- The delimiter is `delimiter=";"` or its name (`semicolon`, `tab`, `pipe`, `space`, `colon`, `comma`); without one it
-  comes from the extension (`.tsv` means tab) or from the first line (whichever of `,` `;` tab `|` it holds most of).
+- The delimiter is `delimiter=";"` or its name (`semicolon`, `tab`, `pipe`, `space`, `colon`, `comma`), or
+  `pdfmd-options: {csv: {delimiter: semicolon}}` for every table; without one it is guessed: whichever of `,` `;` tab `|`
+  splits the first lines into the same number of fields (the extension's own, comma or tab for `.tsv`, on a tie). When
+  the guess is not what the file's name says (a `;` file named `.csv`), the build warns and says how to name it.
 - Columns are aligned with `align="lcr"` (or `align="left,center,right"`), or by a second row in the data made of
   `---`, `:--`, `:-:`, `--:` as in a pipe table; `align=` wins. If such a row is really data, say `separator="none"`.
   `widths="5,1,1"` sets relative widths, and a second row with unequal dashes does too. Without either, pdfmd picks
   widths that suit the contents.
 - The first row is the header unless you add `header="false"`.
 - Large files are capped at 10 rows × 7 columns, so a huge CSV can't
-  silently fill 40 pages. `rows=all` or `cols=20` raise the cap. When a
-  table is cut, the PDF itself shows a note saying so.
+  silently fill 40 pages. A cut table keeps both ends: the first 7 rows, a row
+  of `…`, the last 3, and the first 5 columns, a `…` column, the last 2 (about
+  any cap keeps its last ⌊√cap⌋: 16 + 4 of 20, 25 + 5 of 30; `cut="head"` or `csv: {cut: head}` keeps the first
+  ones only). `rows=all` or `cols=20` raise the cap. When a table is cut, the
+  build warns and the PDF itself shows a note saying so. For every table of a
+  document: `--csv-rows N|all` / `--csv-cols N|all`, or
+  `pdfmd-options: {csv: {rows: all, cols: 12, cut: ends, delimiter: auto, header: false, reader: gfm}}`
+  (in the front matter, a metadata file, or the config, where `pdfmd --setup`
+  sets rows, columns, the cut and the delimiter); a div's own attributes still win.
 
 This works for every output format.
 
@@ -966,6 +1340,29 @@ line above it (or under its caption); the comment survives comment stripping, be
 A comment between a table and its caption would stop Pandoc from reading the caption as one, so there is no such
 position.
 
+### One style sheet for the page: `--css`, `pdfmd.css`, `css-scope`
+
+A `.css` file styles the writers that read CSS: HTML, EPUB, the PDF the HTML engines make (WeasyPrint and the rest) and
+Calibre. pdfmd finds `pdfmd.css` or `<name>.css` beside the document (and in its `metadata/` folder; `--no-auto css` turns the
+search off), takes `css:` from the front matter or a metadata file (Pandoc's own key), `pdfmd-options: {css: file.css}`
+(a name or a list; `pdfmd --setup` keeps one for every document) and `--css FILE`; they come in that order, the last after the
+others, as in CSS.
+
+```css
+@page { size: A4; margin: 2cm 2.5cm }                 /* paper and margins */
+body  { font-family: "STIX Two Text"; font-size: 11pt; line-height: 1.3; text-indent: 1.2em }
+a     { color: #0645AD }                              /* links */
+code, pre { font-family: "JetBrains Mono" }
+```
+
+With `css-scope: all` (`pdfmd-options`, or `--css-scope all`; the default is `html`) the sheet is read for the other writers
+too: those four rules become the paper, margins, font, size, line spacing, indent, link colour and code font that LaTeX,
+Typst and Word take, **below** what the document, its metadata and the command line set (`--verbose` says
+"body font-size 11pt -> fontsize=11pt" for each one it used, and names what it did not: headings, tables, anything else).
+Only rules that say it plainly count: `@page`, `html`/`body`/`:root`, `a`, `code`/`pre`; the last one wins; `@media print`
+counts as if it stood alone, `@media screen` and any other condition do not; a body size LaTeX has no class for (anything but 10,
+11 and 12 pt) is named, not used. It is a small reader on purpose: a CSS cascade has no counterpart in LaTeX.
+
 ### Code: wrapping and line numbers
 
 With a LaTeX engine a long line of code wraps at the margin instead of running off the page (a long path or option list
@@ -995,6 +1392,42 @@ badge works, and a Pandoc built without HTTP support (Homebrew's is) no longer d
 warning and the image's description stays. `--no-auto svg` and `--no-auto remoteimages` turn the two off, and
 `pdfmd --doctor` says which converter will be used.
 
+### Diagrams written as code
+
+````markdown
+```mermaid
+graph LR; Sample --> Reaction --> Product
+```
+
+```{.dot #fig:flow caption="The *flow* of the experiment" width=60% engine=neato}
+digraph { sample -> reaction -> product }
+```
+
+```d2
+sample -> reaction -> product
+```
+````
+
+A fenced block whose class is `mermaid`, `d2`, `dot` or `graphviz` is drawn by the tool that reads that language and the
+picture takes its place: [Graphviz](https://graphviz.org) (`dot`), [D2](https://d2lang.com) (`d2`) and
+[Mermaid](https://github.com/mermaid-js/mermaid-cli) (`mmdc`). pdfmd asks each for the format the output takes: a PDF
+for LaTeX, an SVG for HTML (inside the file, so it can be sent on its own) and Typst (a PNG for Mermaid, whose SVG
+Typst cannot show), a PNG for Word and OpenDocument, and for flat Markdown (`--to gfm`) an SVG in the `_files/` folder
+beside the output, except a Mermaid block, which stays as it is because GitHub draws it. A text output keeps the source.
+Drawings are kept in the cache by their content, so a rebuild does not draw them again. `caption="..."` makes a figure
+(`{#fig:id}` with pandoc-crossref numbers it), `width=` sizes it, `engine=` picks the Graphviz layout (`dot`, `neato`,
+`fdp`, `sfdp`, `circo`, `twopi`), `theme=` the Mermaid theme, `layout=` the D2 layout (`dagre`, `elk`). A tool that is
+not installed leaves the block as code with one warning (`--strict` makes it an error) and says how to install it;
+a diagram the tool cannot parse stays as code too, and the warning gives the tool's own words. `pdfmd --install diagram:d2`
+puts D2's release binary (17 MB, checked against the SHA-256 GitHub lists) in pdfmd's tools folder, and `--install
+diagram:dot` Graphviz built to WebAssembly (2 MB, run by node, which pdfmd fetches when there is none): it writes only SVG,
+which pdfmd converts for a PDF or Word picture with `rsvg-convert` or `inkscape` (D2 needs the same), and it sizes labels
+by Graphviz's own estimate of the font, a couple of percent off the real tool's. A tool of your own on PATH is always the one
+that runs. `pdfmd --doctor` shows which tools are there, and
+`--no-auto diagrams` turns the whole thing off. The attributes need Pandoc's Markdown (a file with front matter); a file
+read as gfm takes the plain ```` ```dot ```` form. Mermaid needs Chrome (mermaid-cli downloads one); in a sandbox
+`PDFMD_MMDC_CONFIG=puppeteer.json` is handed to `mmdc -p`.
+
 ### Editable in LibreOffice, and one file that carries its data
 
 `--hybrid` makes the PDF a LibreOffice *hybrid PDF*: besides its pages it carries an OpenDocument copy of the document
@@ -1040,9 +1473,36 @@ vector picture, a PDF for LaTeX, Typst and Word, an SVG for HTML. A syntax a fam
 included, which is odd but a clear way to say "this output has no HTML in it". A family not mentioned is left to Pandoc
 as it always was, `raw: all` lists everything, and `--no-raw` turns it off for a run. Pictures are kept in pdfmd's cache by
 their content. (An HTML file that is not self-contained points at the cache; use `--self-contained` to carry them.)
-Not yet: LaTeX pieces Pandoc cannot read (tikz, chemfig) as pictures in HTML, HTML drawn as a picture, Word XML as
+A LaTeX picture Pandoc cannot read (a `tikzpicture`, `circuitikz`, `pgfpicture`, `forest`, `\chemfig`...) is drawn by a LaTeX
+engine with the `standalone` class, after the document's own preamble and `header-includes`, and placed as a vector picture
+in HTML, Typst and flat Markdown builds (an SVG for HTML and Markdown; a piece that does not compile is reported and left
+out). Not yet: HTML drawn as a picture, Word XML as
 anything but Word XML.
 
+**Page breaks in every format.** Each output understands one way of writing a page break and drops the others: LaTeX
+takes `\newpage`, WeasyPrint a CSS-break `<div>`, Word only its own XML, Typst none of them. Ask for it and every
+spelling of the families you name becomes the output's own (LaTeX `\newpage`, Typst `#pagebreak`, a CSS break for HTML,
+EPUB and WeasyPrint, a Word or OpenDocument page break, a form feed in `--to txt`, `<!-- pagebreak -->` in `--to gfm`):
+
+```yaml
+pdfmd-options:
+  pagebreak: true              # every family; or a list of them:
+  # pagebreak: [comment, tex]
+```
+
+| family | spellings |
+|---|---|
+| `comment` | `<!-- pagebreak -->`, `<!-- page-break -->`, `<!-- newpage -->`, `<!-- new-page -->`, `<!-- pdfmd: pagebreak -->` |
+| `tex` | `\newpage`, `\pagebreak`, `\pagebreak[3]`, `\clearpage`, `\cleardoublepage` (an odd page) |
+| `html` | `<div style="page-break-after: always"></div>` (or `break-before: page`), `<div class="pagebreak"></div>`, `<hr class="pagebreak">` |
+| `div` | an empty `::: pagebreak` (or `newpage`) |
+| `typst` | a raw `` ```{=typst} `` `#pagebreak()` |
+| `word` | a raw `` ```{=openxml} `` page-break paragraph |
+
+It is off unless asked (the document, a metadata file, or `pdfmd --setup` under *Universal markup*); `--pagebreak
+[KIND ...]` and `--no-pagebreak` decide for one run. A spelling already in the output's own language stays as written,
+and slides leave a break out with a note. The built-in renderer (no Pandoc) reads the comment and TeX spellings anyway.
+
 **PDF images in HTML.** A browser does not show a PDF in `<img>`, an SVG it does. For an HTML build (a web page, an
 EPUB, a PDF through WeasyPrint) every image that is a PDF, `![fig](plot.pdf)` or `<img src="plot.pdf">`, is converted to
 an SVG with poppler's `pdftocairo` (or `mutool`, `pdf2svg`, `inkscape`) and stays vector; the first page is used and the
@@ -1057,16 +1517,16 @@ pdfmd paper.tex          # compiled directly with a LaTeX engine: reruns until
                          # no .aux/.log clutter (--keep-aux keeps them)
 pdfmd minutes.docx       # Word/PowerPoint/Excel/ODF: converted by LibreOffice
 pdfmd analysis.qmd       # handed to Quarto, so code chunks actually run
-pdfmd page.html          # built by WeasyPrint, or a browser if the page runs scripts: no Pandoc
+pdfmd page.html          # built by WeasyPrint, or a browser if the page runs scripts or has MathML: no Pandoc
 pdfmd note.typ           # compiled by Typst itself: the page setup in the file is kept
 pdfmd notes.rst          # anything else Pandoc can read (give the extension)
 ```
 
 A finished `.typ` or `.html` file goes straight to its own engine, because Pandoc would read it into its own model
 and write it out again, and the page size, the styles and the scripts would not survive the trip. For a page that is
-WeasyPrint first (it is quiet and needs no browser); a page with `<script>` goes to Chrome, Chromium, Edge or Brave
-(headless, printing the page), as does one WeasyPrint cannot draw, and wkhtmltopdf, Prince, pagedjs-cli and LibreOffice
-come after. `-e edge` (or `weasyprint`, `chromium`...) picks one. As with an Office file, such a document gets none of
+WeasyPrint first (it is quiet and needs no browser); a page with `<script>` or MathML (`<math>`, which WeasyPrint prints
+as flat text) goes to Chrome, Chromium, Edge or Brave (headless, printing the page), as does one WeasyPrint cannot draw,
+and wkhtmltopdf, Prince, pagedjs-cli and LibreOffice come after. `-e edge` (or `weasyprint`, `chromium`...) picks one. As with an Office file, such a document gets none of
 pdfmd's defaults, since it is finished; `--apply-defaults` (also in `pdfmd --setup`) gives it the title, author, date,
 language, font, font size, paper and margin of its `metadata.yaml`, ahead of its own settings so those win. A `.tex`
 file that no LaTeX engine can compile is tried through Pandoc, with a warning.
@@ -1090,10 +1550,11 @@ Most of these print an `AUTO` line, and each can be switched off individually.
 
 | `AUTO` kind | When | What happens |
 |---|---|---|
-| `READER` | a Markdown file with no YAML front matter | reads the file as GitHub-flavoured Markdown (content-sized table columns, relaxed blank-line rules) |
+| `READER` | a Markdown file with no YAML front matter | reads the file as GitHub-flavoured Markdown (content-sized table columns, relaxed blank-line rules). If the file uses what only Pandoc's Markdown reads (`H~2~O`, `x^2^`, `{#id}` attributes, raw LaTeX, fenced divs), a `NOTE` says gfm leaves it as text; `--from markdown`, a front-matter block, or `reader:` below changes it |
 | `TITLE` | a Markdown file with no front matter, first line is `# Title` | that heading becomes the document title, and the remaining headings move up one level |
 | `MARGIN` | no margin or geometry set anywhere | 1-inch margins instead of LaTeX's wide defaults |
 | `MAINFONT` | no `mainfont:` and no `-f` | STIX Two Text (Times New Roman if it isn't installed), or a serif that has the letters when the document is mostly in a script STIX Two Text lacks (Kazakh Cyrillic, say); retried with DejaVu Serif if a glyph is still missing. A font you name is never changed except by `fallback: document` |
+| `MATHFONT` | pdfmd chose the main font itself (no `-f`, no `mainfont:`/`mathfont:` in the document or its metadata), the engine is LuaLaTeX, XeLaTeX, Tectonic or Typst (Pandoc 3.12+), and the companion is installed | the math font that goes with the text font: STIX Two Math for STIX Two Text, DejaVu Math TeX Gyre for DejaVu Serif, Libertinus Math, New Computer Modern Math, TeX Gyre Termes/Pagella Math; without it formulas are set in Latin Modern Math (Typst: New Computer Modern Math). `--no-auto mathfont` (or `font`) stops it |
 | `UNICODE` | text the main font cannot draw (Arabic, Han, Greek with accents, rare symbols...) | sets each run in an installed font for its script (see *Other scripts*), instead of printing boxes |
 | `MONOFONT` | the document contains code | JetBrains Mono for code (Menlo or another installed monospace font if it isn't installed) |
 | `tablewidth` | a pipe table with plain `---` separators and long lines | picks the column widths that give the fewest lines within the text width (a column never narrower than its longest word), and gives a table that fits its natural width back; unequal dashes (`--|-----`) are kept, and `table-widths: keep` in `pdfmd-options` leaves every table as written |
@@ -1102,8 +1563,11 @@ Most of these print an `AUTO` line, and each can be switched off individually.
 | `codewrap` | code blocks in a LaTeX build | long lines wrap at the margin (`--no-code-wrap` or `--no-auto codewrap` for the old behaviour) |
 | `YAML` / `TEX` / `LUA` | project files found | attaches `metadata.yaml`, `preamble.tex`, `<name>.lua` (see below) |
 | `citeproc` | `@key` / `[@key, p. 90]` citations (as Pandoc reads them: `@key` in a code span or an e-mail address is none) | adds `--citeproc`, so citations and the reference list render from your `bibliography:` without any flag (`--no-citeproc` turns it off) |
+| `remotecsl` | `csl: https://.../ieee.csl` in the front matter or a metadata file | fetches the style once and keeps it (again after 30 days), so a Pandoc built without HTTP support and a build with no network still work: offline it takes that copy, else a style of the same name in Pandoc's own `csl/` folder, with a WARN, else Pandoc's default style with a WARN (`pdfmd-options: {csl-fallback: error}` stops instead) |
 | `crossref` | `@fig:`/`@tbl:` references or `{#fig:...}` labels | adds the `pandoc-crossref` filter, ahead of citeproc |
 | `papersize` | `pagesize: a4` (a common typo) | converts it to Pandoc's real `papersize:` |
+| `texpackages` | `\ce{H2O}` (mhchem) or `\SI{25}{\celsius}`, `\num`, `\qty` (siunitx) in a LaTeX build whose preamble does not load the package | loads it, last in the preamble, unless it is loaded already (your options win), the command is defined some other way, or the package is not installed |
+| `draftpictures` | a part (or section) built alone with `seed-labels: draft` | the draft pass over the whole document does not draw TikZ pictures (pgfplots too), `\chemfig`, chemfig schemes or images: they step no counter. A page reference into what was left out prints `??`; a picture that ends inside a macro makes pdfmd run the pass again with the pictures |
 
 `-v` explains each decision and prints the exact command it runs:
 
@@ -1115,7 +1579,7 @@ AUTO READER  lecture.md: no YAML front matter; reading as gfm
 AUTO TITLE  lecture.md: promoted leading '# ' heading to Pandoc title metadata
 AUTO MARGIN  lecture.md: no geometry/margin set; using geometry:margin=1in on LaTeX-family engines
 AUTO MONOFONT  lecture.md: has code but no monofont set; using JetBrains Mono on LaTeX-family engines
-OK    lecture.md
+OK    lecture.md > lecture.pdf  (lualatex)
 ```
 
 The second `CMD` line is the font fallback at work: STIX Two Text was
@@ -1125,6 +1589,44 @@ file paths are shortened here.)
 **When a PDF doesn't look the way the Markdown suggests, run `-v` first.**
 The cause is usually one of these automatic decisions, and `-v` names it.
 
+The closing line also names the engine that made the PDF. If an earlier one failed, the line says so, so a
+build that quietly fell back to Typst does not look like one that did not:
+
+```console
+$ pdfmd paper
+WARN  paper.md: lualatex failed (! Undefined control sequence.); trying xelatex...
+WARN  paper.md: xelatex failed (! Undefined control sequence.); trying typst...
+OK    paper.md > paper.pdf  (typst; lualatex, xelatex failed)
+```
+
+When LaTeX itself stops, the warning also says where: Pandoc reports a line of the LaTeX it wrote, so pdfmd finds those
+words in your Markdown and prints `near line 9 of paper.md: ...has \badmacro`.
+
+WeasyPrint does not typeset math itself. With MathJax in place, `pdfmd --install math:mathjax` (MathJax 4.1's TeX input
+and HTML output and the STIX Two math font, which goes with pdfmd's default body font: about 12 MB to download, about 2 MB
+on disk in `~/.local/share/pdfmd/mathjax`, each package pinned and checked against its SHA-256; and node, when there is
+none on your PATH: node's own release from nodejs.org, about 30 MB, checked the same way, into pdfmd's tools folder), a
+Markdown document built with `-e weasyprint` (or one that falls back to it) has its math typeset by MathJax before
+WeasyPrint prints it: fractions, roots, matrices, accents, limits, stretchy arrows and braces, `\ce` reactions, in the
+STIX Two Math, sized to the body font's x-height when the body is not STIX Two Text. (MathJax's other math fonts, New
+Computer Modern, TeX Gyre Termes and Pagella and DejaVu, are not offered yet: their tall delimiters built from pieces came
+out broken in WeasyPrint.) WeasyPrint draws some of MathJax's output a little off (an accent three points over its letter, a
+fraction's denominator too low, a bar that ran past its letter); pdfmd's own style rules put that right. A formula MathJax cannot read goes to KaTeX when `pdfmd --install math:katex` has put it in place (a `NOTE` says
+how many), and a formula neither reads (a macro from your LaTeX preamble, say) stays text, with one `WARN` for all of
+them. KaTeX alone, without MathJax, does what it did: `--no-auto mathjax` asks for that. Without either, the math is
+Pandoc's plain math, simple formulas in Unicode (`αᵢ ≤ β`) and the others as their TeX, with one `WARN`; Typst or a
+LaTeX engine typesets them. A math option of your own (`--mathml`, `--math-method=...`) is kept, and `--doctor` says
+which of them you get.
+
+A link to an anchor the document does not have (`[see 13.5](#135-your-own-defaults)` quoted from another document) is
+only a warning for LaTeX and HTML, but Typst stops on it. For Typst, PDF or `.typ`, such a link becomes its text, and
+one `WARN` names the anchors.
+
+`--strict` (or `pdfmd-options: {strict: true}` in the document; `--no-strict` overrides it) makes that, and every other
+warning, an error for scripts and CI: a file whose build printed a `WARN` line, or about which Pandoc warned (an image
+or citation it could not find, a LaTeX reference left undefined), is reported `FAIL` with the first warnings listed and
+the exit code is 1. The output file is kept. In a batch only that file fails.
+
 ### Other scripts
 
 <p align="center">
@@ -1238,6 +1740,10 @@ pdfmd-options:
 ---
 ```
 
+`reader:` fixes the Pandoc reader of a Markdown file (`markdown`, `gfm`, `commonmark_x`, ...; `auto` is the default
+choice described under *What it does automatically*). It is `--from` for one document, or for a whole folder or all your
+documents when it sits in `metadata.yaml` or the config file's `options:`.
+
 `pdf-engine:` takes an engine name (`lualatex`, `typst`, ...) or a family:
 `tex`, `typst`, `html` or `office`. A family limits the fallback chain to
 that kind of engine. For example, a document full of chemical structures
@@ -1261,21 +1767,45 @@ options:
   pdf-engine: lualatex
 ```
 
-**`pdfmd --setup`** changes the same defaults from a menu, without editing the files: a numbered list (nothing to
+**`pdfmd --setup`** (or `pdfmd --config`) changes the same defaults from a menu, without editing the files: a numbered list (nothing to
 install, works over ssh), each setting with its choices and what they mean. It covers what a document would otherwise
 say in `pdfmd-options:` or its front matter, for every document:
 
 - *global metadata* (a `metadata.yaml` beside the config file, below anything a document's own folder says): author, language,
   paper size, font size, page geometry, main and code font, line spacing, coloured links, table of contents, and for
   citations the bibliography file, the CSL style and linked citations;
+  The global metadata can be switched off (`--no-global-metadata`, `pdfmd-options: {global-metadata: false}`, or
+  the *Use the global metadata* row; `--global-metadata` turns it back on for one run) and replaced by a **preset**: another
+  file, `presets/NAME.yaml` beside the config file. `--preset lab` (or `lab.yaml`, or a path), `pdfmd-options: {preset: lab}`
+  in a document or a folder's metadata, or the *Which set of global metadata* row chooses it; `--preset none` takes no global
+  metadata, `default` is `metadata.yaml`. `pdfmd --setup --preset lab` edits that preset's rows (it makes the file), and
+  `pdfmd --presets` lists them and marks the one a build here would use. The command line wins, then the document, then the
+  folder's metadata, then the config.
 - characters a font lacks or none draws, fonts for other scripts, romanization packs;
-- the citation engine, the PDF engine, the default output format, HTML (one file, math method), LaTeX and reference
-  numbers in Word files;
-- PDF finishing (header, footer, bookmarks, attached links) and the source file (the "Compiled with..." stamp, backups,
-  comment stripping, attaching the source and its files to the PDF);
-- the cache, reading `.txt` as Markdown, and which of pdfmd's automatic behaviours (`--no-auto` kinds) are off.
-
-Choosing 0 (for a text, `-`) gives a setting its built-in default back; `s` saves, `q` quits. The files are rewritten without your
+- the citation engine; output (the PDF engine, the default output format, defaults for `.typ` and `.html` files);
+  HTML (full page, one file, style sheet, math method); tables (the rows, columns, cut and delimiter of `.csv` tables,
+  pipe-table widths); code (wrapping, line numbers); Word and OpenDocument (LaTeX in them, reference numbers, the
+  template);
+- plain Markdown, text and ASCII output (`--to gfm`, `txt`, `ascii`: scripts, math, title block, the source carried at
+  the end);
+- PDF finishing (header, footer, bookmarks, attached links, a hybrid PDF); the build history (the "Compiled with..."
+  stamp and its details); backups (their folder, names and how many are kept); the source inside the PDF (attaching
+  the source, its files and its LaTeX packages, comment stripping);
+- the cache (reference numbers, plots, a part built alone); input (the Markdown reader, reading `.txt` as Markdown, raw
+  pieces);
+- checks and limits (`--strict`, the size budgets, the codes `--check` leaves out), and which of pdfmd's automatic
+  behaviours (`--no-auto` kinds) are off.
+
+Every flag and every `pdfmd-options` key is either one of these rows or left out on purpose: `o` lists the rest (commands,
+what is about one run or one document, trust, what pdfmd writes for itself) with the reason, and a test keeps that
+complete. Choosing 0 (for a text, `-`) gives a setting its built-in default back; `s` saves, `q` quits.
+
+**Switching whole features off.** `d` in `--setup` (or `disabled: [history, tables]` in `config.yaml`) switches off
+features you never use: modes, source, tables, history, code, raw, markdown, fonts, builtin, office, cache (the topics
+of `--help`; output, setup and debug stay on). Their options leave `--help`, shell completion (regenerate it with
+`--completion`) and the setup screen, and the command line refuses them; `pdfmd --disabled --history doc` uses one for a
+single run and `pdfmd --disabled --help all` shows them. A document's own `pdfmd-options` still apply, so a document
+from someone else builds the same. In the full-screen setup, `r` resets a row (it used to be `d`). The files are rewritten without your
 comments (the old one is kept as `.bak`). The same keys can be written by hand under `options:` of `config.yaml`. A
 full-screen version is optional: `pdfmd --install tui` (prompt_toolkit, about 1 MB), then `pdfmd --setup fancy`, or set
 "This setup screen" to fancy to make it the one `pdfmd --setup` opens. The first time pdfmd finishes a build in a terminal
@@ -1306,11 +1836,37 @@ files could apply and none is clearly meant, `pdfmd` stops and asks you to
 choose with `-y FILE`, rather than guessing. `-y` alone turns discovery
 off.
 
+**When two metadata files set the same key, the later one wins**, as in Pandoc:
+`<name>.yaml` over `metadata.yaml`, `report.yaml` over `metadata.yaml`, and the
+second of `-y base.yaml -y extra.yaml`. This holds for Pandoc's keys and for
+pdfmd's own (`pdfmd-options:`, `margin:`), key by key: the earlier file still
+gives whatever the later one leaves out. The document's own front matter beats
+every file. `--metadata-precedence first` (or `metadata-precedence: first` in
+`pdfmd --setup`, under Input) turns this round so that the first file wins.
+Until 3.27.22, pdfmd's own keys followed that `first` rule while Pandoc's followed
+the later file.
+
+A `header-includes:` stays when a preamble file joins it: the document's own, or
+else the one of the metadata file that wins (above). The same holds
+for the header files pdfmd adds itself, such as the code-wrapping header of a
+document with code. A metadata file's lines go before `preamble.tex`, and the
+document's own go after everything. An `--include-in-header` you pass yourself
+replaces them all, as it does in Pandoc. The global `metadata.yaml` that
+`pdfmd --setup` writes is the lowest of all metadata files.
+
 With a `metadata/` folder, a report's own folder can hold nothing but
 `report.md` and `report.pdf`. Relative paths inside the metadata (such as
 `bibliography: refs.bib`) resolve from `metadata/`, and image paths in the
 document still resolve from the document's own folder.
 
+**A Lua filter can run any command**, so pdfmd tells you about the ones it picks up by itself. The first build with a
+`<name>.lua` (or `nulabreport.lua`) it has not run before prints one `NOTE`, and so does the first build after the file
+changed; the filter runs all the same, and there is never a prompt, so a filter you edit every day, `-j`, `-w`, CI and the
+Python API are not held up. `pdfmd --trust-lua ~/work/reports` marks a folder you work in (or one filter, as it is now):
+nothing under it is noted again. Only `--strict` skips a new or edited filter outside such a folder. pdfmd remembers
+each filter's path and SHA-256 in `known-lua.txt` beside its config. This is a notice, not a lock: it does not protect
+the first build of a folder you have just downloaded, so read its `.lua` first.
+
 One shared metadata file can also be **symlinked** into many folders. A
 relative `bibliography: refs.bib` inside it then finds the `refs.bib`
 next to the file's real copy, so you never need an absolute path.
@@ -1381,3 +1937,7 @@ read with `pdfinfo -meta`. Turn this off with `--no-stamp-pdf-metadata`.
 ## License
 
 [MIT](https://github.com/aliperdehan/pdfmd/blob/main/LICENSE)
+
+`pdfmd_mhchem/` is a Python port of Martin Hensel's
+[mhchemParser](https://github.com/mhchem/mhchemParser) (the parser of mhchem's `\ce` and `\pu` that MathJax and KaTeX
+use) and keeps its [Apache License 2.0](https://github.com/aliperdehan/pdfmd/blob/main/pdfmd_mhchem/LICENSE).