From a2baaaa6393e7db69c169e1c6b89bc96d7fd1b64 Mon Sep 17 00:00:00 2001 From: Andy Kopra Date: Sun, 9 Aug 2026 16:14:26 +0200 Subject: [PATCH] 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) --- README.md | 2 +- doc/install/linux_source_install.md | 52 ++++++++++++++++++++++++++++ doc/install/macos_source_install.md | 53 ++++++++++++++++++++++++++++- 3 files changed, 105 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c22019c..335c00a 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ are regenerated on each release — patches cannot be merged directly. Report problems (or send patches) to the author; accepted changes are applied to the development tree and appear in a following snapshot. -This snapshot was assembled from development commit `97d4f244c737`. +This snapshot was assembled from development commit `d8ea0e973914`. ## License diff --git a/doc/install/linux_source_install.md b/doc/install/linux_source_install.md index 3701b7d..46c5ca4 100644 --- a/doc/install/linux_source_install.md +++ b/doc/install/linux_source_install.md @@ -195,6 +195,58 @@ ktext -s '@eval :haskell main = putStr "Hello from Haskell" @' -d ``` +## 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 (see *Environment variables* above) you already have it — +**in shells started after the installation**. In a shell that was already +running, source it again: + +```bash +source $KLAMMERTEXT_HOME/env/runtime.env +type mdpdf # mdpdf is a shell function +``` + +Two things it needs that the distribution does not install: + +```bash +# 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; install whichever you prefer. +sudo apt install chromium-browser +``` + +Then: + +```bash +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 your +shell profile — `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: + +```bash +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. + + ## Directory layout after build ``` diff --git a/doc/install/macos_source_install.md b/doc/install/macos_source_install.md index 62e8255..dfcec31 100644 --- a/doc/install/macos_source_install.md +++ b/doc/install/macos_source_install.md @@ -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: