diff options
Diffstat (limited to 'docs/typ/README')
| -rw-r--r-- | docs/typ/README | 78 |
1 files changed, 58 insertions, 20 deletions
diff --git a/docs/typ/README b/docs/typ/README index 175a7abb..b86d7ef2 100644 --- a/docs/typ/README +++ b/docs/typ/README @@ -1,16 +1,15 @@ docs/typ: the Typst documentation corpus - style.typ the semantic elements (key btn chord word tag addr file - cmd doc), the palette and the topic ids; the only place - they are defined. Each element looks at target() and - draws itself for paged output or emits HTML elements. - cheatsheet.typ content: facts as markup and element calls, no layout. - Later topics (tags, fs, config, ...) go beside it as - their own content files, importing from style.typ. - cheatsheet-a4.typ - an output wrapper: page, type, headings, then #include - of the content. Future wrappers (book.typ, html.typ) - sit beside it; wrappers hold no facts. + 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 an output wrapper: page, type, headings, then + #include of the content. Future wrappers (book.typ, + html.typ) sit beside it; wrappers hold no facts. Build (from the repo root): @@ -18,12 +17,51 @@ Build (from the repo root): zig build cheatsheet -Dplatform=tty --prefix DIR # DIR/share/doc/pardes/cheatsheet.pdf typst compile --features html --format html docs/typ/cheatsheet.typ out.html -Write #word("Name") for a builtin, #key("SPC f c") or #key("Ctrl-w") for -keys, #tag("words", path: ...) for a default tagline, #doc("fs", section: -"edit") to point at a topic. The unit test "docs/typ names only words, -keys and default tags that exist" (src/config.zig) reads every .typ here -and fails when one names a builtin, key binding or default tag that pardes -no longer has. 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. +The contract for content files +------------------------------ +Start a content file with + #import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs +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 it sits in a tag. + #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 topic, by id from `topics` in style.typ + (tags fs config themes keys detached). + #doc("fs", section: "look-and-exec") + 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]) + +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. |