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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfmd-cli
-Version: 3.28.49
+Version: 3.29.24
 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 AND Apache-2.0
@@ -245,8 +245,60 @@ when none can. `pdf-engine:` in `pdfmd-options`, the front matter, a metadata fi
 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:`).
+or drawn as a picture, as for a Word file. Calibre is not in the numbered chain: it comes first when you
+name it (`-e calibre`, or `pdf-engine: calibre` in `pdfmd-options:`), and (v3.29.1) it and the browsers
+(`-e edge`, `chrome`, `chromium`, `brave`: Pandoc's HTML page, printed headless) are tried last when no engine is named
+and LaTeX, Typst and the HTML engines have all failed, ahead of LibreOffice; `--doctor` lists them as last resorts.
+A comma list of your own never adds them (`-e pandoc` is every engine Pandoc drives, not these).
+
+With no Pandoc at all, Calibre reads the Markdown itself (v3.29): its own Markdown reader (tables, footnotes, fenced code, lists)
+prints it, before the rough built-in renderers, with the document's paper and margins. It has no math (formulas are text) and
+none of Pandoc's syntax, and says so (`NOTE`, `WARN`). `-e calibre` or `-e native` without Pandoc picks it; with Pandoc,
+`-e calibre` is the HTML route above.
+
+`pdfmd --install calibre` (v3.29) gets Calibre when it is missing (190 to 360 MB). In a terminal on a Mac or Windows it offers
+`brew install --cask calibre` or `winget install --id calibre.calibre -e` first. Otherwise (or on answering `d`) pdfmd downloads the
+release file for your machine and checks it against the SHA-256 GitHub lists for it, and refuses a download whose checksum is not
+listed: on macOS it opens the disk image read-only and copies `calibre.app` into `~/Applications`, on Linux (x86-64, ARM)
+it unpacks the archive into pdfmd's data folder (no root, no desktop entries), and either way runs `ebook-convert --version`
+to check. Windows: `winget`, or the installer from calibre-ebook.com. Calibre is a program pdfmd runs, never one it contains.
+
+A browser prints a Markdown document too (v3.29): `-e edge`, `-e chrome`, `-e chromium` or `-e brave` (or `-e browser` for the
+first one installed) has Pandoc write one self-contained HTML page and the browser, headless, print it with the document's
+paper and margins (`papersize`, `geometry`, `margin`: as `@page`) and 12pt text. The math is MathML, which the browser draws
+itself; LaTeX in the document is made native or drawn as a picture, as for a Word file. Like Calibre, a browser comes first when you
+name it and last when you do not (see above); an `.html` file already goes to one first when it has scripts or MathML.
+
+Calibre also writes ebooks (v3.29): `pdfmd book.md -o book.azw3` (or `--to azw3`) has Pandoc write an EPUB 3 (chapters,
+contents, the metadata, the math as MathML) and Calibre turn it into the target, `book.azw3` beside the document. The
+twelve targets only Calibre writes are `azw3`, `mobi`, `kepub`, `lit`, `lrf`, `pdb`, `rb`, `snb`, `tcr`, `pmlz`, `htmlz`
+and `txtz`; each was converted back to text to check that its words, list and table are there. (Before v3.29 `-o
+book.azw3` wrote a PDF under that name.) `epub`, `docx`, `rtf`, `txt` and `fb2` Pandoc writes itself, with more of its own
+features (styles, tables, footnotes); they go through Calibre only when `-e calibre` is on the command line (a
+`pdf-engine: calibre` is a PDF setting), with a NOTE. `-e calibre` with another target (`.tex`, `.html`, `.md`) stops and
+lists what Calibre writes. One document at a time, not `-b` or `-r`.
+
+The math of an ebook: a Kindle or a Kobo does not draw MathML, and a MOBI has no place for it. `azw3`, `mobi`, `kepub`, `lit`
+and `lrf` (and `docx` through Calibre) get each formula drawn by LaTeX as a picture, in the document's own preamble and with
+its `\ce` and siunitx, as a Word file's pictures are (needs a LaTeX engine and Poppler's `pdftocairo`); the plain formats
+(`pdb`, `rb`, `snb`, `tcr`, `pmlz`, `txtz`, `rtf`, `txt`, `fb2`) get the formulas as text, the simple ones with their
+superscripts and the rest as TeX, with one `WARN` that counts them, and so does a picture target on a machine with no LaTeX.
+`epub` and `htmlz` keep the MathML. A `--mathml` or `--math-method` of your own is kept.
+
+An ebook can be the input too (v3.29): `pdfmd book.epub` builds `book.pdf` beside it, `pdfmd book.mobi -o book.md` writes its
+Markdown (with its pictures in `media/`) for you to edit, `pdfmd book.azw3 --to docx` a Word file. An EPUB is read by Pandoc;
+`mobi`, `azw`, `azw3`, `azw4`, `kepub`, `lit`, `lrf`, `pdb`, `prc`, `chm`, `snb`, `tcr`, `rb`, `pmlz`, `htmlz` and `txtz` first go
+through Calibre's `ebook-convert` into an EPUB (Calibre is needed for those, not for an EPUB). The closing line names the
+book. One book at a time, not with other files, `-b` or `-r`; a book with DRM, and an ebook of nothing but pictures (a comic),
+cannot be read. A formula a MOBI holds as a picture stays a picture. Calibre's own scaffolding in the converted book (an
+anchor for every file it split the book into, its page-break divs and classes) is dropped from the Markdown; with
+`-o book.md` the pictures are copied to a `media/` folder beside it.
+
+LibreOffice writes what Pandoc cannot too (v3.29): `pdfmd letter.md -o letter.doc` (Word 97) has Pandoc write the Word file (the
+same one `-o letter.docx` writes: your reference document, native equations and tables, pictures for what LaTeX alone can draw)
+and headless LibreOffice turn it into `.doc`. `rtf`, `odt`, `txt` and `epub` go through LibreOffice only with `-e soffice` (or
+`-e libreoffice`, `-e office`) first on the command line, with a NOTE; without it Pandoc writes them from the document itself,
+which is the better file. `-e soffice` with another target (`.tex`, `.md`) lists what it writes.
 
 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
@@ -278,6 +330,8 @@ MISS  xelatex: could not build it (! LaTeX Error: File `stix2.sty' not found.)
 OK    typst: built a PDF in 1.1 s
 ```
 
+The last resorts are tried too (v3.29): an installed browser (`edge: built a PDF in 6.1 s`) and Calibre, which also writes a small
+ebook (`calibre:azw3: built an AZW3 ebook in 18.0 s`), so a missing Qt library shows here and not in the middle of a book.
 It takes a few seconds per engine (a minute or more if TeX has to fetch packages); without `--deep` nothing is built.
 
 ### Tab completion
@@ -349,6 +403,10 @@ OK    notes.md > notes.pdf
 - `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 core:tex` (also `cortex`, about 50 MB) is the other core: **Pandoc and Tectonic**, the self-contained
+  LaTeX engine (its release from GitHub, checked against the SHA-256 GitHub lists, into pdfmd's own tools folder). Tectonic
+  fetches the TeX files a document needs from the network the first time, then works from its cache. `core:typst`
+  (or `core`) is `--install full` below. `pan-tec` (see "Other command names") runs pdfmd on it.
 - `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
