Rewrite much of the options section of the manual

1 files changed, 226 insertions, 156 deletions

diff --git a/catgirl.1 b/catgirl.1
index 16fa38b..f4d5d65 100644
--- a/catgirl.1
+++ b/catgirl.1
@@ -1,4 +1,4 @@
-.Dd October 11, 2023
+.Dd May 22, 2024
 .Dt CATGIRL 1
 .Os
 .
@@ -46,9 +46,9 @@
 The
 .Nm
 IRC client
-provides a curses interface
-for TLS-only
-Internet Relay Chat.
+provides a curses interface for
+Internet Relay Chat
+over TLS.
 The only required option is
 .Fl h ,
 the host name to connect to.
@@ -62,7 +62,8 @@ in
 to view the list of
 .Sx COMMANDS
 and
-.Sx KEY BINDINGS .
+.Sx KEY BINDINGS
+in this manual.
 .
 .Pp
 Options can be loaded from files
@@ -78,50 +79,65 @@ unless the path starts with
 .Ql \&./
 or
 .Ql \&../ .
-Files and flags listed later
-on the command line
-take precedence over
-those listed earlier.
+For example,
+a configuration file at
+.Pa ~/.config/catgirl/tilde
+can be loaded by running
+.Ql catgirl tilde .
 .
 .Pp
 Each option is placed on a line,
 and lines beginning with
 .Ql #
 are ignored.
+An optional
+.Ql =
+may appear
+between an option and its value.
 The options are listed below
 following their corresponding flags.
+Flags and options in files are processed
+in the order they appear on the command line,
+so later values override earlier values.
 .
 .Bl -tag -width Ds
-.It Fl C Ar util | Cm copy No = Ar util
-Set the utility used by
-.Ic /copy .
+.It Fl C Ar util | Cm copy Ar util
+Set the utility used by the
+.Ic /copy 
+command.
 Subsequent
 .Cm copy
-options append arguments to
-.Ar util .
-The URL to copy is provided to
-.Ar util
-on standard input.
+options add arguments
+to the utility.
+The URL to copy is provided
+to the utility on standard input.
 The default is the first available of
 .Xr pbcopy 1 ,
 .Xr wl-copy 1 ,
-.Xr xclip 1 ,
+.Xr xclip 1
+or
 .Xr xsel 1 .
 .
-.It Fl H Ar seed,bound | Cm hash No = Ar seed,bound
-Set the initial seed
-of the nick and channel
-color hash function
-and the maximum IRC color value
-produced by the function.
-The default is 0,75.
-To use only colors from
-the 16-color terminal set,
+.It Fl H Ar seed,bound | Cm hash Ar seed,bound
+Set the seed for choosing
+nick and channel colours
+and the maximum IRC colour value
+that will be chosen.
+Changing the seed
+will randomize the chosen colours,
+in case you don't like the ones
+chosen for yourself or your crush.
+.Pp
+The default is 0,75,
+which uses colours
+in the 256-colour terminal set.
+To use only colours
+from the 16-colour terminal set,
 use 0,15.
-To disable nick and channel colors,
+To disable nick and channel colours,
 use 0,0.
 .
-.It Fl I Ar pattern | Cm highlight No = Ar pattern
+.It Fl I Ar pattern | Cm highlight Ar pattern
 Add a case-insensitive message highlight pattern,
 which may contain
 .Ql * ,
@@ -132,44 +148,51 @@ wildcards as in
 .Xr glob 7 .
 The format of the pattern is as follows:
 .Bd -ragged -offset indent
+.\" FIXME: there's really no reason !user@host should be required
 .Ar nick Ns Op Ar !user@host Op Ar command Op Ar channel Op Ar message
 .Ed
 .Pp
 The commands which can be matched are:
-.Sy INVITE ,
-.Sy JOIN ,
-.Sy NICK ,
-.Sy NOTICE ,
-.Sy PART ,
-.Sy PRIVMSG ,
-.Sy QUIT ,
-.Sy SETNAME .
+.Sy invite ,
+.Sy join ,
+.Sy nick ,
+.Sy notice ,
+.Sy part ,
+.Sy privmsg ,
+.Sy quit ,
+.Sy setname .
+.Pp
+For example,
+to highlight whenever your crush
+joins your favourite channel:
+.Pp
+.Dl highlight crush!*@* join #channel
 .
-.It Fl N Ar util | Cm notify No = Ar util
+.It Fl N Ar util | Cm notify Ar util
 Send notifications using a utility.
 Subsequent
 .Cm notify
-options append arguments to
-.Ar util .
+options add arguments
+to the utility.
 The window name and message
-are provided to
-.Ar util
+are provided to the utility
 as two additional arguments,
 appropriate for
 .Xr notify-send 1 .
 .
-.It Fl O Ar util | Cm open No = Ar util
-Set the utility used by
-.Ic /open .
+.It Fl O Ar util | Cm open Ar util
+Set the utility used by the
+.Ic /open
+command.
 Subsequent
 .Cm open
