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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfmd-cli
-Version: 3.25.20
+Version: 3.26.20
 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
@@ -233,6 +233,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
@@ -368,6 +383,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
@@ -383,13 +431,50 @@ for the build, and a name that does not exist yet starts a new file. It is delib
 
 ### 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 +502,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`
@@ -851,7 +1043,31 @@ 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. `\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, for
+exact numbers at about half a compile's cost); `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,8 +1079,9 @@ 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
@@ -995,6 +1212,37 @@ 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. `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,7 +1288,10 @@ 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.
 
 **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
@@ -1090,7 +1341,7 @@ 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` |
@@ -1115,7 +1366,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  (lualatex)
 ```
 
 The second `CMD` line is the font fallback at work: STIX Two Text was
@@ -1125,6 +1376,24 @@ 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  (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`.
+
+`--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 +1507,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
@@ -1311,6 +1584,14 @@ With a `metadata/` folder, a report's own folder can hold nothing but
 `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.