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: