Show, don't tell: the guide, the tutor, scripting, setup and the landing lead show an example first and cut the prose it makes redundant; the reference's 9P tree and REPLs name Look and Exec

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

1 files changed, 14 insertions, 15 deletions

diff --git a/docs/typ/setup.typ b/docs/typ/setup.typ
index c7644dbb..1c3a616b 100644
--- a/docs/typ/setup.typ
+++ b/docs/typ/setup.typ
@@ -61,17 +61,16 @@ fi
 
 = A pager <pager>
 
-`pardes -` reads its standard input into the directory's one `+Pager`
-pane, colours kept, and returns. With #word("Pager") `pardes` (the default) a
-terminal's shell gets `PAGER`, `GIT_PAGER` and `SYSTEMD_PAGER` set to it,
-and `SYSTEMD_PAGERSECURE=0`, each only where your environment does not set
-it. So `git log`, `journalctl` or `man` output arrives as a pane to search
-and click in, a diff drawn as one; command panes page through `cat`. `man`
-reads `MANPAGER` first, which pardes never sets. Any pager of your own wins;
-#word("Pager") `off` in the startup file keeps them all yours, for terminals started
-after it. git colours what it pages by default (`color.pager`); ask other
-programs for colour outright (`ls --color=always | pardes -`), and put
-#word("PagerColor") `off` in the init file for plain text.
+#cmd("ls --color=always | pardes -   # into the directory's +Pager, colours kept")
+
+With #word("Pager") `pardes` (the default) a terminal's shell gets
+`PAGER`, `GIT_PAGER` and `SYSTEMD_PAGER` set to it (and
+`SYSTEMD_PAGERSECURE=0`) wherever your environment leaves them unset, so
+`git log`, `journalctl` and `man` arrive as a pane, a diff drawn as one;
+command panes page through `cat`. `man` reads `MANPAGER` first, which
+pardes never sets. #word("Pager") `off` in the startup file leaves them all
+yours, for terminals started after it; #word("PagerColor") `off` makes the
+text plain.
 
 = yazi in a terminal pane <yazi>
 
@@ -105,9 +104,7 @@ script on that `PATH` is a word you can click.
 
 = Language servers <language-servers>
 
-pardes starts a language server for a file it knows, finding the program
-on `PATH`; `PARDES_LSP_<LANG>` names another, and an empty value turns it
-off.
+pardes starts a language server for a file it knows, from `PATH`:
 
 #pairs(
   [`.zig`], [`zls` (`PARDES_LSP_ZIG`)],
@@ -118,6 +115,8 @@ off.
   [`.py`], [`pyright-langserver --stdio` (`PARDES_LSP_PY`)],
 )
 
+#cmd("PARDES_LSP_ZIG=$HOME/src/zls/zig-out/bin/zls pardes   # another zls\nPARDES_LSP_PY= pardes                                  # none for .py")
+
 #word("Lspinfo") (#key("SPC l i")) says what is running.
 
 = Fonts and themes <fonts-and-themes>
@@ -125,7 +124,7 @@ off.
 The terminal build uses your terminal's font. The SDL window carries
 Adwaita Mono and finds others in `/usr/share/fonts`,
 `/usr/local/share/fonts`, `~/.local/share/fonts` and `~/.fonts`; #word("Font")
-`name:size` picks one. #word("Theme") `<name>` and #word("ThemeFile") are in the themes
+`Iosevka:16` picks one. #word("Theme") `<name>` and #word("ThemeFile") are in the themes
 chapter (#doc("themes")).
 
 = plan9port <plan9port>