diff options
Diffstat (limited to 'docs/typ/README')
| -rw-r--r-- | docs/typ/README | 43 |
1 files changed, 41 insertions, 2 deletions
diff --git a/docs/typ/README b/docs/typ/README index 522d99ff..9d3913c0 100644 --- a/docs/typ/README +++ b/docs/typ/README @@ -35,14 +35,16 @@ Build (from the repo root): The contract for content files ------------------------------ Start a content file with - #import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs + #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 it sits in a tag. + 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). @@ -68,12 +70,49 @@ new function instead. 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 |