@@ -1065,9 +1123,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`, `inkmd` and `batchmd`
+### Other command names: `mdpdf`, `inkmd`, `batchmd` and `pan-tec`
 
-pdfmd also installs `mdpdf`, `inkmd` and `batchmd` commands that take those tools' own keys
+pdfmd also installs `mdpdf`, `inkmd`, `batchmd` and `pan-tec` commands that take those tools' own keys
 and do what they did, with pdfmd behind them:
 
 ```sh
@@ -1079,6 +1137,10 @@ batchmd ~/notes                              # every .md in the folder, as pdfmd
 batchmd -e inkmd                             # the current folder, with the built-in renderer
 ```
 
+`pan-tec` is the first version of pdfmd, a shell function around `pandoc "$@" --pdf-engine=tectonic --pdf-engine-opt=--chatter=minimal`
+(v3.29): `pan-tec test.md -o ex.pdf` is `pdfmd -e tectonic test.md -o ex.pdf --pdf-engine-opt=--chatter=minimal`, with everything else
+pdfmd does. Name another engine (`-e typst`) or a chatter level of your own and that is used instead.
+
 `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.
@@ -1297,6 +1359,12 @@ Water,18.015,1.20
   `---`, `:--`, `:-:`, `--:` 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.
+- **A spreadsheet** (v3.29) works as the file: `::: {.csv file="results.xlsx" sheet="Run 2"}` (`.xlsx`, `.xlsm`, `.xls`, `.ods`;
+  `sheet=` is a name or a number counted from 1, the first sheet when it is left out). The sheet is read by `openpyxl` (xlsx and
+  xlsm: the values the file stores, so a cell shown as `1.50` is `1.5`, a date is `2026-01-02`), else by `pandas`, else by
+  LibreOffice (the sheet by number); none of them is a `WARN` that says what to install (`pip install openpyxl`). The converted
+  CSV is kept in pdfmd's cache by the file's content, the attached source carries the spreadsheet itself, and
+  `--expand-tables` reads it too.
 - 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. A cut table keeps both ends: the first 7 rows, a row
@@ -1358,10 +1426,28 @@ 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.
+"body font-size 11pt -> fontsize=11pt" for each one it used, and names what it did not: tables, anything else).
+Only rules that say it plainly count: `@page`, `html`/`body`/`:root`, `a`, `code`/`pre`, `h1`-`h5`; the last one wins. A media
+query is read as a browser prints (v3.29): `print` and `all` apply, `screen` and the other media types do not, a comma is "or",
+`only` and `not` count, `(orientation: landscape)` is read against the sheet's own `@page` size, and a feature of the screen or of
+a width (`(min-width: 600px)`) is not for a printed page and is named. 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.
+
+Headings (v3.29): `h1`-`h5` with a `color`, `font-size` (`em`, `%`, `pt`, `px`: of the body's size), `font-family`,
+`font-weight` or `font-style` are set for LaTeX too, as titlesec's starred formats (the numbering and the spacing stay the
+class's; `h1` is `\section`, `h2` `\subsection` ... `h5` `\subparagraph`; `h6` has no LaTeX level). It is done only for the plain
+article class, and never over a document that formats its headings itself: a `titlesec`, `sectsty`, KOMA or memoir command, or a
+`\section` of its own, in the preamble, the `header-includes` or a metadata file, is named in a `CSS` note and nothing is added
+(and when `titlesec` is not installed, one LaTeX warning says so). A family needs XeLaTeX or LuaLaTeX.
+
+### A cover: `cover`
+
+`pdfmd-options: {cover: true}` puts the title block (title, subtitle, author, date) on a page of its own and starts the text
+on the next (v3.29): LaTeX's `titlepage` class option (for the article, report and book classes and KOMA's; another class is
+left alone), and a page break after the title block of an HTML-family PDF (WeasyPrint, a browser, Calibre) or an HTML page.
+`cover: picture.png` (relative to the document) puts that picture on the first page of such a PDF, before the title, and is the
+cover of an EPUB, so of the Kindle book Calibre makes from it (Pandoc's own `cover-image:` does the same for an EPUB). A
+Word, OpenDocument or Typst file says once that the key was not applied. Off by default: the title block stays on page 1.
 
 ### Code: wrapping and line numbers
 
@@ -1503,6 +1589,79 @@ It is off unless asked (the document, a metadata file, or `pdfmd --setup` under
 [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.
 
+**Callouts in every format** (v3.29, the first kind of *universal markup* after page breaks). GitHub's and Obsidian's
+`> [!NOTE]`, a fenced `::: note` and Quarto's `::: callout-tip` are a block quote or a div to Pandoc, and print as plain text.
+Ask for them and each becomes a box of the writer's own: LaTeX a `tcolorbox` (a plain indented quote when that package is not
+installed), Typst a tinted block, HTML, EPUB and the HTML engines' PDFs a `div.callout` with its style, every other writer
+(Word, OpenDocument, Markdown ...) a block quote with a bold title:
+
+```yaml
+pdfmd-options:
+  markup: callouts             # or: markup: true (every kind there is)
+```
+
+```markdown
+> [!warning] Mind the gap
+> The title is the rest of the first line, the body the lines after it.
+
+::: {.tip title="Another way"}
+A fenced div takes `note`, `tip`, `important`, `warning` or `caution` as its class, `title=` for the title.
+:::
+```
+
+The five kinds are GitHub's (`note`, `tip`, `important`, `warning`, `caution`); Obsidian's others map to them (`info`, `todo`,
+`example`, `abstract` to note; `success`, `check`, `hint` to tip; `question`, `help`, `faq` to important; `failure`, `danger`,
+`error`, `bug` to caution; `attention` to warning), and an unknown name is a note titled with it. A fold marker (`[!tip]-`) is
+dropped. Off unless asked (the document, a metadata file, or `pdfmd --setup` under *Universal markup*); `--markup [KIND ...]` and
+`--no-markup` decide for one run. The built-in renderer (no Pandoc) does not read it yet, and there is no Word shaded box yet.
+
+**A table of contents where you put it** (v3.29, `markup: toc`). `[TOC]`, `[[_TOC_]]` and `<!-- toc -->` alone in a paragraph, or
+a raw `\tableofcontents` for a writer that is not LaTeX, become the contents at that place: LaTeX's `\tableofcontents` (filled in
+one build, with the page numbers), Typst's `#outline()`, a Word TOC field (Word offers to update it when the file is opened) and,
+for every other writer (HTML, EPUB, Markdown, OpenDocument ...), a nested list of links to the headings down to level 3, with a
+bold "Contents" above it. `markup: [callouts, toc]` or `markup: true` for both; `--markup toc` for one run. A marker inside a
+sentence is text.
+
+**Centred text** (v3.29, `markup: center`). `<center>` ... `</center>` around blocks (the closing tag in its own paragraph),
+`<div align="center">`, `<div style="text-align: center">`, a fenced `::: center` and, for writers that are not LaTeX, a raw
+`\begin{center}` ... `\end{center}` all centre what they hold: LaTeX's `center` environment, Typst's `#align(center)[...]`, a
+`text-align` div in HTML, EPUB and the HTML engines' PDFs. Word and OpenDocument keep the text as it is and say so once (no
+centring for a block there yet). `markup: [callouts, toc, center]` or `true` for all; `--markup center` for one run.
+
+**Highlighted text** (v3.29, `markup: highlight`). `==marked text==` (across several words, with emphasis inside, over a line
+break) is highlighted: LaTeX with `soul`'s `\hl` in a pale yellow (plain text when `soul` is not installed), Typst with
+`#highlight[...]`, HTML, EPUB and `--to gfm` with `<mark>`; Pandoc's own Markdown output keeps `==...==`, and Word and OpenDocument
+keep the text and say once that it is not highlighted. A lone `==` or one inside code stays as written; a closing `==` followed by
+punctuation (`==end==.`) works. `markup: [callouts, toc, center, highlight]` or `true` for all; `--markup highlight` for one run.
+
+**Blocks kept on one page** (v3.29, `markup: keep`). A fenced `::: keep` (also `nobreak`, `keep-together`), a div with
+`style="break-inside: avoid"` and, for writers that are not LaTeX, a raw `\begin{samepage}` ... `\end{samepage}` hold what they
+contain on one page where it fits: LaTeX's `samepage` environment, Typst's `#block(breakable: false)[...]`, a `break-inside:
+avoid` div in HTML, EPUB and the HTML engines' PDFs. Word and OpenDocument keep the text and say once that it is not held.
+`--markup keep` for one run.
+
+**Landscape pages** (v3.29, `markup: landscape`). A fenced `::: landscape`, a div with `style="page: landscape"` and, for writers
+that are not LaTeX, a raw `\begin{landscape}` ... `\end{landscape}` put what they hold on pages turned sideways, the document
+going back to portrait after it: LaTeX with `pdflscape` (the page is rotated in the PDF; `lscape`, or no turning, when it is not
+installed), Typst with `#page(flipped: true)[...]`, WeasyPrint and the browsers with a named page (`@page landscape`: the browsers
+get the document's paper turned; WeasyPrint's is its own A4 unless your own `@page landscape` says otherwise). Calibre's PDF cannot
+name page types, and Word and OpenDocument have no sections made from here: they keep the text and say once that no landscape page
+was made. `--markup landscape` for one run.
+
+**Where the appendix starts** (v3.29, `markup: appendix`). A raw `\appendix`, `<!-- appendix -->` or a heading with the class
+`{.appendix}` marks the start: the sections after it are lettered (A, B, A.1) in LaTeX (`\appendix`) and Typst (a heading
+numbering of letters and a counter reset). It matters for a document that numbers its sections (`--number-sections`); without
+numbers Typst gets nothing and LaTeX's `\appendix` changes nothing visible. Other writers keep their own numbering and say once
+that the lettering is not made.
+
+**Showing the comments of the text** (v3.29, `show-comments`). An `<!-- HTML comment -->` is invisible in every output. With
+`pdfmd-options: {show-comments: true}` (or `--show-comments` for one run, `--no-show-comments` to switch it off; also a row in
+`pdfmd --setup`) each one is shown: a box labelled *Comment* in LaTeX, Typst, HTML, EPUB and the HTML engines' PDFs, a real Word
+comment in a `.docx` (anchored on the paragraph after it, so Word's review pane lists them), `[comment: ...]` in italics for one
+inside a paragraph. The Markdown family (`--to gfm`, `markdown`) keeps the comment as it is; OpenDocument and PowerPoint drop
+it, with a note once. pdfmd's own markers stay invisible (`<!-- pdfmd: ... -->`, `<!-- pagebreak -->`, `<!-- toc -->`,
+`<!-- appendix -->`), and so does an empty comment. It is off unless asked and is not one of the kinds `markup: true` turns on.
+
 **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
@@ -1760,6 +1919,17 @@ document or its metadata files say (the command line beats all of them);
 `translit:` is the romanization packs of the name lookup. `PDFMD_CONFIG=other.yaml`
 uses another file, `PDFMD_CONFIG=` (empty) none.
 
+**Settings for a folder** (v3.29): a `.pdfmd/config.yaml` in a document's folder, or in any folder above it, has the same
+`options:` for everything under it. The order, strongest first: the command line, the document's `pdfmd-options`, its metadata
+files, the folder settings (the nearest folder first, then the ones above it), your global `config.yaml`, pdfmd's own defaults.
+`inherit: false` in a folder's file stops the walk upward there. A folder cannot set what belongs to this computer (`translit`,
+`setup-ui`, `disabled`): they are ignored with a `WARN`. A mapping such as `stamp:` or `backup:` in a folder's file stays off
+until it says `enabled: true`, as in the global file. A build lists the folder files it used on its `FOUND` line
+(`--verbose`: `AUTO SETTINGS`). A folder's options cannot name code (a Lua filter or a preamble is read from the document's own
+front matter only), a `.pdfmd/config.yaml` owned by another user (a shared `/tmp`) is not read, and a path in it (`css: house.css`)
+is relative to the document, as everywhere, not to the folder file. Writing the file from `pdfmd --setup DIR`, and carrying it in
+an attached source, are not done yet.
+
 ```yaml
 translit: [greek, hangul]
 options:

{pdfmd_cli-3.28.49 → pdfmd_cli-3.29.24}/README.md

@@ -210,8 +210,60 @@ when none can. `pdf-engine:` in `pdfmd-options`, the front matter, a metadata fi
 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:`).
+or drawn as a picture, as for a Word file. Calibre is not in the numbered chain: it comes first when you
+name it (`-e calibre`, or `pdf-engine: calibre` in `pdfmd-options:`), and (v3.29.1) it and the browsers
+(`-e edge`, `chrome`, `chromium`, `brave`: Pandoc's HTML page, printed headless) are tried last when no engine is named
+and LaTeX, Typst and the HTML engines have all failed, ahead of LibreOffice; `--doctor` lists them as last resorts.
+A comma list of your own never adds them (`-e pandoc` is every engine Pandoc drives, not these).
+
+With no Pandoc at all, Calibre reads the Markdown itself (v3.29): its own Markdown reader (tables, footnotes, fenced code, lists)
+prints it, before the rough built-in renderers, with the document's paper and margins. It has no math (formulas are text) and
+none of Pandoc's syntax, and says so (`NOTE`, `WARN`). `-e calibre` or `-e native` without Pandoc picks it; with Pandoc,
+`-e calibre` is the HTML route above.
+
+`pdfmd --install calibre` (v3.29) gets Calibre when it is missing (190 to 360 MB). In a terminal on a Mac or Windows it offers
+`brew install --cask calibre` or `winget install --id calibre.calibre -e` first. Otherwise (or on answering `d`) pdfmd downloads the
+release file for your machine and checks it against the SHA-256 GitHub lists for it, and refuses a download whose checksum is not
+listed: on macOS it opens the disk image read-only and copies `calibre.app` into `~/Applications`, on Linux (x86-64, ARM)
+it unpacks the archive into pdfmd's data folder (no root, no desktop entries), and either way runs `ebook-convert --version`
+to check. Windows: `winget`, or the installer from calibre-ebook.com. Calibre is a program pdfmd runs, never one it contains.
+
+A browser prints a Markdown document too (v3.29): `-e edge`, `-e chrome`, `-e chromium` or `-e brave` (or `-e browser` for the
+first one installed) has Pandoc write one self-contained HTML page and the browser, headless, print it with the document's
+paper and margins (`papersize`, `geometry`, `margin`: as `@page`) and 12pt text. The math is MathML, which the browser draws
+itself; LaTeX in the document is made native or drawn as a picture, as for a Word file. Like Calibre, a browser comes first when you
+name it and last when you do not (see above); an `.html` file already goes to one first when it has scripts or MathML.
+
+Calibre also writes ebooks (v3.29): `pdfmd book.md -o book.azw3` (or `--to azw3`) has Pandoc write an EPUB 3 (chapters,
+contents, the metadata, the math as MathML) and Calibre turn it into the target, `book.azw3` beside the document. The
+twelve targets only Calibre writes are `azw3`, `mobi`, `kepub`, `lit`, `lrf`, `pdb`, `rb`, `snb`, `tcr`, `pmlz`, `htmlz`
+and `txtz`; each was converted back to text to check that its words, list and table are there. (Before v3.29 `-o
+book.azw3` wrote a PDF under that name.) `epub`, `docx`, `rtf`, `txt` and `fb2` Pandoc writes itself, with more of its own
+features (styles, tables, footnotes); they go through Calibre only when `-e calibre` is on the command line (a
+`pdf-engine: calibre` is a PDF setting), with a NOTE. `-e calibre` with another target (`.tex`, `.html`, `.md`) stops and
+lists what Calibre writes. One document at a time, not `-b` or `-r`.
+
+The math of an ebook: a Kindle or a Kobo does not draw MathML, and a MOBI has no place for it. `azw3`, `mobi`, `kepub`, `lit`
+and `lrf` (and `docx` through Calibre) get each formula drawn by LaTeX as a picture, in the document's own preamble and with
+its `\ce` and siunitx, as a Word file's pictures are (needs a LaTeX engine and Poppler's `pdftocairo`); the plain formats
+(`pdb`, `rb`, `snb`, `tcr`, `pmlz`, `txtz`, `rtf`, `txt`, `fb2`) get the formulas as text, the simple ones with their
+superscripts and the rest as TeX, with one `WARN` that counts them, and so does a picture target on a machine with no LaTeX.
+`epub` and `htmlz` keep the MathML. A `--mathml` or `--math-method` of your own is kept.
+
+An ebook can be the input too (v3.29): `pdfmd book.epub` builds `book.pdf` beside it, `pdfmd book.mobi -o book.md` writes its
+Markdown (with its pictures in `media/`) for you to edit, `pdfmd book.azw3 --to docx` a Word file. An EPUB is read by Pandoc;
+`mobi`, `azw`, `azw3`, `azw4`, `kepub`, `lit`, `lrf`, `pdb`, `prc`, `chm`, `snb`, `tcr`, `rb`, `pmlz`, `htmlz` and `txtz` first go
+through Calibre's `ebook-convert` into an EPUB (Calibre is needed for those, not for an EPUB). The closing line names the
+book. One book at a time, not with other files, `-b` or `-r`; a book with DRM, and an ebook of nothing but pictures (a comic),
+cannot be read. A formula a MOBI holds as a picture stays a picture. Calibre's own scaffolding in the converted book (an
+anchor for every file it split the book into, its page-break divs and classes) is dropped from the Markdown; with
+`-o book.md` the pictures are copied to a `media/` folder beside it.
+
+LibreOffice writes what Pandoc cannot too (v3.29): `pdfmd letter.md -o letter.doc` (Word 97) has Pandoc write the Word file (the
+same one `-o letter.docx` writes: your reference document, native equations and tables, pictures for what LaTeX alone can draw)
+and headless LibreOffice turn it into `.doc`. `rtf`, `odt`, `txt` and `epub` go through LibreOffice only with `-e soffice` (or
+`-e libreoffice`, `-e office`) first on the command line, with a NOTE; without it Pandoc writes them from the document itself,
+which is the better file. `-e soffice` with another target (`.tex`, `.md`) lists what it writes.
 
 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
@@ -243,6 +295,8 @@ MISS  xelatex: could not build it (! LaTeX Error: File `stix2.sty' not found.)
 OK    typst: built a PDF in 1.1 s
 ```
 
+The last resorts are tried too (v3.29): an installed browser (`edge: built a PDF in 6.1 s`) and Calibre, which also writes a small
+ebook (`calibre:azw3: built an AZW3 ebook in 18.0 s`), so a missing Qt library shows here and not in the middle of a book.
 It takes a few seconds per engine (a minute or more if TeX has to fetch packages); without `--deep` nothing is built.
 
 ### Tab completion
@@ -314,6 +368,10 @@ OK    notes.md > notes.pdf
 - `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 core:tex` (also `cortex`, about 50 MB) is the other core: **Pandoc and Tectonic**, the self-contained
+  LaTeX engine (its release from GitHub, checked against the SHA-256 GitHub lists, into pdfmd's own tools folder). Tectonic
+  fetches the TeX files a document needs from the network the first time, then works from its cache. `core:typst`
+  (or `core`) is `--install full` below. `pan-tec` (see "Other command names") runs pdfmd on it.
 - `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
@@ -1030,9 +1088,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`, `inkmd` and `batchmd`
+### Other command names: `mdpdf`, `inkmd`, `batchmd` and `pan-tec`
 
-pdfmd also installs `mdpdf`, `inkmd` and `batchmd` commands that take those tools' own keys
+pdfmd also installs `mdpdf`, `inkmd`, `batchmd` and `pan-tec` commands that take those tools' own keys
 and do what they did, with pdfmd behind them:
 
 ```sh
@@ -1044,6 +1102,10 @@ batchmd ~/notes                              # every .md in the folder, as pdfmd
 batchmd -e inkmd                             # the current folder, with the built-in renderer
 ```
 
+`pan-tec` is the first version of pdfmd, a shell function around `pandoc "$@" --pdf-engine=tectonic --pdf-engine-opt=--chatter=minimal`
+(v3.29): `pan-tec test.md -o ex.pdf` is `pdfmd -e tectonic test.md -o ex.pdf --pdf-engine-opt=--chatter=minimal`, with everything else
+pdfmd does. Name another engine (`-e typst`) or a chatter level of your own and that is used instead.
+
 `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.
@@ -1262,6 +1324,12 @@ Water,18.015,1.20
   `---`, `:--`, `:-:`, `--:` 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.
+- **A spreadsheet** (v3.29) works as the file: `::: {.csv file="results.xlsx" sheet="Run 2"}` (`.xlsx`, `.xlsm`, `.xls`, `.ods`;
+  `sheet=` is a name or a number counted from 1, the first sheet when it is left out). The sheet is read by `openpyxl` (xlsx and
+  xlsm: the values the file stores, so a cell shown as `1.50` is `1.5`, a date is `2026-01-02`), else by `pandas`, else by
+  LibreOffice (the sheet by number); none of them is a `WARN` that says what to install (`pip install openpyxl`). The converted
+  CSV is kept in pdfmd's cache by the file's content, the attached source carries the spreadsheet itself, and
+  `--expand-tables` reads it too.
 - 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. A cut table keeps both ends: the first 7 rows, a row
@@ -1323,10 +1391,28 @@ 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.
+"body font-size 11pt -> fontsize=11pt" for each one it used, and names what it did not: tables, anything else).
+Only rules that say it plainly count: `@page`, `html`/`body`/`:root`, `a`, `code`/`pre`, `h1`-`h5`; the last one wins. A media
+query is read as a browser prints (v3.29): `print` and `all` apply, `screen` and the other media types do not, a comma is "or",
+`only` and `not` count, `(orientation: landscape)` is read against the sheet's own `@page` size, and a feature of the screen or of
+a width (`(min-width: 600px)`) is not for a printed page and is named. 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.
+
+Headings (v3.29): `h1`-`h5` with a `color`, `font-size` (`em`, `%`, `pt`, `px`: of the body's size), `font-family`,
+`font-weight` or `font-style` are set for LaTeX too, as titlesec's starred formats (the numbering and the spacing stay the
+class's; `h1` is `\section`, `h2` `\subsection` ... `h5` `\subparagraph`; `h6` has no LaTeX level). It is done only for the plain
+article class, and never over a document that formats its headings itself: a `titlesec`, `sectsty`, KOMA or memoir command, or a
+`\section` of its own, in the preamble, the `header-includes` or a metadata file, is named in a `CSS` note and nothing is added
+(and when `titlesec` is not installed, one LaTeX warning says so). A family needs XeLaTeX or LuaLaTeX.
+
+### A cover: `cover`
+
+`pdfmd-options: {cover: true}` puts the title block (title, subtitle, author, date) on a page of its own and starts the text
+on the next (v3.29): LaTeX's `titlepage` class option (for the article, report and book classes and KOMA's; another class is
+left alone), and a page break after the title block of an HTML-family PDF (WeasyPrint, a browser, Calibre) or an HTML page.
+`cover: picture.png` (relative to the document) puts that picture on the first page of such a PDF, before the title, and is the
+cover of an EPUB, so of the Kindle book Calibre makes from it (Pandoc's own `cover-image:` does the same for an EPUB). A
+Word, OpenDocument or Typst file says once that the key was not applied. Off by default: the title block stays on page 1.
 
 ### Code: wrapping and line numbers
 
@@ -1468,6 +1554,79 @@ It is off unless asked (the document, a metadata file, or `pdfmd --setup` under
 [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.
 
+**Callouts in every format** (v3.29, the first kind of *universal markup* after page breaks). GitHub's and Obsidian's
+`> [!NOTE]`, a fenced `::: note` and Quarto's `::: callout-tip` are a block quote or a div to Pandoc, and print as plain text.
+Ask for them and each becomes a box of the writer's own: LaTeX a `tcolorbox` (a plain indented quote when that package is not
+installed), Typst a tinted block, HTML, EPUB and the HTML engines' PDFs a `div.callout` with its style, every other writer
+(Word, OpenDocument, Markdown ...) a block quote with a bold title:
+
+```yaml
+pdfmd-options:
+  markup: callouts             # or: markup: true (every kind there is)
+```
+
+```markdown
+> [!warning] Mind the gap
+> The title is the rest of the first line, the body the lines after it.
+
+::: {.tip title="Another way"}
+A fenced div takes `note`, `tip`, `important`, `warning` or `caution` as its class, `title=` for the title.
+:::
+```
+
+The five kinds are GitHub's (`note`, `tip`, `important`, `warning`, `caution`); Obsidian's others map to them (`info`, `todo`,
+`example`, `abstract` to note; `success`, `check`, `hint` to tip; `question`, `help`, `faq` to important; `failure`, `danger`,
+`error`, `bug` to caution; `attention` to warning), and an unknown name is a note titled with it. A fold marker (`[!tip]-`) is
+dropped. Off unless asked (the document, a metadata file, or `pdfmd --setup` under *Universal markup*); `--markup [KIND ...]` and
+`--no-markup` decide for one run. The built-in renderer (no Pandoc) does not read it yet, and there is no Word shaded box yet.
+
+**A table of contents where you put it** (v3.29, `markup: toc`). `[TOC]`, `[[_TOC_]]` and `<!-- toc -->` alone in a paragraph, or
+a raw `\tableofcontents` for a writer that is not LaTeX, become the contents at that place: LaTeX's `\tableofcontents` (filled in
+one build, with the page numbers), Typst's `#outline()`, a Word TOC field (Word offers to update it when the file is opened) and,
+for every other writer (HTML, EPUB, Markdown, OpenDocument ...), a nested list of links to the headings down to level 3, with a
+bold "Contents" above it. `markup: [callouts, toc]` or `markup: true` for both; `--markup toc` for one run. A marker inside a
+sentence is text.
+
+**Centred text** (v3.29, `markup: center`). `<center>` ... `</center>` around blocks (the closing tag in its own paragraph),
+`<div align="center">`, `<div style="text-align: center">`, a fenced `::: center` and, for writers that are not LaTeX, a raw
+`\begin{center}` ... `\end{center}` all centre what they hold: LaTeX's `center` environment, Typst's `#align(center)[...]`, a
+`text-align` div in HTML, EPUB and the HTML engines' PDFs. Word and OpenDocument keep the text as it is and say so once (no
+centring for a block there yet). `markup: [callouts, toc, center]` or `true` for all; `--markup center` for one run.
+
+**Highlighted text** (v3.29, `markup: highlight`). `==marked text==` (across several words, with emphasis inside, over a line
+break) is highlighted: LaTeX with `soul`'s `\hl` in a pale yellow (plain text when `soul` is not installed), Typst with
+`#highlight[...]`, HTML, EPUB and `--to gfm` with `<mark>`; Pandoc's own Markdown output keeps `==...==`, and Word and OpenDocument
+keep the text and say once that it is not highlighted. A lone `==` or one inside code stays as written; a closing `==` followed by
+punctuation (`==end==.`) works. `markup: [callouts, toc, center, highlight]` or `true` for all; `--markup highlight` for one run.
+
+**Blocks kept on one page** (v3.29, `markup: keep`). A fenced `::: keep` (also `nobreak`, `keep-together`), a div with
+`style="break-inside: avoid"` and, for writers that are not LaTeX, a raw `\begin{samepage}` ... `\end{samepage}` hold what they
+contain on one page where it fits: LaTeX's `samepage` environment, Typst's `#block(breakable: false)[...]`, a `break-inside:
+avoid` div in HTML, EPUB and the HTML engines' PDFs. Word and OpenDocument keep the text and say once that it is not held.
+`--markup keep` for one run.
+
+**Landscape pages** (v3.29, `markup: landscape`). A fenced `::: landscape`, a div with `style="page: landscape"` and, for writers
+that are not LaTeX, a raw `\begin{landscape}` ... `\end{landscape}` put what they hold on pages turned sideways, the document
+going back to portrait after it: LaTeX with `pdflscape` (the page is rotated in the PDF; `lscape`, or no turning, when it is not
+installed), Typst with `#page(flipped: true)[...]`, WeasyPrint and the browsers with a named page (`@page landscape`: the browsers
+get the document's paper turned; WeasyPrint's is its own A4 unless your own `@page landscape` says otherwise). Calibre's PDF cannot
+name page types, and Word and OpenDocument have no sections made from here: they keep the text and say once that no landscape page
+was made. `--markup landscape` for one run.
+
+**Where the appendix starts** (v3.29, `markup: appendix`). A raw `\appendix`, `<!-- appendix -->` or a heading with the class
+`{.appendix}` marks the start: the sections after it are lettered (A, B, A.1) in LaTeX (`\appendix`) and Typst (a heading
+numbering of letters and a counter reset). It matters for a document that numbers its sections (`--number-sections`); without
+numbers Typst gets nothing and LaTeX's `\appendix` changes nothing visible. Other writers keep their own numbering and say once
+that the lettering is not made.
+
+**Showing the comments of the text** (v3.29, `show-comments`). An `<!-- HTML comment -->` is invisible in every output. With
+`pdfmd-options: {show-comments: true}` (or `--show-comments` for one run, `--no-show-comments` to switch it off; also a row in
+`pdfmd --setup`) each one is shown: a box labelled *Comment* in LaTeX, Typst, HTML, EPUB and the HTML engines' PDFs, a real Word
+comment in a `.docx` (anchored on the paragraph after it, so Word's review pane lists them), `[comment: ...]` in italics for one
+inside a paragraph. The Markdown family (`--to gfm`, `markdown`) keeps the comment as it is; OpenDocument and PowerPoint drop
+it, with a note once. pdfmd's own markers stay invisible (`<!-- pdfmd: ... -->`, `<!-- pagebreak -->`, `<!-- toc -->`,
+`<!-- appendix -->`), and so does an empty comment. It is off unless asked and is not one of the kinds `markup: true` turns on.
+
 **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
@@ -1725,6 +1884,17 @@ document or its metadata files say (the command line beats all of them);
 `translit:` is the romanization packs of the name lookup. `PDFMD_CONFIG=other.yaml`
 uses another file, `PDFMD_CONFIG=` (empty) none.
 
+**Settings for a folder** (v3.29): a `.pdfmd/config.yaml` in a document's folder, or in any folder above it, has the same
+`options:` for everything under it. The order, strongest first: the command line, the document's `pdfmd-options`, its metadata
+files, the folder settings (the nearest folder first, then the ones above it), your global `config.yaml`, pdfmd's own defaults.
+`inherit: false` in a folder's file stops the walk upward there. A folder cannot set what belongs to this computer (`translit`,
+`setup-ui`, `disabled`): they are ignored with a `WARN`. A mapping such as `stamp:` or `backup:` in a folder's file stays off
+until it says `enabled: true`, as in the global file. A build lists the folder files it used on its `FOUND` line
+(`--verbose`: `AUTO SETTINGS`). A folder's options cannot name code (a Lua filter or a preamble is read from the document's own
+front matter only), a `.pdfmd/config.yaml` owned by another user (a shared `/tmp`) is not read, and a path in it (`css: house.css`)
+is relative to the document, as everywhere, not to the folder file. Writing the file from `pdfmd --setup DIR`, and carrying it in
+an attached source, are not done yet.
+
 ```yaml
 translit: [greek, hangul]
 options: