Update docs

11 files changed, 104 insertions, 65 deletions

diff --git a/doc/cha-api.5 b/doc/cha-api.5
index fd5dee6b..499df580 100644
--- a/doc/cha-api.5
+++ b/doc/cha-api.5
@@ -1,5 +1,5 @@
 '\" t
-.\" Automatically generated by Pandoc 3.3
+.\" Automatically generated by Pandoc 3.4
 .\"
 .TH "cha\-api" "5" "" "" "Chawan\[cq]s command API"
 .SH Chawan\[cq]s command API
diff --git a/doc/cha-config.5 b/doc/cha-config.5
index c9b797aa..237d28ad 100644
--- a/doc/cha-config.5
+++ b/doc/cha-config.5
@@ -1,5 +1,5 @@
 '\" t
-.\" Automatically generated by Pandoc 3.3
+.\" Automatically generated by Pandoc 3.4
 .\"
 .TH "cha\-config" "5" "" "" "Configuration of Chawan"
 .SH Configuration of Chawan
@@ -717,7 +717,9 @@ These are to be placed in the table array \f[CR][[omnirule]]\f[R].
 Examples:
 .IP
 .EX
-# Search using DuckDuckGo Lite. (Bound to C\-k by default.)
+# Search using DuckDuckGo Lite.
+# (This rule is included in the default config, although C\-k now invokes
+# Google search.)
 [[omnirule]]
 match = \[aq]\[ha]ddg:\[aq]
 substitute\-url = \[aq](x) => \[dq]https://lite.duckduckgo.com/lite/?kp=\-1&kd=\-1&q=\[dq] + encodeURIComponent(x.split(\[dq]:\[dq]).slice(1).join(\[dq]:\[dq]))\[aq]
