The docs take round 31: one +Pager per directory and how pardes - cleans its text, SYSTEMD_PAGER, a paged diff drawn as one, event reads in pieces, sel, write-back origins, +PdfSections rows, a PDF body by lines, bare :N looks and quoted bad values

Co-Authored-By: Claude Opus 5.5 <[email protected]>

1 files changed, 33 insertions, 13 deletions

diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 3f895a8c..c27a6084 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -58,8 +58,9 @@ refused open or truncation (an OTRUNC open such as `> data` after a failed
 `addr`), create or remove answers its error alone, as do a write to
 #file("pane/new") (`permission denied`) and a write on a read-only fid
 (`bad use of fid`). Errors are words (Plan 9's where pardes has none of its
-own), never a C library string; a ctl refusal quotes the offending word
-alone (`wrong #args in control message "Newcol"`). Through 9ns the kernel sees an errno 9ns
+own), never a C library string; a bad setting value is quoted, the value
+itself (`bad value in control message; takes on, off "maybe"`); a ctl
+refusal quotes the offending word alone (`wrong #args in control message "Newcol"`). Through 9ns the kernel sees an errno 9ns
 reads from those words (cloud9's `9ns/src/nine.zig`, `enameToErrno`):
 `control message`, `invalid` or `bad ` is EINVAL (malformed input); `no such`, `not found` ENOENT; `in use` EBUSY; `no space` ENOSPC; `denied`
 EACCES; anything else, such as `no match for regexp`, `address out of range`, `Modified` or an `Edit` command pardes leaves out (`w is a sam command pardes's Edit leaves out`), EIO; no refusal reads as EOPNOTSUPP.
@@ -135,7 +136,7 @@ files.
 - `file:12` selects line 12, newline included; `file:12:5` puts the caret
   at line 12, byte column 5; `file:<addr>` takes any address (below),
   *evaluated from the file's dot*: `file:/re/` finds the next match after
-  the selection, `file:0/re/` the first. `:addr` addresses the pane itself.
+  the selection, `file:0/re/` the first. A bare `:N` or `:N:M` (or any `:addr`) addresses the pane looked from.
   `@p<serial>:<addr>` addresses a pane by serial, a terminal's logical
   lines too.
 - A leading `~` is the home directory (`$HOME`, else the passwd entry's;
@@ -150,6 +151,8 @@ files.
 - A whole line of a diff pane written to #file("look") is the look a
   #btn("B3") click on its first column makes. The line is matched in the
   pane from its cursor row on, wrapping, and the first match wins.
+- A `+PdfSections` row is `file.pdf:PAGE:SECTION`; a look at a section that
+  is not there, or not on that page, fails as a miss.
 - A plain word selects its next place after dot, wrapping (`LookWord list`
   on the root ctl lists every place in a `+Search` pane instead). In a
   terminal a word is always listed, rows spelled `@p3:12:5-9`.
@@ -296,7 +299,7 @@ word clicked in a tag does. The same lines go in the startup file
   [`Verbose`], [on: a builtin announces its name on the message row],
   [`MessageAnimation`], [on: messages ease in and dissolve],
   [`MessageLinger`, `MessageFall`, `MessageDissolve`], [800, 180, 150 milliseconds, at most 60000],
-  [`Pager pardes|off`], [`pardes`: what a terminal's commands page through, `pardes -`; `off` leaves `PAGER` and `GIT_PAGER` as the environment has them. It applies to terminals started after it],
+  [`Pager pardes|off`], [`pardes`: what a terminal's commands page through, `pardes -`; `off` leaves `PAGER`, `GIT_PAGER` and `SYSTEMD_PAGER` as the environment has them (#doc("fs", section: "pardes-stdin")). It applies to terminals started after it],
   [`Placement acme|pardes`], [`acme`: where new panes go (#doc("tags", section: "new-panes"))],
   [`BootShell keep|replace`], [`keep`; `replace` closes the untouched lone shell a dragged document lands beside],
   [`LookWord search|list`], [`search`: a looked-at word selects its next place, or lists all in `+Search`],
@@ -426,12 +429,14 @@ all. A terminal's body is its history as plain text in logical lines
 (wrapped rows joined), frozen per open; writing it sends input to the
 child as typed keys, never a paste: no bracketed-paste marks around it,
 even when the program asked for them, so a newline in it is Enter. A PDF's
-body is the text layer of the page shown, read-only: it is no text of the
+body is the text layer of the page shown, each line of the page's text a
+line of the body, read-only: it is no text of the
 pane's, so #file("addr"), #file("data"), #file("dot") and a `file:<addr>`
 look do not address it (a PDF's `:<n>` is its page); images and PDFs take
 no write (`this pane has no text`).
 
-*#file("sel")* reads the selected text; a write replaces it.
+*#file("sel")* reads the selected text; a write replaces it and leaves
+the written text selected, and one open's writes run on from the last.
 *#file("errors")* is write-only: text appended to the directory's
 `+Errors` pane (logged as `msg` records when no column has room).
 
@@ -581,7 +586,9 @@ one step: `echo 1 > mark` (a point now), `echo 0 > mark`, the writes,
 Holding #file("event") open takes the pane's look and execute clicks: they
 come to the reader as records instead of acting, as do lines written to
 the pane's own #file("look")/#file("exec") (or the root's while it has the
-keyboard). A record is acme's `<origin><action><q0> <q1> <flag> <n> <text>\n`; read `n` *bytes* of text, which may hold newlines. One open
+keyboard). A record is acme's `<origin><action><q0> <q1> <flag> <n> <text>\n`; read `n` *bytes* of text, which may hold newlines. Reads may be shorter
+than a record: a record arrives in pieces across reads, so a shell's
+`read` loop works. One open
 reads a pane's #file("event") at a time, as acme's is one window's: a
 second open for reading fails `file in use` (EBUSY) until the first is
 closed. A reader whose pane has closed reads EOF.
@@ -603,7 +610,9 @@ to; the whole record as read acts on its text (the only way for `0 0`). A
 chorded record with its two follow-ups, in one write or three, runs once
 with its argument. A record written back that runs a builtin which fails
 (a refused #word("Del")) fails the write, EIO with its `err`, as an
-#file("exec") write would. `I`, `D`, `i`, `d` are refused. A helper holding
+#file("exec") write would. `I`, `D`, `i`, `d` are refused; the origin must be `E`, `F`, `K` or `M`,
+and a number larger than a range can hold is refused `bad number`,
+EINVAL. A helper holding
 #file("event") that writes its own pane's #file("exec") gets its command
 back as a record: run it through #file("ctl") instead.
 
@@ -713,11 +722,22 @@ at 200, ending in `…`. Control characters become spaces.
 
 = pardes - <pardes-stdin>
 
-`pardes -` reads stdin to its end, strips terminal escapes (colour,
-hyperlinks, a man page's overstrike), and shows it in a `+Pager` pane:
-inside a pardes pane, a clean `<cwd>/+Pager` in the outer session,
-returning at once; outside one, a new editor whose first pane it is. Input
-past a file's size limit is cut, and the pane says so at its end.
+`pardes -` reads stdin to its end and shows it in the directory's one
+`+Pager` pane, made or emptied for it and left clean; the next paged text
+refills it. Terminal escapes go (colour, hyperlinks, a man page's
+overstrike), a carriage return keeps a progress line's last state, CRLF
+becomes LF, and NUL, BEL, SO and SI are dropped. Empty stdin shows
+nothing. Inside a pardes pane it returns at once; a text the session cannot
+take is printed to stderr with why, and the exit is 1. From a directory
+whose name holds a newline or control byte, the pane is the session
+directory's. Outside a pardes pane it starts a new editor whose first pane
+the text is.
+
+With `Pager pardes`, a terminal's shell gets `PAGER`, `GIT_PAGER` and
+`SYSTEMD_PAGER` set to this pardes plus ` -` (the path quoted only when it
+needs it), and `SYSTEMD_PAGERSECURE=0` (it has no shell escape), each only
+where your environment does not set it. `man` pages through `MANPAGER`
+first, then `PAGER`; your own `MANPAGER` wins.
 
 = Other ways in <other-clients>