The docs describe the pager that landed: pardes - and its +Pager pane, a terminal's PAGER, command panes' cat, Pager pardes|off, and pty/run no longer waiting in one

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

4 files changed, 30 insertions, 17 deletions

diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ
index 55f11a80..6eeba822 100644
--- a/docs/typ/guide.typ
+++ b/docs/typ/guide.typ
@@ -184,6 +184,10 @@ A terminal is a pane like any other.
 - #word("Save") asks for a path on the pane's notice band and writes the
   terminal's scrollback there as text; `Save path` writes it at once.
 - #word("Filter") maps the program's colours through the theme.
+- A paging command in a terminal (`git log`, `man`) opens its text in a
+  `+Pager` pane: a terminal's `PAGER` and `GIT_PAGER` are `pardes -` unless
+  your environment sets them. `Pager off` keeps your own pager, for
+  terminals started after it.
 - In raw mode Ctrl-V types what you yanked into the program (with nothing
   yanked, the program gets the key), and Ctrl-Shift-V the desktop
   clipboard.
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 28f0c756..08fb1d83 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -296,6 +296,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],
   [`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`],
@@ -642,7 +643,8 @@ Terminal panes also have #file("pty/"):
   open: #cmd("exec 3<>$m/pane/$n/pty/run; echo make >&3; cat <&3; exec 3<&-")
   The answer's first line is the header: `exit N` then the command's output
   (as the screen showed it: no colour, tabs expanded to blanks, `\r`
-  progress collapsed, trailing blanks dropped; the last 64 KiB, `exit N cut M` when M bytes were left
+  progress collapsed, trailing blanks dropped; a paging command's text
+  goes to a `+Pager` pane through the terminal's `pardes -` pager; the last 64 KiB, `exit N cut M` when M bytes were left
   out, bare `cut` when the start scrolled away or was cleared). Or: `busy: <program> is running` (bare `busy` when text is typed at the prompt),
   `exit ?` (no status reported, not a success), `error not run` (the shell
   refused the line, e.g. a fish syntax error), `error shell gone`, `error no prompt marks`, and on a command pane `error a command runs here, not a shell` (`error command done; not a shell` once it ended). A line written
@@ -708,6 +710,14 @@ at 200, ending in `…`. Control characters become spaces.
   `-Dembed-sources=true`; `EffectCode <effect>` lists an effect's files
   under `/virtual`.
 
+= 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.
+
 = Other ways in <other-clients>
 
 The scripting chapter's rule (a mount, else plan9port's `9p`) covers most
diff --git a/docs/typ/scripting.typ b/docs/typ/scripting.typ
index 8b5831b8..d3e42573 100644
--- a/docs/typ/scripting.typ
+++ b/docs/typ/scripting.typ
@@ -39,9 +39,12 @@ and the Python client in the source tree.
 A command run from a pane (#btn("B2") on a line in its tag or text) also
 gets `$winid`, the serial of that pane, as acme's commands do; it is unset
 for one run from a column's or the workspace's tag, and `PARDES_PANE`
-stays the command pane's own. Every pane's child, a terminal's shell or a
-command, gets `PAGER=cat` and `GIT_PAGER=cat` unless your environment sets
-them, so nothing waits in a pager.
+stays the command pane's own.
+
+A paging command run through #file("pty/run") does not hang: the
+terminal's pager is `pardes -`, which puts the text in a `+Pager` pane and
+returns. A command pane pages through `cat`; its output is a pane already.
+Both hold only where your environment names no pager.
 
 = Recipes
 
@@ -102,10 +105,6 @@ pardes the editor of every program run there.
   the bad one fails. Send a block as one write (`cat block > $p/ctl`), and
   end every write whose result matters with a newline.
 - plan9port's `9p write` opens with OTRUNC: `echo x | 9p write pane/3/body` replaces the whole body. Append with `>>` through a mount.
-- #file("pty/run") runs in the terminal's own shell, so a command that
-  pages waits in the pager when your environment names one (pardes sets
-  `PAGER` and `GIT_PAGER` to `cat` only when it does not): run
-  `git --no-pager ...` or `PAGER=cat ...`.
 - `tail -f log` never sees anything new: write `follow` on the open you
   read. Through a FUSE mount bash's `read -t` cannot time out: wrap the
   loop in `timeout`.
diff --git a/docs/typ/setup.typ b/docs/typ/setup.typ
index 8cf8b091..4769eb49 100644
--- a/docs/typ/setup.typ
+++ b/docs/typ/setup.typ
@@ -75,15 +75,15 @@ command line with Ctrl-O in fish instead, add `bind ctrl-o edit_command_buffer`
 
 = A pager <pager>
 
-// PENDING: written to the 9P agent's pager design, which is not on main
-// yet; check every line against its change when it lands.
-`pardes -` reads its standard input into a `+Pager` pane. Terminal panes
-get `PAGER='pardes -'` and `GIT_PAGER='pardes -'` by themselves, unless
-your environment sets them, so `git log` or `man` output arrives as a pane
-to search and click in; command panes get `cat`. `Pager off` (on the root
-ctl, or a line in the startup file) turns it off, `Pager pardes` back on.
-To keep your own pager in pardes's terminals, set `PAGER` in your
-environment; to use pardes's outside them, set it to `pardes -` yourself.
+`pardes -` reads its standard input into a `+Pager` pane, escapes
+stripped. Terminals get `PAGER` and `GIT_PAGER` set to it (this pardes's
+own path, then `-`) by themselves unless your environment sets them, so
+`git log` or `man` output arrives as a pane to search and click in, and
+the terminal is back at once; command panes page through `cat`. To keep
+your own pager, either set `PAGER` in your environment, or put `Pager off`
+in the startup file (or write it to the root ctl); it applies to terminals
+started after it. Outside pardes, `PAGER='pardes -'` opens a new editor on
+the text.
 
 = yazi in a terminal pane <yazi>