-options append arguments to
-.Ar util .
-The URL to open is provided to
-.Ar util
-as an argument.
+options add arguments
+to the utility.
+The URL to open is provided
+to the utility as an additional argument.
 The default is the first available of
-.Xr open 1 ,
+.Xr open 1
+or
 .Xr xdg-open 1 .
 .
 .It Fl R | Cm restrict
@@ -185,58 +208,75 @@ option,
 and viewing this manual with
 .Ic /help .
 .
-.It Fl S Ar host | Cm bind No = Ar host
+.It Fl S Ar host | Cm bind Ar host
 Bind to source address
 .Ar host
 when connecting to the server.
-To connect from any address
-over IPv4 only,
+To connect from any IPv4 address,
 use 0.0.0.0.
-To connect from any address
-over IPv6 only,
+To connect from any IPv6 address,
 use ::.
 .
-.It Fl T Ns Oo Ar format Oc | Cm timestamp Op = Ar format
-Show timestamps by default,
-in the specified
-.Xr strftime 3
-.Ar format .
-The format string may contain
-raw IRC formatting codes.
-The default format is
-.Qq \&%X .
+.It Fl T Ns Oo Ar format Oc | Cm timestamp Op Ar format
+Show timestamps by default.
+The optional
+.Ar format
+string is interpreted by
+.Xr strftime 3 .
+The string may contain
+raw IRC formatting codes,
+if you can figure out
+how to enter them.
 .
-.It Fl a Ar user : Ns Ar pass | Cm sasl-plain No = Ar user : Ns Ar pass
-Authenticate as
-.Ar user
-with
-.Ar pass
-using SASL PLAIN.
+.It Fl a Ar user : Ns Ar pass | Cm sasl-plain Ar user : Ns Ar pass
+Authenticate with NickServ
+during connection using SASL PLAIN.
+.Nm
+will disconnect
+if authentication fails.
 Leave
 .Ar pass
-blank to prompt for the password.
+blank to prompt for the password when
+.Nm
+starts.
 .
-.It Fl c Ar path | Cm cert No = Ar path
-Load the TLS client certificate from
-.Ar path .
-The
-.Ar path
-is searched for in the same manner
-as configuration files.
-If the private key is in a separate file,
-it is loaded with
-.Cm priv .
-With
-.Cm sasl-external ,
-authenticate using SASL EXTERNAL.
-Certificates can be generated with
-.Fl g .
+.It Fl c Ar path | Cm cert Ar path
+Connect using a TLS client certificate
+loaded from
+.Ar path ,
+which is searched for
+in the same manner as configuration files.
+If the private key
+is in a separate file,
+additionally specify it with the
+.Cm priv
+option.
+.Pp
+To use this certificate
+to authenticate to NickServ
+using CertFP,
+use the
+.Cm sasl-external
+option.
+See
+.Sx Configuring CertFP .
+.Pp
+Client certificates
+can be generated with the
+.Fl g
+flag.
 .
 .It Fl e | Cm sasl-external
-Authenticate using SASL EXTERNAL,
-also known as CertFP.
-The TLS client certificate is loaded with
-.Cm cert .
+Authenticate to NickServ
+during connection using CertFP
+via SASL EXTERNAL.
+.Nm
+will disconnect
+if authentication fails.
+The client certificate
+must be specified with the
+.Cm cert
+option.
 See
 .Sx Configuring CertFP .
 .
@@ -246,11 +286,11 @@ Generate a TLS client certificate using
 and write it to
 .Ar path .
 .
-.It Fl h Ar host | Cm host No = Ar host
-Connect to
+.It Fl h Ar host | Cm host Ar host
+Connect to the IRC server
 .Ar host .
 .
-.It Fl i Ar pattern | Cm ignore No = Ar pattern
+.It Fl i Ar pattern | Cm ignore Ar pattern
 Add a case-insensitive message ignore pattern,
 which may contain
 .Ql * ,
@@ -265,56 +305,69 @@ The format of the pattern is as follows:
 .Ed
 .Pp
 The commands which can be matched are:
-.Sy INVITE ,
-.Sy JOIN ,
-.Sy NICK ,
-.Sy NOTICE ,
-.Sy PART ,
-.Sy PRIVMSG ,
-.Sy QUIT ,
-.Sy SETNAME .
+.Sy invite ,
+.Sy join ,
+.Sy nick ,
+.Sy notice ,
+.Sy part ,
+.Sy privmsg ,
+.Sy quit ,
+.Sy setname .
+.Pp
+Visibility of ignored messages
+can be toggled using
+.Ic M--
+and
+.Ic M-+ .
 .
-.It Fl j Ar channels Oo Ar keys Oc | Cm join No = Ar channels Oo Ar keys Oc
+.It Fl j Ar channels Oo Ar keys Oc | Cm join Ar channels Oo Ar keys Oc
 Join the comma-separated list of
 .Ar channels
 with the optional comma-separated list of channel
 .Ar keys .