@@ -837,8 +839,9 @@ rewrite\-url
 T}@T{
 JavaScript function
 T}@T{
-A JavaScript function Chawan will pass the URL to.
-If a new URL is returned, it will replace the old one.
+A JavaScript function Chawan will pass the site\[cq]s URL object to.
+If a new URL is returned, or the URL object is modified in any way,
+Chawan will transparently redirect the user to this new URL.
 T}@T{
 T}
 T{
@@ -1031,9 +1034,16 @@ Examples:
 .EX
 \f[I]# show change URL when Control, Escape and j are pressed\f[R]
 \[aq]C\-M\-j\[aq] = \[aq]cmd.pager.load\[aq]
+
 \f[I]# go to the first line of the page when g is pressed twice without a preceding\f[R]
 \f[I]# number, or to the line when a preceding number is given.\f[R]
 \[aq]gg\[aq] = \[aq]cmd.buffer.gotoLineOrStart\[aq]
+
+\f[I]# JS functions and expressions are accepted too. Following replaces the\f[R]
+\f[I]# default search engine with DuckDuckGo Lite.\f[R]
+\f[I]# (See api.md for a list of available functions, and a discussion on how\f[R]
+\f[I]# to add your own \[dq]namespaced\[dq] commands like above.)\f[R]
+\[aq]C\-k\[aq] = \[aq]() => pager.load(\[dq]ddg:\[dq])\[aq]
 .EE
 .SS Pager actions
 .PP
@@ -1082,8 +1092,7 @@ T}@T{
 \f[CR]cmd.pager.webSearch\f[R]
 T}@T{
 Open the URL bar with an arbitrary search engine.
-At the moment, this is DuckDuckGo Lite, but this may change in the
-future.
+At the moment, this is Google Search, but this may change in the future.
 T}@T{
 T}
 T{
diff --git a/doc/cha-image.5 b/doc/cha-image.5
index 4a97f055..43309d32 100644
--- a/doc/cha-image.5
+++ b/doc/cha-image.5
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 3.3
+.\" Automatically generated by Pandoc 3.4
 .\"
 .TH "cha\-image" "5" "" "" "Image support in Chawan"
 .SH Inline images
diff --git a/doc/cha-localcgi.5 b/doc/cha-localcgi.5
index 85129618..08f0e42b 100644
--- a/doc/cha-localcgi.5
+++ b/doc/cha-localcgi.5
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 3.3
+.\" Automatically generated by Pandoc 3.4
 .\"
 .TH "cha\-localcgi" "5" "" "" "Local CGI support in Chawan"
 .SH Local CGI support in Chawan
@@ -98,20 +98,21 @@ For example, an HTTP client would have to send
 \f[CR]Cha\-Control: ControlDone\f[R] before returning the retrieved
 headers.
 .PP
-List of public error codes:
+Following is a list of error codes and their string counterparts.
+CGI scripts may use either (but not both) in a ConnectionError header.
 .IP \[bu] 2
-\f[CR]1 internal error\f[R]: An internal error prevented the script from
+\f[CR]1 InternalError\f[R]: An internal error prevented the script from
 retrieving the requested resource.
 CGI scripts can also use this to signal that they have no information on
 what went wrong.
 .IP \[bu] 2
-\f[CR]2 invalid method\f[R]: The client requested data using a method
-not supported by this protocol.
+\f[CR]2 InvalidMethod\f[R]: The client requested data using a method not
+supported by this protocol.
 .IP \[bu] 2
-\f[CR]3 invalid URL\f[R]: The request URL could not be interpreted as a
+\f[CR]3 InvalidURL\f[R]: The request URL could not be interpreted as a
 valid URL for this format.
 .IP \[bu] 2
-\f[CR]4 file not found\f[R]: No file was found at the requested address,
+\f[CR]4 FileNotFound\f[R]: No file was found at the requested address,
 and thus the request is meaningless.
 Note: this should only be used by protocols that do not rely on a
 client\-server architecture, e.g.\ local file access, local databases,
@@ -119,14 +120,14 @@ or peer\-to\-peer file retrieval mechanisms.
 A server responding with \[lq]no file found\[rq] is NOT a connection
 error, and is better represented as a response with a 404 status code.
 .IP \[bu] 2
-\f[CR]5 failed to resolve host\f[R]: The hostname could not be resolved.
+\f[CR]5 FailedToResolveHost\f[R]: The hostname could not be resolved.
 .IP \[bu] 2
-\f[CR]6 failed to resolve proxy\f[R]: The proxy could not be resolved.
+\f[CR]6 FailedToResolveProxy\f[R]: The proxy could not be resolved.
 .IP \[bu] 2
-\f[CR]7 connection refused\f[R]: The server refused to establish a
+\f[CR]7 ConnectionRefused\f[R]: The server refused to establish a
 connection.
 .IP \[bu] 2
-\f[CR]8 proxy refused to connect\f[R]: The proxy refused to establish a
+\f[CR]8 ProxyRefusedToConnect\f[R]: The proxy refused to establish a
 connection.
 .SS Environment variables
 Chawan sets the following environment variables:
diff --git a/doc/cha-mailcap.5 b/doc/cha-mailcap.5
index 77fc7759..11abde02 100644
--- a/doc/cha-mailcap.5
+++ b/doc/cha-mailcap.5
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 3.3
+.\" Automatically generated by Pandoc 3.4
 .\"
 .TH "cha\-mailcap" "5" "" "" "Mailcap support in Chawan"
 .SH Mailcap
diff --git a/doc/cha-mime.types.5 b/doc/cha-mime.types.5
index d00d1803..3a228b56 100644
--- a/doc/cha-mime.types.5
+++ b/doc/cha-mime.types.5
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 3.3
+.\" Automatically generated by Pandoc 3.4
 .\"
 .TH "cha\-config" "5" "" "" "MIME type detection in Chawan"
 .SH mime.types
diff --git a/doc/cha-protocols.5 b/doc/cha-protocols.5
index de44247e..4cbb64ac 100644
--- a/doc/cha-protocols.5
+++ b/doc/cha-protocols.5
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 3.3
+.\" Automatically generated by Pandoc 3.4
 .\"
 .TH "cha\-protocols" "5" "" "" "Protocol support in Chawan"
 .SH Protocols
@@ -16,7 +16,7 @@ able to use passed userinfo data
 (\f[CR]https://username:password\[at]example.org\f[R]), and returns all
 headers and response body it receives from libcurl without exception.
 .PP
-It is possible to build these adapters using \c
+It is possible to build the HTTP adapter using \c
 .UR https://github.com/lwthiker/curl-impersonate
 curl\-impersonate
 .UE \c
@@ -34,22 +34,23 @@ very limited; in particular, it does not support HTTP headers (beyond
 some basic request headers), so e.g.\ cookies will not work.
 .SS FTP
 Chawan supports FTP through the \f[CR]adapter/protocol/ftp.nim\f[R]
-libcurl adapter.
+adapter.
+Only passive mode is supported.
+.PP
 For directory listings, it assumes UNIX output style, and will probably
 break horribly on receiving anything else.
 Otherwise, the directory listing view is identical to the file://
 directory listing.
-.PP
-SFTP \[lq]works\[rq] too, but YMMV.
+.SS SFTP
+The sftp adapter wraps libcurl.
+It works for me, but YMMV.
 Note that if an IdentityFile declaration is found in your ssh config,
 then it will prompt for the identity file password, but there is no way
 to tell whether it is really asking for that.
 Also, settings covered by the Match field are ignored.
-.PP
-In theory, FTPS should work too, but it is completely untested.
 .SS Gopher
 Gopher is supported through the \f[CR]adapter/protocol/gopher.nim\f[R]
-libcurl adapter.
+adapter.
 Gopher directories are passed as the \f[CR]text/gopher\f[R] type, and
 \f[CR]adapter/format/gopher.nim\f[R] takes care of converting this to
 HTML.
@@ -65,7 +66,7 @@ Chawan\[cq]s gemini adapter (in \f[CR]adapter/protocol/gmifetch.c\f[R])
 is a C program.
 It requires OpenSSL to work.
 .PP
-Currently, it still has some limitations:
+It still has some limitations:
 .IP \[bu] 2
 It does not support proxies yet.
 .IP \[bu] 2
diff --git a/doc/cha-troubleshooting.5 b/doc/cha-troubleshooting.5
index 8f205664..3748c99c 100644
--- a/doc/cha-troubleshooting.5
+++ b/doc/cha-troubleshooting.5
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 3.3
+.\" Automatically generated by Pandoc 3.4
 .\"
 .TH "cha\-troubleshooting" "5" "" "" "Troubleshooting Chawan"
 .SH Troubleshooting Chawan
@@ -6,30 +6,30 @@ This document lists common problems you may run into when using Chawan.
 .SS I can\[cq]t select/copy text with my mouse?
 Your options are:
 .IP \[bu] 2
-Use \f[CR]v\f[R] (and copy with \f[CR]y\f[R]).
-Drawback: requires keyboard
+Press \f[CR]v\f[R] (and copy with \f[CR]y\f[R]).
+You can then expand the selection with the mouse.
 .IP \[bu] 2
 Hold down the shift key while selecting.
-Drawback: can only select text currently on the screen
+Drawback: can only select text currently on the screen, and you
+can\[cq]t select tabs.
 .IP \[bu] 2
 Disable mouse support (\f[CR]input.use\-mouse = false\f[R] in
 config.toml).
-Drawback: see above (plus now you can\[cq]t use the mouse to move on the
-screen)
+Drawback: see above.
 .SS Why do I get strange/incorrect/ugly colors?
 Chawan\[cq]s display capabilities depend on what your terminal reports.
 In particular:
 .IP \[bu] 2
 if the \f[CR]$COLORTERM\f[R] variable is not set, then it may fall back
-to 8\-bit or ANSI colors
+to 8\-bit or ANSI colors.
+Make sure you export it as \f[CR]COLORTERM=truecolor\f[R].
 .IP \[bu] 2
 if it does not respond to querying the background color, then
-Chawan\[cq]s color contrast correction will likely malfunction
-.PP
-You can fix this manually by exporting \f[CR]COLORTERM=truecolor\f[R]
-and
+Chawan\[cq]s color contrast correction will likely malfunction.
+you can correct this using the
 \f[CR]display.default\-background\-color\f[R]/\f[CR]display.default\-foreground\-color\f[R]
 variables.
+.PP
 See config.md for details.
 .SS Can I view Markdown files using Chawan?
 Yes; Chawan now has a built\-in markdown converter.
@@ -43,7 +43,7 @@ Unfortunately, mandoc passes us the formatted document as a
 \f[I]file\f[R], which Chawan reasonably interprets as plain text without
 formatting.
 .PP
-At this point you have two options:
+At this point, you have two options:
 .IP \[bu] 2
 \f[CR]export PAGER=\[aq]cha \-T text/x\-ansi\[aq]\f[R] and see that man
 suddenly works as expected.
@@ -53,6 +53,18 @@ expected.
 .PP
 Ideally you should do both, to deal with cases like git help which
 shells out to man directly.
+.PP
+There is still one problem with this solution: some programs will try to
+call \f[CR]$PAGER\f[R] without shell expansion, breaking the
+\f[CR]\-T text/x\-ansi\f[R] trick.
+To fix this, put a script somewhere in your \f[CR]PATH\f[R]:
+.IP
+.EX
+\f[I]#!/bin/sh\f[R]
+exec cha \-T text/x\-ansi \[dq]$\[at]\[dq]
+.EE
+.PP
+and \f[CR]export PAGER=pcha\f[R].
 .SS Where are the keybindings?
 Please run \f[CR]cha about:chawan\f[R] for a list of default
 keybindings.
diff --git a/doc/cha-urimethodmap.5 b/doc/cha-urimethodmap.5
index 0cdb5c37..1347bcc0 100644
--- a/doc/cha-urimethodmap.5
+++ b/doc/cha-urimethodmap.5
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 3.3
+.\" Automatically generated by Pandoc 3.4
 .\"
 .TH "cha\-urimethodmap" "5" "" "" "URI method map support in Chawan"
 .SH URI method map support in Chawan
diff --git a/doc/protocols.md b/doc/protocols.md
index 7d23d22c..04f09c24 100644
--- a/doc/protocols.md
+++ b/doc/protocols.md
@@ -9,6 +9,10 @@ Gopher, Gemini, and Finger. Details on these protocols, and information
 on how users can add support to their preferred protocols is outlined in
 this document.
 
+In general, you can find network adapters in the `adapter/protocol` directory.
+For protocol-specific file formats (like gemtext or gopher directories) you will
+also find an appropriate HTML converter in `adapter/format`.
+
 <!-- MANOFF -->
 **Table of contents**
 
@@ -28,7 +32,7 @@ this document.
 ## HTTP
 
 HTTP/s support is based on libcurl; supported features largely depend on
-your libcurl version. The adapter is found at `adapter/protocol/http.nim`.
+your libcurl version.
 
 The libcurl HTTP adapter can take arbitrary headers and POST data, is able
 to use passed userinfo data (`https://username:password@example.org`), and
@@ -42,16 +46,14 @@ for curl-impersonate to work, you must set `network.default-headers = {}`
 in the Chawan config. (Otherwise, the libcurl adapter will happily override
 curl-impersonate headers, which is probably not what you want.)
 
-The `bonus/libfetch` directory contains an alternative HTTP client, which is
-based on FreeBSD libfetch. It is mostly a proof of concept, as FreeBSD
-libfetch HTTP support is very limited; in particular, it does not support
-HTTP headers (beyond some basic request headers), so e.g. cookies will
-not work.
+The `bonus` directory contains an alternative HTTP client based on FreeBSD
+libfetch. It is mostly a proof of concept, as FreeBSD libfetch HTTP support is
+very limited; in particular, it does not support arbitrary HTTP headers, so e.g.
+cookies will not work.
 
 ## FTP
 
-Chawan supports FTP through the `adapter/protocol/ftp.nim` adapter. Only
-passive mode is supported.
+Chawan supports FTP passive mode browsing and downloads.
 
 For directory listings, it assumes UNIX output style, and will probably
 break horribly on receiving anything else. Otherwise, the directory
@@ -59,11 +61,13 @@ listing view is identical to the file:// directory listing.
 
 ## SFTP
 
-The sftp adapter wraps libcurl. It works for me, but YMMV. Note that if
-an IdentityFile declaration is found in your ssh config, then it will
-prompt for the identity file password, but there is no way to tell
-whether it is really asking for that. Also, settings covered by the
-Match field are ignored.
+The sftp adapter (`adapter/protocol/sftp.nim`) wraps libcurl. It works for me,
+but YMMV.
+
+Note that if an IdentityFile declaration is found in your ssh config, then it
+will prompt for the identity file password, but there is no way to tell whether
+it is really asking for that (or just normal password auth). Also, settings
+covered by the Match field are ignored.
 
 ## Gopher
 
diff --git a/doc/troubleshooting.md b/doc/troubleshooting.md
index b94769a8..59104576 100644
--- a/doc/troubleshooting.md
+++ b/doc/troubleshooting.md
@@ -10,11 +10,12 @@ This document lists common problems you may run into when using Chawan.
 
 Your options are:
 
-* Use `v` (and copy with `y`). Drawback: requires keyboard
+* Press `v` (and copy with `y`). You can then expand the selection with the
+  mouse.
 * Hold down the shift key while selecting. Drawback: can only select text
-  currently on the screen
+  currently on the screen, and you can't select tabs.
 * Disable mouse support (`input.use-mouse = false` in config.toml). Drawback:
-  see above (plus now you can't use the mouse to move on the screen)
+  see above.
 
 ## Why do I get strange/incorrect/ugly colors?
 
@@ -22,13 +23,13 @@ Chawan's display capabilities depend on what your terminal reports. In
 particular:
 
 * if the `$COLORTERM` variable is not set, then it may fall back to 8-bit or
-  ANSI colors
+  ANSI colors. Make sure you export it as `COLORTERM=truecolor`.
 * if it does not respond to querying the background color, then Chawan's color
-  contrast correction will likely malfunction
+  contrast correction will likely malfunction. you can correct this using the
+  `display.default-background-color`/`display.default-foreground-color`
+  variables.
 
-You can fix this manually by exporting `COLORTERM=truecolor` and
-`display.default-background-color`/`display.default-foreground-color`
-variables. See [config.md](config.md#display) for details.
+See [config.md](config.md#display) for details.
 
 ## Can I view Markdown files using Chawan?
 
@@ -43,7 +44,7 @@ Chawan *can* parse if they are passed through standard input.
 Unfortunately, mandoc passes us the formatted document as a *file*, which Chawan
 reasonably interprets as plain text without formatting.
 
-At this point you have two options:
+At this point, you have two options:
 
 * `export PAGER='cha -T text/x-ansi'` and see that man suddenly works as
   expected.
@@ -52,6 +53,17 @@ At this point you have two options:
 Ideally you should do both, to deal with cases like git help which shells out to
 man directly.
 
+There is still one problem with this solution: some programs will try to call
+`$PAGER` without shell expansion, breaking the `-T text/x-ansi` trick. To fix
+this, put a script somewhere in your `PATH`:
+
+```sh
+#!/bin/sh
+exec cha -T text/x-ansi "$@"
+```
+
+and `export PAGER=pcha`.
+
 ## Where are the keybindings?
 
 Please run `cha about:chawan` for a list of default keybindings. Users familiar