diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/typ/README | 21 | ||||
| -rw-r--r-- | docs/typ/book.typ | 45 | ||||
| -rw-r--r-- | docs/typ/html.typ | 23 | ||||
| -rw-r--r-- | docs/typ/style.typ | 15 |
4 files changed, 100 insertions, 4 deletions
diff --git a/docs/typ/README b/docs/typ/README index b86d7ef2..f1eff604 100644 --- a/docs/typ/README +++ b/docs/typ/README @@ -7,20 +7,33 @@ docs/typ: the Typst documentation corpus 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. + 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). + html.typ output wrapper: one HTML page, every chapter under + an anchor named by its id, then the tutor. + Wrappers hold layout only, never facts. + +Chapters: `chapters` in style.typ lists them in reading order (guide, +cheatsheet, scripting, reference, 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. 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 --features html --format html docs/typ/cheatsheet.typ out.html + typst compile --root . --ignore-system-fonts docs/typ/book.typ + typst compile --root . --features html --format html docs/typ/html.typ pardes.html +(--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 +(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. diff --git a/docs/typ/book.typ b/docs/typ/book.typ new file mode 100644 index 00000000..26191fa7 --- /dev/null +++ b/docs/typ/book.typ @@ -0,0 +1,45 @@ +// The book: every topic in reading order, then the tutor. Facts live in the +// content files named by `chapters` in style.typ; this is layout only. +// typst compile --root . --ignore-system-fonts docs/typ/book.typ +// (--root . because the tutor is read from src/tutor.txt.) +#import "style.typ": palette, mono, chapters, tutor-path + +#set document(title: "pardes") +#set page(paper: "a4", fill: palette.paper, margin: (x: 22mm, y: 24mm)) +#set text(font: "Libertinus Serif", size: 10.5pt, fill: palette.ink, lang: "en") +#set par(justify: true, leading: 0.6em) +#show raw: set text(font: mono, size: 0.9em) +#show heading: set text(fill: palette.tag-name) +#show heading.where(level: 1): it => { + pagebreak(weak: true) + v(18mm) + text(size: 22pt, weight: "bold", it.body) + v(8mm) +} + +// title page +#page(numbering: none, { + v(1fr) + text(size: 34pt, weight: "bold", fill: palette.tag-name)[pardes] + v(4mm) + text(size: 13pt, style: "italic", fill: palette.tag-fg)[acme's tags and three buttons, helix's keys, terminals as panes, the editor as a 9P filesystem] + v(2fr) +}) + +#page(numbering: none, outline(depth: 2)) + +#set page(numbering: "1") +#counter(page).update(1) + +#for ch in chapters { + heading(level: 1, ch.title) + if ch.file == none { + text(style: "italic", fill: palette.tag-fg)[This chapter is not written yet.] + } else { + set heading(offset: 1) + include ch.file + } +} + += The tutor +#text(size: 8pt, raw(read(tutor-path), block: true)) diff --git a/docs/typ/html.typ b/docs/typ/html.typ new file mode 100644 index 00000000..2b7277e6 --- /dev/null +++ b/docs/typ/html.typ @@ -0,0 +1,23 @@ +// The HTML documentation: one page holding every topic in reading order, +// each under an anchor named by its id, then the tutor. +// typst compile --root . --features html --format html docs/typ/html.typ pardes.html +// One page because Typst 0.15's HTML export writes one document per run. +#import "style.typ": chapters, tutor-path + +#set document(title: "pardes") + +#html.elem("nav", { + for ch in chapters [- #link(label(ch.id), ch.title)] + [- #link(<tutor>)[The tutor]] +}) + +#for ch in chapters [ + #heading(level: 1, ch.title) #label(ch.id) + #if ch.file == none [_This chapter is not written yet._] else { + set heading(offset: 1) + include ch.file + } +] + += The tutor <tutor> +#raw(read(tutor-path), block: true) diff --git a/docs/typ/style.typ b/docs/typ/style.typ index 64d96064..467577cc 100644 --- a/docs/typ/style.typ +++ b/docs/typ/style.typ @@ -33,6 +33,21 @@ detached: "docs/detached.md", ) +/// The book's and the HTML's reading order. `file` is the content file +/// in docs/typ, or none while the topic is not written yet (the outputs +/// then show a placeholder). Wrappers include each with heading offset 1, +/// so a file's `=` headings sit under its chapter title. +#let chapters = ( + (id: "guide", title: "Guide", file: none), + (id: "cheatsheet", title: "Cheatsheet", file: "cheatsheet.typ"), + (id: "scripting", title: "Scripting", file: none), + (id: "reference", title: "Reference", file: none), + (id: "building", title: "Building", file: none), +) + +/// The tutor, shown as it is in the editor (`Tutor`), from the repo root. +#let tutor-path = "/src/tutor.txt" + #let html-out() = target() == "html" #let span(class, body) = html.elem("span", attrs: (class: class), body) #let m(s, fill: palette.ink) = text(font: mono, size: 0.92em, fill: fill, s) |