summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/typ/builtins-gui.json1
-rw-r--r--docs/typ/builtins-tui.json1
-rw-r--r--docs/typ/reference.typ44
3 files changed, 46 insertions, 0 deletions
diff --git a/docs/typ/builtins-gui.json b/docs/typ/builtins-gui.json
index 6a5856a9..1fe1f0fb 100644
--- a/docs/typ/builtins-gui.json
+++ b/docs/typ/builtins-gui.json
@@ -1,4 +1,5 @@
[
+ {"name": "Addon", "leader": null, "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "Addons, the libraries that bring kinds of pane: `Addon load <path>`, `Addon unload <name>`, `Addon reload <name>`; bare, the kinds here."},
{"name": "Adopt", "leader": null, "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Take in the shells of a session that died holding them, each as a terminal pane here: the pardes daemon kept their terminals open."},
{"name": "Ascii", "leader": "SPC t a", "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "add the printable ASCII bitmaps to the matcher's glyph set"},
{"name": "Back", "leader": "SPC j o", "also": ["C-o"], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Ctrl-o: one step back into the history."},
diff --git a/docs/typ/builtins-tui.json b/docs/typ/builtins-tui.json
index 1a6a4023..647cdf1b 100644
--- a/docs/typ/builtins-tui.json
+++ b/docs/typ/builtins-tui.json
@@ -1,4 +1,5 @@
[
+ {"name": "Addon", "leader": null, "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "Addons, the libraries that bring kinds of pane: `Addon load <path>`, `Addon unload <name>`, `Addon reload <name>`; bare, the kinds here."},
{"name": "Adopt", "leader": null, "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Take in the shells of a session that died holding them, each as a terminal pane here: the pardes daemon kept their terminals open."},
{"name": "Ascii", "leader": "SPC t a", "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "add the printable ASCII bitmaps to the matcher's glyph set"},
{"name": "Back", "leader": "SPC j o", "also": ["C-o"], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Ctrl-o: one step back into the history."},
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 72d0b5ee..205b0400 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -34,6 +34,7 @@ ctl settings and session builtins @ro
commands every builtin, one a line @other-files
recent files opened lately: open|closed <path> @other-files
dumps the dumps the state file keeps: label date size panes @other-files
+addons the kinds of pane here, compiled in or an addon's @addons
layout a line per column, then active <serial> @columns-and-tags
tag the workspace tag @columns-and-tags
tagexec a word clicked in the workspace tag @columns-and-tags
@@ -970,6 +971,49 @@ at 200, ending in `…`. Control characters become spaces.
synthetic. Linux v9fs's truncation `mtime` hint is accepted and dropped.
- #file("/src/") with `-Dembed-sources=true`.
+= Addons <addons>
+
+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; a kind with only
+a head and `paint` is a valid one. Image is a kind compiled in, through the
+same records.
+
+- #word("Addon") `load <path>` (relative to the pane's directory) loads
+ one; `unload <name>` lets one go, refused while a pane of its kind is
+ open; `reload <name>` loads its library again, every pane of the kind
+ kept through its `dump` and `load` (one with none comes back fresh), and
+ a library that fails any check leaves the old one running; bare, it says
+ the kinds here. At start, every `*.so` of `$XDG_DATA_HOME/pardes/addons`,
+ then of `<prefix>/lib/pardes/addons`, is loaded.
+- #file("/addons"): a line a kind, `<kind> <version> <abi> static|loaded
+ <path>`, and a line an addon refused, with why: another ABI's major, no
+ `pardes_addon`, a word, leader path or extension already someone's (the
+ core's or another addon's: refused whole), words with no `ctl`.
+- Its words join #file("/commands") and Help, `(addon <name>)` after each.
+ Written to a pane of its kind they go to that kind; a word that opens its
+ kind opens a pane of it from anywhere, its argument the path; any other
+ 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
+ #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 <name> <version> is not loaded: Addon load <path>`;
+ the addon loaded, it opens there.
+- 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
+ crash inside one says `in addon <file>, <call>` in the crash record.
+- `pardes --addon-test <lib> <script>` runs a script of keys, clicks,
+ words and ticks against a pane of its kind and prints the pane after
+ each: an addon's test, compared with `diff`.
+
= The pardes command <command-line>
In a pane's shell (`PARDES_PID`, `PARDES_9P` and `PARDES_PANE` set),