From 239e8186111c215bf3bca842216205056e4b00e1 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Fri, 6 Nov 2026 06:24:42 -0300 Subject: kinds #17, the docs: reference.typ's Addons section says PDFs are an addon (pdf.so, its jobs and lanes, ABI 2.1's additions), a kind's tag prefix, Look and search in a kind's pane, a dump's record; install.typ the second library; shared-libs.md what left the binaries; building.typ and the cheatsheet; the changelog one line Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge --- docs/typ/reference.typ | 48 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 33 insertions(+), 15 deletions(-) (limited to 'docs/typ/reference.typ') diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ index 7af819a1..44b3bed9 100644 --- a/docs/typ/reference.typ +++ b/docs/typ/reference.typ @@ -503,8 +503,9 @@ keyboard goes to its tag, #file("focus") reads empty, the log says only #file("tag") files (#file("/tag"), #file("/col//tag"), #file("/pane//tag")) read the whole tag, with no newline after it. A -pane's starts with its computed path (an image's with its mode words, a -PDF's with its page), then the editable text. `>` replaces the editable +pane's starts with its computed path, then the editable text. A kind's +pane's starts with what its kind says (an image's `img`, a PDF's page +`[1/12]`), the core's art words when it shows a picture, then its path. `>` replaces the editable text (the default words too: `echo Make > tag` leaves only `Make`) and drops the one newline that ends it; `>>` appends, so `printf ' Make' >> tag` (the blank matters; `echo` would start a second @@ -977,14 +978,20 @@ An addon is a shared library that brings one kind of pane: a picture, a game, a plot. It is written against one header, `src/kinds/pardes_addon.h`, in C or anything that speaks C, and links nothing of pardes: the records are the header's, and what pardes does for it (an allocation from the -pane's arena, a job off the loop, a Look, a message, a new text pane) it is -handed at load. `addons/fake/fake.c` uses every function and -`addons/snake/snake.c` is a game in it; a kind with only a head and `paint` -is a valid one. Pictures are an addon too, `addons/image/image.c` (PNG, -JPEG, GIF, BMP, PPM, PGM and TGA through stb_image, at most 1280 pixels a -side), which the build installs as `/lib/pardes/addons/image.so`; -without it an image file opens as text. The header is ABI 2: an addon -built against another major is refused. +pane's arena, memory that outlives a call, a job off the loop, a Look or an +Exec, a message, a new text pane, its selection) it is handed at load. +`addons/fake/fake.c` uses every function and `addons/snake/snake.c` is a +game in it; a kind with only a head and `paint` is a valid one. Pictures +are an addon too, `addons/image/image.c` (PNG, JPEG, GIF, BMP, PPM, PGM and +TGA through stb_image, at most 1280 pixels a side), which the build +installs as `/lib/pardes/addons/image.so`, and so are PDFs, +`addons/pdf/pdf.c` over MuPDF (its pages rendered on jobs, two at once), +installed as `/lib/pardes/addons/pdf.so` (none with +`-Dmupdf=false`); without them an image file and a PDF open as text. The +header is ABI 2.1: an addon built against another major is refused, and +one of 2.0 runs as it did (2.1 added at the ends of its records: `heap`, +`view`, `exec` and `select` in its `pa_api`, the rail's thumb in +`pa_paint`, its own `search`). - `tick(state, now, flags)` returns the absolute time of its next step (0: none) on a monotonic clock. It is called when that time comes and @@ -1025,13 +1032,24 @@ built against another major is refused. elsewhere is refused. A Look of a file whose extension an addon claims opens a pane of its kind. - A pane of an addon's kind takes every key but #key("Esc") when its kind - takes keys, as a raw terminal does, and its clicks when it takes the - mouse. Its #file("body") is the kind's text, if it has any; its + takes keys, as a raw terminal does (#key("Esc") too, first, for a kind + of 2.1: not taken, it leaves), and its clicks when it takes the mouse, + a press's drag and release wherever they go, and a motion off its body + when the pointer leaves it. `tick` is called again when its view (its + window, a cell's pixels, the theme) changes. A `/` in it asks its kind's + `search`, a `+Search` of its rows; a Look of `file:` (`:` + in it) is its kind's `address`, a miss said `` and what the kind + said (`has no page 99`), one from a list its kind made (`text`) handed + with the list's name first (`+PdfSections 3:2`). Its #file("body") is the kind's text, if it has any; its #file("ctl") read ends with the kind's own fields. - A dump keeps each such pane: its kind, version, path and place, and the - kind's own record. Restored without its addon, the pane waits in its - place saying `addon is not loaded: Addon load `; - the addon loaded, it opens there. + kind's own record (a PDF's: its file's bytes, its fit, tint and page). + Restored without its addon, the pane waits in its place saying `addon + is not loaded: Addon load `; the addon loaded, it + opens there. One with no record opens from its file, at its place, its + words given again; a PDF pane of a dump made before the PDF addon comes + back so. A pane whose file changes on disk opens again from it, its + record kept for its `load` (a PDF stays on its page). - An addon runs in pardes's process. A load is marked on disk while it runs; a start that finds the mark of one that never finished skips that library, listed so, until #word("Addon") `load` asks for it again. A -- cgit v1.3