summaryrefslogtreecommitdiff
path: root/docs/typ
diff options
context:
space:
mode:
Diffstat (limited to 'docs/typ')
-rw-r--r--docs/typ/reference.typ27
1 files changed, 20 insertions, 7 deletions
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index f1b4df76..4d077f71 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -41,6 +41,7 @@ tagexec a word clicked in the workspace tag @co
plumb/ the plumber's: plumb(6) rules, and messages sent by them @plumber
rules the rules in force; a write adds rule sets, > replaces them @plumber
send write a message: six header lines, then its data @plumber
+ <port> a port the rules name: read, the messages sent to it @plumber
col/ the columns @columns-and-tags
<n>/ column <n>; rmdir closes it when empty @columns-and-tags
tag its tag
@@ -1038,7 +1039,8 @@ own: a file or directory opened, else the word searched for.
(`plumbing` in the configuration directory, beside `init`; saved, its
rules are in force), or without one `include basic`, pardes's own
(`src/plumbing`, below). A write adds rule sets, each
- read as its blank line comes, the rest at the close; `>` replaces them
+ read as its blank line comes, the rest at the close (refused there, it
+ is an `err` in the log alone; Plan 9's loses it); `>` replaces them
all. One open writes at a time (`file in use`). Kept in a dump.
- A rule set that does not read is refused at the write it is whole in,
`plumb/rules:<line>: <why>` in rules.c's words (`unknown verb isnt`,
@@ -1062,11 +1064,22 @@ own: a file or directory opened, else the word searched for.
`$file` and `$dir` are where), `set`, `add` and `delete` (`delete` of
an attribute not there fails, as plumber's code does), and the actions
`plumb to <port>`, `plumb start <words>` and `plumb client <words>`.
-- The ports pardes reads itself: `edit` (the data opened as a
- #word("Look") opens it, at `addr=` when given), `web` (the host's
- browser, a URL of at most 256 bytes) and each loaded kind by its name
- (`image`, `pdf`). A message to another port runs its rule set's
- `start` or `client`; to a port no rule names it goes nowhere.
+- Each port a rule has named this session has a file,
+ #file("/plumb/<port>") (0444), listed after `rules` and `send` in the
+ order the rules named them, never dropped. An open of it reads the
+ messages sent to that port from then on, one a read in the six lines'
+ form, a read that finds none held until one comes; every open gets its
+ own copy (`cat /plumb/edit` beside the editor sees every look it opens),
+ a message over its 64 KiB queue is not sent to it (an `err` in the log
+ says so). Messages sent before the open are not its.
+- The ports pardes reads itself, whatever else reads them: `edit` (the
+ data opened as a #word("Look") opens it, at `addr=` when given), `web`
+ (the host's browser, a URL of at most 256 bytes) and each loaded kind by
+ its name (`image`, `pdf`). A message to another port goes to its
+ readers; with none, its rule set's `start` runs (the message dropped),
+ or its `client`, the message held for the port's first reader (the
+ program it started, as a rule's `plumb client` means). To a port no
+ rule ever named it goes nowhere.
- `plumb start` of a builtin or a kind's word runs it in place, at the
looking pane (the pane with the keyboard for a #file("/plumb/send")
message); one that cannot do what it is asked declines, saying
@@ -1424,7 +1437,7 @@ with Client(sys.argv[1]) as c: # a socket path, or (ip, port)
[Edit], [every acme command but `B <cmd`, `D <cmd` and the `'` address; no `\1`-`\9`, and an alternation takes the first branch that matches, not the longest; a failing `< | >` command changes nothing, where acme puts in what it wrote (#doc("fs", section: "edit"))],
[`win`], [#word("Term") is a VT terminal pane; #file("pty/run") runs a line at its prompt and answers `exit N` and the output; with #word("Repl") bound, #word("Exec") on a source pane types the text into it],
[a directory window], [as acme's: a text pane named `dir/` (#file("index") kind `text`, #file("ctl") isdir 1), its entries in columns sorted bytewise, dotfiles shown, a directory's marked `/`; blanks pad the columns where acme's tabs do; a #word("Look") at an entry is from that directory, `Get` or a look at it again reads it again, and an edit is kept until then rather than lost to a resize; never dirty, #word("Save") refuses it],
- [the plumber], [no process: the plumber is the editor's own (#doc("reference", section: "plumber")): plumb(6)'s rules in #file("/plumb/rules") and the plumbing file #word("Plumb") opens, messages to #file("/plumb/send"); no submatches (`$1`-`$9`), no `click` from a #word("Look") (its own expansion stands), and no external port files yet],
+ [the plumber], [no process: the plumber is the editor's own (#doc("reference", section: "plumber")): plumb(6)'s rules in #file("/plumb/rules") and the plumbing file #word("Plumb") opens, messages to #file("/plumb/send"); no submatches (`$1`-`$9`), no `click` from a #word("Look") (its own expansion stands)],
[#key("Esc") selects what was typed], [#key("Esc") leaves insert mode, or goes back a pane (#doc("tags", section: "modes"))],
)