+No spaces may appear in either list.
 .
-.It Fl k Ar path | Cm priv No = Ar priv
-Load the TLS client private key from
-.Ar path .
-The
-.Ar path
-is searched for in the same manner
-as configuration files.
+.It Fl k Ar path | Cm priv Ar path
+Load the TLS client private key 
+for a certificate loaded with the
+.Cm cert
+option from
+.Ar path ,
+which is search for
+in the same manner as configuration files.
 .
 .It Fl l | Cm log
-Log chat events to files in paths
-.Pa $XDG_DATA_HOME/catgirl/log/network/channel/YYYY-MM-DD.log .
+Log messages to files in
+.Pa $XDG_DATA_HOME/catgirl/log
+.Po
+usually
+.Pa ~/.local/share/catgirl/log
+.Pc .
+Directories are created
+for each network and channel,
+and files are created for each date
+in the format
+.Pa YYYY-MM-DD.log .
 .
-.It Fl m Ar mode | Cm mode No = Ar mode
-Set the user
-.Ar mode .
+.It Fl m Ar modes | Cm mode Ar modes
+Set user modes as soon as possible
+after connecting.
 .
-.It Fl n Ar nick Oo Ar ... Oc | Cm nick No = Ar nick Oo Ar ... Oc
-Set nickname to
-.Ar nick .
-The default nickname is
-the value of the environment variable
+.It Fl n Ar nick Oo Ar ... Oc | Cm nick Ar nick Oo Ar ... Oc
+Set the nickname with optional fallbacks,
+should one nick be unavailable.
+Each nick is treated as a highlight word.
+The default nickname is the value of
 .Ev USER .
-Additional space-separated nicks
-will be tried in order
-if the first is not available,
-and all nicks
-are treated as highlight words.
 .
 .It Fl o
-Print the server certificate chain
-to standard output in PEM format
-and exit.
+Connect to the server
+only to obtain its certificate chain
+and write it to standard output
+in PEM format.
 .
-.It Fl p Ar port | Cm port No = Ar port
-Connect to
+.It Fl p Ar port | Cm port Ar port
+Connect to the IRC server on
 .Ar port .
 The default port is 6697.
 .
@@ -323,17 +376,27 @@ Raise the default message visibility threshold
 for new windows,
 hiding general events
 (joins, quits, etc.).
+The threshold can be lowered with
+.Ic M-- .
 .
-.It Fl r Ar real | Cm real No = Ar real
-Set realname to
-.Ar real .
-The default realname is the same as the nickname.
+.It Fl r Ar real | Cm real Ar real
+Set the
+.Dq realname
+which appears in
+.Ic /whois .
+The default is the same as the nickname.
+This is a good place to add your pronouns.
 .
-.It Fl s Ar name | Cm save No = Ar name
-Save and load the contents of windows from
+.It Fl s Ar name | Cm save Ar name
+Persist windows and their scrollback
+in a file called
 .Ar name
 in
-.Pa $XDG_DATA_DIRS/catgirl ,
+.Pa $XDG_DATA_DIRS/catgirl
+.Po
+usually
+.Pa ~/.local/share/catgirl
+.Pc ,
 or an absolute or relative path if
 .Ar name
 starts with
@@ -342,36 +405,43 @@ starts with
 or
 .Ql \&../ .
 .
-.It Fl t Ar path | Cm trust No = Ar path
-Trust the self-signed certificate
-loaded from
-.Ar path
-and disable server name verification.
-The
-.Ar path
-is searched for in the same manner
-as configuration files.
+.It Fl t Ar path | Cm trust Ar path
+Trust the self-signed certificate in
+.Ar path ,
+which is searched for
+in the same manner as configuration files.
+Server name verification is also disabled.
 See
 .Sx Connecting to Servers with Self-signed Certificates .
 .
-.It Fl u Ar user | Cm user No = Ar user
-Set username to
-.Ar user .
-The default username is the same as the nickname.
+.It Fl u Ar user | Cm user Ar user
+Set the username.
+This is almost entirely irrelevant,
+except that it's more likely to remain stable,
+and
+.Nm
+uses it to choose nick colours.
+The default is the same as the nickname.
 .
 .It Fl v | Cm debug
-Log raw IRC messages to the
+Log raw IRC protocol to the
 .Sy <debug>
-window
+window,
 as well as standard error
 if it is not a terminal.
 .
-.It Fl w Ar pass | Cm pass No = Ar pass
-Log in with the server password
-.Ar pass .
+.It Fl w Ar pass | Cm pass Ar pass
+Connect using a server password.
 Leave
 .Ar pass
-blank to prompt for the password.
+blank
+.Po
+using an
+.Ql =
+.Pc
+to prompt for the password when
+.Nm
+starts.
 .El
 .
 .Ss Configuring CertFP