diff options
| author | Gabriel Schneider <[email protected]> | 2026-10-30 17:35:06 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-10-30 17:35:06 -0300 |
| commit | 6d8da8721141284cf33bb901168b26135893eb86 (patch) | |
| tree | 791d63401d4e85fbca1d597a8ce0326e70efd545 /docs/typ/README | |
| parent | efd43a3a2cf03bb741366331158b368abf9ac583 (diff) | |
| parent | bf6810a8f9d6cc82050e7d9c0cfb06358301b574 (diff) | |
| download | pardes-6d8da8721141284cf33bb901168b26135893eb86.tar.gz pardes-6d8da8721141284cf33bb901168b26135893eb86.zip | |
Merge latest upstream into the macOS branch for Zig 0.17
Retain the macOS branch history and local Acme selection color while adopting upstream's current core and platform changes. Pin Zig and ZLS to 0.17.0, and fetch the existing zstbi compatibility commit through upstream after its original fork was removed.
Diffstat (limited to 'docs/typ/README')
| -rw-r--r-- | docs/typ/README | 126 |
1 files changed, 126 insertions, 0 deletions
diff --git a/docs/typ/README b/docs/typ/README new file mode 100644 index 00000000..9d3913c0 --- /dev/null +++ b/docs/typ/README @@ -0,0 +1,126 @@ +docs/typ: the Typst documentation corpus + + style.typ every semantic function, the palette and the topic + ids; the only place they are defined. Each function + looks at target(): it draws itself for paged output + and emits HTML elements under --features html. + cheatsheet.typ content: facts as markup and the calls below, no + layout. Later topics (guide, scripting, reference, + building) go beside it as their own content files. + cheatsheet-a4.typ output wrapper: the one-page A4 cheatsheet. + book.typ output wrapper: an A4 book, title page, contents, + every chapter, then the tutor (src/tutor.txt). + ../site/site.typ output wrapper: the website, a page per chapter plus + the landing page and the tutor, in one Typst bundle + run (see docs/site/README). + Wrappers hold layout only, never facts. + +Chapters: `chapters` in style.typ lists them in reading order (guide, setup, +cheatsheet, scripting, reference, themes, building), each with its content file, +or none while it is not written (the outputs show a placeholder). To add +a topic, write docs/typ/<id>.typ and set its `file`. Wrappers include it +with heading offset 1, so its = headings sit under the chapter title, +which is labelled ch-<id>. Labels on headings must be unique across all +the topics, since the book and the HTML hold them all. + +Build (from the repo root): + + typst compile --ignore-system-fonts docs/typ/cheatsheet-a4.typ + zig build cheatsheet -Dplatform=tty --prefix DIR # DIR/share/doc/pardes/cheatsheet.pdf + typst compile --root . --ignore-system-fonts docs/typ/book.typ + typst compile --root . --format bundle --features bundle,html docs/site/site.typ OUT + zig build site -Dplatform=tty --prefix DIR # DIR/share/doc/pardes/site/ +(--root . because book and HTML read the tutor from src/tutor.txt.) + +The contract for content files +------------------------------ +Start a content file with + #import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs, fstree, annotated, mode-box +(a content file does not import page setup; the same file goes into the +book, the HTML and, for the cheatsheet, the A4 page) +and use plain markup (= headings, - lists, `raw`, *strong*) plus these. +Never set page, fonts, colours or spacing in a content file; ask for a +new function instead. + + word(w) a builtin or tag word, drawn as a chip on the tag's + ground; a builtin links to its entry in the Builtins + chapter wherever that chapter is in the same output. + #word("Save") #word("Tty+bash") + key(k) one press, or a sequence of presses separated by + spaces, drawn as one pill (Ctrl + w, g › g). + Modifiers: Ctrl-, Alt-, Shift-. + #key("Ctrl-w") #key("g g") #key("SPC f c") + keys(..ks) alternatives listed together, each its own key. + #keys("h", "j", "k", "l") #keys("g d", "g r") + btn(b, shift:) a mouse button, B1 B2 (the wheel) or B3, drawn as a + mouse with that part filled; shift: true adds a ⇧. + #btn("B3") #btn("B1", shift: true) + chord(..bs) a chord: the first button held, each next clicked. + #chord("B2", "B1") #chord("B1", "B2", "B3") + tag(words, path:) + a whole default tagline; words must be a default tag. + #tag("Save Tty Collapse Del", path: "/home/me/notes.txt") + addr(a) a look address. #addr("file:12:5") + file(p) a 9P path. #file("pane/N/addr") + cmd(c) a shell line, as a block. #cmd("echo Save > $m/pane/$n/ctl") + doc(id, section:) + a pointer to a chapter, or a section of it by the label + on its heading. Ids: guide setup cheatsheet scripting + reference themes building (and the older tags fs + config keys detached, mapped in `topics`). A link in + the book and the HTML; on the A4 sheet, its name. + #doc("building", section: "listeners") + fstree(spec) a directory tree drawn as `tree` draws one, from a raw + block: two spaces of indent per level, the name (a + directory ends in /), two or more spaces, a one-line + description, an optional @label of the section that + documents it (a link where that section is in the + same output). reference.typ's tree is checked against + the files the session serves. + #fstree(``` + index a line per pane @rules + pane/ + new open: a new pane @panes + ```) + annotated(src, size, alt:, ..pins) + a screenshot with numbered pins, their labels as text + beside it. src from the repository root, size in + pixels, each pin ([label], x, y) in its pixels. + #annotated("/docs/site/media/themes/orchard.png", (640, 513), + alt: "a pardes window", ([the box], 8, 58)) + mode-box(mark, unsaved:) + a pane's box as it looks: " " normal, "^" insert, + "$" raw; unsaved: true fills it. + #mode-box("^") #mode-box(" ", unsaved: true) + theme-gallery() every theme as a picture, on the site's Themes page; + nothing on paper. + pairs(split:, ..cells) + a two-column table, a thing and its meaning, rows on + alternating tints; split: 2 sets it as two tables side + by side on paper. Cells alternate left, right. + #pairs(key("u"), [undo], keys("i", "a"), [insert]) + +Builtins +-------- +builtins-tty.json and builtins-gui.json are every builtin of the terminal +and the window build (name, leader, Help's other shortcuts, arg, scope, +setting, choices, doc), written by `zig build builtins-json -Dplatform=tty` +and `-Dplatform=gui` from the registry and the Help rows +(src/builtins_json.zig). style.typ merges them, marking each word "both", +"tty" or "gui". The doc steps refresh their build's file first, and each +build's unit-test fails when its file is stale. #word takes a name from +either file. builtins.typ draws it as the +glossary; `everyday`, `internals` and `builtin-groups` in style.typ say +in what order. + +The drift test +-------------- +The unit test "docs/typ names only words, keys and default tags that +exist" (src/config.zig) reads every .typ here and fails when a word(), +key(), keys() or tag() names a builtin, key binding or default tag that +pardes no longer has. Pass these functions string literals, so the test +can read them. + +Only embedded fonts (Libertinus Serif, DejaVu Sans Mono), so output is the +same on every machine. docs/typ/cheatsheet-a4.pdf is committed, as the +other docs PDFs are; re-render it when the content changes. |
