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:
@@ -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:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user