Document the mdpdf command in the source-install guides

The distribution shipped sks/tns/ and the mdpdf command in the previous
snapshot without either install guide mentioning them, so the only way to
discover the command was to read env/runtime.env.  Both source-install
guides now describe it: what it is for (Markdown that is not Klammertext,
rendered through a headless browser), that runtime.env defines it -- so a
shell started before the installation does not have it -- the two things the
distribution does not install (the renderer's virtual environment, created
by "md_to_pdf.py --setup", and a Chromium-based browser), the MDPDF_*
variables that change its defaults, and where the stylesheet is.

 (from dev d8ea0e973914)
This commit is contained in:
2026-08-09 16:14:26 +02:00
parent 4a4c7404cc
commit a2baaaa639
3 changed files with 105 additions and 2 deletions

View File

@@ -145,7 +145,58 @@ xelatex --version
ktext hello.kt -t pdf # writes hello.pdf
```
## 6. Updating
## 6. Optional: the `mdpdf` command (Markdown to PDF)
Klammertext ships a second, independent route in `sks/tns/`: `mdpdf` renders
a **Markdown** file to PDF through a headless browser, bypassing Klammertext
entirely. It is for a document that is not written in Klammertext — one you
have not converted yet, or one whose Markdown is not worth converting.
The command is a shell function that `env/runtime.env` defines, so if you
source that file (section 3) you already have it — **in shells started after
the installation**. In a shell that was already running, source it again:
```sh
source "$KLAMMERTEXT_HOME/env/runtime.env"
type mdpdf # mdpdf is a shell function
```
Two things it needs that the distribution does not install:
```sh
# 1. The Markdown renderer, in a virtual environment of its own. PEP 668
# forbids installing it into the system Python, so this is not optional
# and not a system package.
python3 "$KLAMMERTEXT_HOME/sks/tns/md_to_pdf.py" --setup
# 2. A Chromium-based browser -- Brave, Chrome or Chromium -- which is the
# renderer. Any one of them will do, and an .app in /Applications is
# found without being told where it is.
brew install --cask chromium
```
Then:
```sh
mdpdf notes.md # writes notes.pdf beside it
mdpdf notes # the .md may be left off
```
It supplies the fonts, the size matching and the code wrapping, and completes
on `*.md` at the TAB key. Each default is a variable you may set in
`~/.zprofile``MDPDF_SERIF`, `MDPDF_SANS`, `MDPDF_MONO`, `MDPDF_MATCH`,
`MDPDF_WRAP`, and `MDPDF_BROWSER` for a browser installed somewhere the
command does not look. Any option of the underlying `md_to_pdf.py` may also
be given on the command line, where it overrides the default:
```sh
mdpdf notes.md --paper letter --margin 0.75
```
The stylesheet it applies is `sks/tns/markdown.css`; copy it, edit the copy,
and pass `--css yourcopy.css` to render to your own taste.
## 7. Updating
To update an existing source installation to the latest version: