about summary refs log tree commit diff
path: root/catgirl.1
diff options
context:
space:
mode:
Diffstat (limited to 'catgirl.1')
-rw-r--r--catgirl.11411
1 files changed, 1123 insertions, 288 deletions
diff --git a/catgirl.1 b/catgirl.1
index 5511ed4..f2a2fbb 100644
--- a/catgirl.1
+++ b/catgirl.1
@@ -1,4 +1,4 @@
-.Dd October 3, 2019
+.Dd May 24, 2024
 .Dt CATGIRL 1
 .Os
 .
@@ -8,406 +8,1241 @@
 .
 .Sh SYNOPSIS
 .Nm
-.Op Fl NPRv
-.Op Fl a Ar auth
+.Op Fl Relqv
+.Op Fl C Ar copy
+.Op Fl H Ar hash
+.Op Fl I Ar highlight
+.Op Fl N Ar notify
+.Op Fl O Ar open
+.Op Fl S Ar bind
+.Op Fl T Ns Op Ar timestamp
+.Op Fl a Ar plain
+.Op Fl c Ar cert
 .Op Fl h Ar host
-.Op Fl j Ar chan
-.Op Fl k Ar keys
-.Op Fl l Ar path
+.Op Fl i Ar ignore
+.Op Fl j Ar join
+.Op Fl k Ar priv
+.Op Fl m Ar mode
 .Op Fl n Ar nick
 .Op Fl p Ar port
 .Op Fl r Ar real
+.Op Fl s Ar save
+.Op Fl t Ar trust
 .Op Fl u Ar user
 .Op Fl w Ar pass
+.Op Ar config ...
+.
+.Nm
+.Fl o
+.Op Fl S Ar bind
+.Op Fl h Ar host
+.Op Fl p Ar port
+.Op Ar config ...
+.
+.Nm
+.Fl g Ar cert
 .
 .Sh DESCRIPTION
+The
 .Nm
-is a curses, TLS-only IRC client.
+IRC client
+provides a curses interface for
+Internet Relay Chat
+over TLS.
+The only required option is
+.Fl h ,
+the host name to connect to.
+See
+.Sx EXAMPLES
+for managing further configuration.
+Type
+.Ic /help
+in
+.Nm
+to view the list of
+.Sx COMMANDS
+and
+.Sx KEY BINDINGS
+in this manual.
+.
+.Pp
+Options can be loaded from files
+listed on the command line.
+Files are searched for in
+.Pa $XDG_CONFIG_DIRS/catgirl
+.Po
+usually
+.Pa ~/.config/catgirl
+.Pc
+unless the path starts with
+.Ql / ,
+.Ql \&./
+or
+.Ql \&../ .
+For example,
+a configuration file at
+.Pa ~/.config/catgirl/tilde
+can be loaded by running
+.Ql catgirl tilde .
 .
 .Pp
-The arguments are as follows:
+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 "-w pass"
-.It Fl N
-Send notifications with
+.Bl -tag -width Ds
+.It Fl C Ar util | Cm copy Ar util
+Set the utility used by the
+.Ic /copy 
+command.
+Subsequent
+.Cm copy
+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
+or
+.Xr xsel 1 .
+.
+.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 colours,
+use 0,0.
+.
+.It Fl I Ar pattern | Cm highlight Ar pattern
+Add a case-insensitive message highlight pattern,
+which may contain
+.Ql * ,
+.Ql \&?
+and
+.Ql []
+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 .
+.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 Ar util
+Send notifications using a utility.
+Subsequent
+.Cm notify
+options add arguments
+to the utility.
+The window name and message
+are provided to the utility
+as two additional arguments,
+appropriate for
 .Xr notify-send 1 .
 .
-.It Fl P
-Prompt for nickname.
-.
-.It Fl R
-Restrict the use of the
-.Ic /join ,
-.Ic /query ,
-.Ic /quote ,
-.Ic /raw
-commands.
-.
-.It Fl a Ar auth
-Authenticate with SASL PLAIN.
-.Ar auth
-is a colon-separated
-username and password pair.
-.
-.It Fl h Ar host
-Connect to
+.It Fl O Ar util | Cm open Ar util
+Set the utility used by the
+.Ic /open
+command.
+Subsequent
+.Cm open
+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
+or
+.Xr xdg-open 1 .
+.
+.It Fl R | Cm restrict
+Disable the
+.Ic /copy ,
+.Ic /exec
+and
+.Ic /open
+commands,
+the
+.Cm notify
+option,
+and viewing this manual with
+.Ic /help .
+.
+.It Fl S Ar host | Cm bind Ar host
+Bind to source address
+.Ar host
+when connecting to the server.
+To connect from any IPv4 address,
+use 0.0.0.0.
+To connect from any IPv6 address,
+use ::.
+.
+.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 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 when
+.Nm
+starts.
+.
+.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 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 .
+.
+.It Fl g Ar path
+Generate a TLS client certificate using
+.Xr openssl 1
+and write it to
+.Ar path .
+.
+.It Fl h Ar host | Cm host Ar host
+Connect to the IRC server
 .Ar host .
 .
-.It Fl j Ar chan
-Join
-.Ar chan
+.It Fl i Ar pattern | Cm ignore Ar pattern
+Add a case-insensitive message ignore pattern,
+which may contain
+.Ql * ,
+.Ql \&?
+and
+.Ql []
+wildcards as in
+.Xr glob 7 .
+The format of the pattern is as follows:
+.Bd -ragged -offset indent
+.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 .
+.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 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 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 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 modes | Cm mode Ar modes
+Set user modes as soon as possible
 after connecting.
-.Ar chan
-may be a comma-separated list.
-.
-.It Fl k Ar keys
-Set keys for channels in
-.Fl j .
-.Ar keys
-may be a comma-separated list.
-.
-.It Fl l Ar path
-Log messages to
-subdirectories of
-.Ar path
-named by channel or nick
-in files named by date.
-.
-.It Fl n Ar nick
-Set nickname to
-.Ar nick .
-The default nickname
-is the user's name.
-.
-.It Fl p Ar port
-Connect to
+.
+.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 .
+.
+.It Fl o
+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 Ar port
+Connect to the IRC server on
 .Ar port .
 The default port is 6697.
 .
-.It Fl r Ar real
-Set realname to
-.Ar real .
-The default realname is
-the same as the nickname.
-.
-.It Fl u Ar user
-Set username to
-.Ar user .
-The default username is
-the same as the nickname.
-.
-.It Fl v
-Show raw IRC protocol in the
-.Sy <raw>
-window.
-If standard error is not a terminal,
-output raw IRC protocol
-to standard error.
+.It Fl q | Cm quiet
+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 w Ar pass
-Log in with
-.Ar pass .
+.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 Ar name
+Persist windows and their scrollback
+in a file called
+.Ar name
+in
+.Pa $XDG_DATA_DIRS/catgirl
+.Po
+usually
+.Pa ~/.local/share/catgirl
+.Pc ,
+or an absolute or relative path if
+.Ar name
+starts with
+.Ql / ,
+.Ql \&./ ,
+or
+.Ql \&../ .
+.
+.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 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 protocol to the
+.Sy <debug>
+window,
+as well as standard error
+if it is not a terminal.
+.
+.It Fl w Ar pass | Cm pass Ar pass
+Connect using a server password.
+Leave
+.Ar pass
+blank
+.Po
+using an
+.Ql =
+.Pc
+to prompt for the password when
+.Nm
+starts.
+.El
+.
+.Ss Configuring CertFP
+CertFP allows you to
+authenticate with NickServ during connection
+using a TLS client certificate
+rather than your account password.
+.Bl -enum
+.It
+Generate a new TLS client certificate:
+.Bd -literal -offset indent
+$ catgirl -g ~/.config/catgirl/example.pem
+.Ed
+.It
+Connect to the server using the certificate
+by adding the following configuration:
+.Bd -literal -offset indent
+cert example.pem
+.Ed
+.It
+Identify with NickServ,
+then add the certificate fingerprint
+to your account:
+.Bd -literal -offset indent
+/ns CERT ADD
+.Ed
+.It
+Enable SASL EXTERNAL in your configuration
+to require successful authentication
+when connecting
+(not possible on all networks):
+.Bd -literal -offset indent
+cert example.pem
+sasl-external
+.Ed
 .El
 .
+.Ss Connecting to Servers with Self-signed Certificates
+If connecting to a server fails
+with a certificate verification error
+due to a self-signed certificate,
+it needs to be trusted manually.
+.Bl -enum
+.It
+Connect to the server
+and write its certificate to a file:
+.Bd -literal -offset indent
+$ catgirl -o -h irc.example.org > ~/.config/catgirl/example.pem
+.Ed
+.It
+Configure
+.Nm
+to trust the certificate:
+.Bd -literal -offset indent
+trust example.pem
+.Ed
+.El
+.
+.Sh INTERFACE
+The
+.Nm
+interface is split
+into three main areas.
+.
+.Ss Status Line
+The top line of the terminal
+shows window statuses.
+Only the currently active window
+and windows with activity are shown.
+The status line for a window
+might look like this:
+.Bd -literal -offset indent
+1+ #ascii.town +3 ~7 @
+.Ed
+.Pp
+The number on the left
+is the window number.
+Following it may be one of
+.Ql - ,
+.Ql +
+or
+.Ql ++ ,
+as well as
+.Ql = .
+These indicate
+the message visibility threshold
+and mute status
+of the window.
+.Pp
+On the right side,
+the number following
+.Ql +
+indicates the number of unread messages.
+The number following
+.Ql ~
+indicates how many lines
+are below the current scroll position.
+An
+.Ql @
+indicates that there is unsent input
+waiting in the window's
+.Sx Input Line .
+.Pp
+.Nm
+will also set the terminal title,
+if possible,
+to the name of the network
+and active window,
+followed by the unread count
+for that window,
+and the unread count
+for all other windows
+in parentheses.
+.
+.Ss Chat Area
+The chat area shows
+messages and events.
+Regular messages are shown
+with the nick between
+.Ql <>
+angle brackets.
+Actions are shown
+with the nick preceded by
+.Ql * .
+Notices are shown
+with the nick between
+.Ql -
+hyphens.
+.Pp
+Blank lines are inserted into the chat
+as unread markers
+whenever there are messages
+in a window that is not active
+or the terminal is not focused
+(in some terminal emulators).
+.Pp
+While scrolling,
+the most recent 5 lines of chat
+are kept visible below a marker line.
+.
+.Ss Input Line
+The bottom line of the terminal
+is where messages and commands are entered.
+When entering a message, action or notice,
+your nick appears on the left,
+as it would in the
+.Sx Chat Area .
+When entering a command,
+no nick is shown.
+.Pp
+Formatting codes are shown
+in the input line
+as reverse-video uppercase letters.
+These will not appear in the sent message.
+.Pp
+Input that is too long
+to send as a single message
+will have a red background
+starting at the point where it will be split
+into a second message.
+.
 .Sh COMMANDS
-Any unique prefix
-may be used to abbreviate a command.
+Commands can be abbreviated
+if no other command
+shares the same prefix.
+For example,
+.Ic /join
+can be typed
+.Ic /j ,
+and
+.Ic /window
+can be typed
+.Ic /wi .
 .
 .Ss Chat Commands
 .Bl -tag -width Ds
-.It Ic /join Ar chan Op Ar key
-Join a channel.
-.
-.It Ic /list Op Ar chan
-List channels.
-.
+.It Ic /away Op Ar message
+Set or clear your away status.
+This is sent in reply to private messages
+and shown in
+.Ic /whois .
+.It Ic /cs Ar command
+Send a command to ChanServ,
+the service for managing registered channels.
+.It Ic /invite Ar nick
+Invite someone to the channel.
+.It Ic /join Op Ar channel Op Ar key
+Join the named channel,
+the current channel (if you've left),
+or the channel you've been invited to.
+.It Ic /list Op Ar search
+List channels, their user counts and their topics.
+The
+.Ar search
+can usually contain glob-style wildcards.
 .It Ic /me Op Ar action
 Send an action message.
-.
-.It Ic /names , /who
-List users in the current channel.
-.
+These are used to write messages in third person.
+.It Ic /msg Ar nick message
+Send a private message to someone.
+.It Ic /names
+List the users in the channel.
 .It Ic /nick Ar nick
-Change nicknames.
-.
+Change your nickname.
+.It Ic /notice Ar message
+Send a notice.
+It's best not to do this.
+.It Ic /ns Ar command
+Send a command to NickServ,
+the service for managing your account.
+.It Ic /ops
+List channel operators.
+They can kick or ban someone from the channel.
 .It Ic /part Op Ar message
-Leave the current channel.
-.
+Leave the channel.
+Use
+.Ic /close
+if you want to close the window afterwards.
 .It Ic /query Ar nick
-Open a private message view.
-.
+Start a private conversation with someone.
 .It Ic /quit Op Ar message
-Quit IRC.
-.
+Disconnect from IRC and close
+.Nm .
+You can do this even quicker with
+.Ic C-c .
 .It Ic /quote Ar command
 Send a raw IRC command.
-.
+Often
+.Nm
+will not know how to interpret the results.
+You can use
+.Ic M--
+to show unknown server responses
+in the
+.Sy <network>
+or channel windows.
+.It Ic /say Ar message
+Send a regular message.
+This is useful
+if the message you want to send
+begins with a slash.
+.It Ic /setname Ar name
+Update your 
+.Dq realname
+if the server supports it.
+This may be broadcast
+to other users
+with clients that support it.
 .It Ic /topic Op Ar topic
-Show or set the topic of the current channel.
-.
-.It Ic /whois Ar nick
-Query information about a user.
-.
-.It Ic /znc Ar command
-Send
-.Xr znc 1
-command.
+Show or set the topic of the channel.
+Press
+.Ic Tab
+twice immediately after
+.Ic /topic
+to copy the current topic.
+.It Ic /whois Op Ar nick
+Query information about a user or yourself.
+.It Ic /whowas Ar nick
+Query past information about a user.
 .El
 .
-.Pp
-Any messages entered in the
-.Sy <raw>
-window will be sent as raw IRC commands.
-.
-.Ss UI Commands
+.Ss Interface Commands
 .Bl -tag -width Ds
-.It Ic /close
-Close the current window.
-.
-.It Ic /help , /man
-View this manual.
-.
-.It Ic /move Ar num
-Move window to number.
-If
-.Ar num
-starts with
-.Cm +
-or
-.Cm - ,
-the number is relative to the current window.
-.
-.It Ic /open Op Ar range
-Open a
-.Ar range
-of recent URLs
-in the current window with
-.Xr open 1 .
-URLs are numbered
-from the most recent
-starting at 1.
-The
-.Ar range
-may be a single number,
-or a hyphen- or comma-separated range.
-.
-.It Ic /open Ar substring
-Open the most recent URL
-in the current window
-matching the
+.It Ic /close Op Ar name | num
+Close the named, numbered or current window.
+.It Ic /copy Op Ar nick | substring
+Copy the most recent URL from
+.Ar nick
+or matching
 .Ar substring .
-.
-.It Ic /raw
-Toggle the
-.Sy <raw>
+.It Ic /debug
+Toggle logging in the
+.Sy <debug>
 window.
-.
-.It Ic /url
-Hide the UI
-and list the most recent URLs
-in the current window.
-Press
-.Ic Enter
-to resume the UI.
-.
-.It Ic /window Ar name
-Switch to window by name.
-.
-.It Ic /window Ar num , Ic / Ns Ar num
+.It Ic /exec Ar command
+Run
+.Ar command
+with
+.Ev SHELL
+and interpret its output
+as input to the current window,
+including as commands.
+.It Ic /help
+View this manual.
+Type
+.Ic q
+to return to
+.Nm .
+.It Ic /help Ar topic
+List the server help for a topic.
+Try
+.Ic /help index
+for a list of topics.
+.It Ic /highlight Op Ar pattern
+List message highlight patterns
+or temporarily add a pattern.
+To permanently add a pattern,
+use the
+.Cm highlight
+option.
+.It Ic /ignore Op Ar pattern
+List message ignore patterns
+or temporarily add a pattern.
+To permanently add a pattern,
+use the
+.Cm ignore
+option.
+.It Ic /move Oo Ar name Oc Ar num
+Move the named or current window to number.
+.It Ic /o ...
+Alias of
+.Ic /open .
+.It Ic /open Op Ar count
+Open each of
+.Ar count
+most recent URLs.
+.It Ic /open Ar nick | substring
+Open the most recent URL from
+.Ar nick
+or matching
+.Ar substring .
+.It Ic /unhighlight Ar pattern
+Temporarily remove a message highlight pattern.
+.It Ic /unignore Ar pattern
+Temporarily remove a message ignore pattern.
+.It Ic /window
+List all windows.
+.It Ic /window Ar name | substring
+Switch to window by name
+or matching substring.
+.It Ic /window Ar num | Ic / Ns Ar num
 Switch to window by number.
-If
-.Ar num
-starts with
-.Cm +
-or
-.Cm - ,
-the number is relative to the current window.
+.El
+.
+.Ss Operator Commands
+.Bl -tag -width Ds
+.It Ic /ban Op Ar mask ...
+List or ban masks from the channel.
+.It Ic /deop Op Ar nick ...
+Revoke channel operator status from users or yourself.
+.It Ic /devoice Op Ar nick ...
+Revoke voice from users or yourself in the channel.
+.It Ic /except Op Ar mask ...
+List or add masks to the channel ban exception list.
+.It Ic /invex Op Ar mask ...
+List or add masks to the channel invite list.
+.It Ic /kick Ar nick Op Ar message
+Kick a user from the channel.
+.It Ic /mode Oo Ar modes Oc Op Ar param ...
+Show or set channel modes.
+In the
+.Sy <network>
+window,
+show or set user modes.
+.It Ic /op Op Ar nick ...
+Grant users or yourself channel operator status.
+.It Ic /unban Ar mask ...
+Unban masks from the channel.
+.It Ic /unexcept Ar mask ...
+Remove masks from the channel ban exception list.
+.It Ic /uninvex Ar mask ...
+Remove masks from the channel invite list.
+.It Ic /voice Op Ar nick ...
+Grant users or yourself voice in the channel.
 .El
 .
 .Sh KEY BINDINGS
+The
 .Nm
-provides
+interface provides
 .Xr emacs 1 Ns -like
-line editing keys
-as well as keys for applying IRC formatting.
+line editing
+as well as keys for IRC formatting.
 The prefixes
-.Ic C- , M- , S-
-represent the control, meta (alt) and shift modifiers,
-respectively.
-.Ic M- Ns Ar x
-sequences can also be typed as
-.Ic Esc
-followed by
-.Ar x .
+.Ic C-
+and
+.Ic M-
+represent the control and meta (alt)
+modifiers, respectively.
 .
 .Ss Line Editing
 .Bl -tag -width Ds -compact
 .It Ic C-a
-Move cursor to beginning of line.
+Move to beginning of line.
 .It Ic C-b
-Move cursor left.
+Move left.
 .It Ic C-d
-Delete character under cursor.
+Delete next character.
 .It Ic C-e
-Move cursor to end of line.
+Move to end of line.
 .It Ic C-f
-Move cursor right.
+Move right.
 .It Ic C-k
-Delete line after cursor.
+Delete to end of line.
+.It Ic C-t
+Transpose characters.
 .It Ic C-u
-Delete line.
+Delete to beginning of line.
 .It Ic C-w
-Delete word before cursor.
+Delete previous word.
+.It Ic C-x
+Expand a text macro beginning with
+.Ql \e .
+.It Ic C-y
+Paste previously deleted text.
+.It Ic M-Enter
+Insert a newline without sending a command.
 .It Ic M-b
-Move cursor to beginning of word.
+Move to previous word.
 .It Ic M-d
-Delete word after cursor.
+Delete next word.
 .It Ic M-f
-Move cursor to end of word.
+Move to next word.
+.It Ic M-q
+Collapse all whitespace.
 .It Ic Tab
-Cycle through completions for
-commands, nicks and channels.
+Complete nick, channel, command or macro.
 .El
+.Pp
+Arrow and navigation keys
+also work as expected.
 .
-.Ss IRC Formatting
+.Ss Window Keys
 .Bl -tag -width Ds -compact
-.It Ic C-_
-Toggle underline.
-.It Ic C-o
-Toggle bold.
+.It Ic C-l
+Redraw the UI.
+.It Ic C-n
+Switch to next window.
+.It Ic C-p
+Switch to previous window.
 .It Ic C-r
-Set or reset color.
+Scroll to previous line matching input.
 .It Ic C-s
-Reset formatting.
-.It Ic C-t
-Toggle italics.
+Scroll to next line matching input.
 .It Ic C-v
-Toggle reverse video.
-This must usually be typed as
-.Ic C-v C-v .
+Scroll down a page.
+.It Ic M-+
+Raise message visibility threshold,
+hiding ignored messages,
+general events
+(joins, quits, etc.),
+or non-highlighted messages.
+.It Ic M--
+Lower message visibility threshold,
+showing ignored messages
+and unknown replies.
+.It Ic M-=
+Toggle mute.
+Muted windows do not appear in the status line
+unless you are mentioned.
+.It Ic M-/
+Switch to previously selected window.
+.It Ic M-<
+Scroll to top.
+.It Ic M->
+Scroll to bottom.
+.It Ic M- Ns Ar n
+Switch to window by number 0\(en9.
+.It Ic M-a
+Cycle through unread windows.
+.It Ic M-l
+List the contents of the window
+without word-wrapping
+and with timestamps.
+Press
+.Ic Enter
+to return to
+.Nm .
+.It Ic M-m
+Insert a blank line in the window.
+.It Ic M-n
+Scroll to next highlight.
+.It Ic M-p
+Scroll to previous highlight.
+.It Ic M-s
+Reveal spoiler text.
+.It Ic M-t
+Toggle timestamps.
+.It Ic M-u
+Scroll to first unread line.
+.It Ic M-v
+Scroll up a page.
+.El
+.
+.Ss IRC Formatting
+.Bl -tag -width "C-z C-v" -compact
+.It Ic C-z C-v
+Insert the next input character literally.
+.It Ic C-z b
+Toggle bold.
+.It Ic C-z c
+Set or reset color.
+.It Ic C-z i
+Toggle italics.
+.It Ic C-z o
+Reset formatting.
+.It Ic C-z p
+Manually toggle paste mode.
+.It Ic C-z r
+Toggle reverse color.
+.It Ic C-z s
+Set spoiler text (black on black).
+.It Ic C-z u
+Toggle underline.
+.El
+.
+.Pp
+Some color codes can be inserted
+with the following:
+.Bl -column "C-z A" "magenta" "C-z N" "orange (dark yellow)"
+.It Ic C-z A Ta gray Ta Ic C-z N Ta brown (dark red)
+.It Ic C-z B Ta blue Ta Ic C-z O Ta orange (dark yellow)
+.It Ic C-z C Ta cyan Ta Ic C-z P Ta pink (light magenta)
+.It Ic C-z G Ta green Ta Ic C-z R Ta red
+.It Ic C-z K Ta black Ta Ic C-z W Ta white
+.It Ic C-z M Ta magenta Ta Ic C-z Y Ta yellow
 .El
 .
 .Pp
+To set other colors, follow
+.Ic C-z c
+by one or two digits for the foreground color,
+optionally followed by a comma
+and one or two digits for the background color.
 To reset color, follow
-.Ic C-r
+.Ic C-z c
 by a non-digit.
-To set colors, follow
-.Ic C-r
-by one or two digits
-to set the foreground color,
-optionally followed by a comma
-and one or two digits
-to set the background color.
 .
 .Pp
 The color numbers are as follows:
-.Pp
-.Bl -column "7" "orange (dark yellow)" "15" "pink (light magenta)"
-.It 0 Ta white Ta \ 8 Ta yellow
-.It 1 Ta black Ta \ 9 Ta light green
-.It 2 Ta blue Ta 10 Ta cyan
-.It 3 Ta green Ta 11 Ta light cyan
-.It 4 Ta red Ta 12 Ta light blue
-.It 5 Ta brown (dark red) Ta 13 Ta pink (light magenta)
-.It 6 Ta magenta Ta 14 Ta gray
-.It 7 Ta orange (dark yellow) Ta 15 Ta light gray
-.El
-.
-.Ss Window Keys
-.Bl -tag -width "PageDown" -compact
-.It Ic C-l
-Redraw the UI.
-.It Ic C-n
-Switch to the next window.
-.It Ic C-p
-Switch to the previous window.
-.It Ic M-/
-Switch to the previously active window.
-.It Ic M-a
-Switch to next hot or unread window.
-.It Ic M-l
-Hide the UI and list the log for the current window.
-.It Ic M-m
-Insert a blank line in the window.
-.It Ic M- Ns Ar n
-Switch to window by number 0\(en9.
-.It Ic Down
-Scroll window down by one line.
-.It Ic PageDown
-Scroll window down by one page.
-.It Ic PageUp
-Scroll window up by one page.
-.It Ic Up
-Scroll window up by one line.
+.Bl -column "99" "orange (dark yellow)" "15" "pink (light magenta)"
+.It \ 0 Ta white Ta \ 8 Ta yellow
+.It \ 1 Ta black Ta \ 9 Ta light green
+.It \ 2 Ta blue Ta 10 Ta cyan
+.It \ 3 Ta green Ta 11 Ta light cyan
+.It \ 4 Ta red Ta 12 Ta light blue
+.It \ 5 Ta brown (dark red) Ta 13 Ta pink (light magenta)
+.It \ 6 Ta magenta Ta 14 Ta gray
+.It \ 7 Ta orange (dark yellow) Ta 15 Ta light gray
+.It 99 Ta default Ta Ta
 .El
 .
 .Sh ENVIRONMENT
 .Bl -tag -width Ds
+.It Ev SHELL
+The shell used by
+.Ic /exec .
+The default is
+.Pa /bin/sh .
 .It Ev USER
 The default nickname.
 .El
 .
-.Sh EXAMPLES
-.Dl catgirl -h chat.freenode.net -j '#ascii.town'
+.Sh FILES
+.Bl -tag -width Ds
+.It Pa $XDG_CONFIG_DIRS/catgirl
+Configuration files are searched for first in
+.Ev $XDG_CONFIG_HOME ,
+usually
+.Pa ~/.config ,
+followed by the colon-separated list of paths
+.Ev $XDG_CONFIG_DIRS ,
+usually
+.Pa /etc/xdg .
+.It Pa ~/.config/catgirl
+The most likely location of configuration files.
 .
-.Sh STANDARDS
+.It Pa $XDG_DATA_DIRS/catgirl
+Save files are searched for first in
+.Ev $XDG_DATA_HOME ,
+usually
+.Pa ~/.local/share ,
+followed by the colon-separated list of paths
+.Ev $XDG_DATA_DIRS ,
+usually
+.Pa /usr/local/share:/usr/share .
+.It Pa ~/.local/share/catgirl
+The most likely location of save files.
+.El
+.
+.Sh EXIT STATUS
+The
 .Nm
-is a partial implementation of the following:
+client exits 0
+if requested by the user,
+69 if the connection is lost,
+and >0 if any other error occurs.
 .
+.Sh EXAMPLES
+Join
+.Li #ascii.town
+from the command line:
+.Bd -literal -offset indent
+$ catgirl -h irc.tilde.chat -j '#ascii.town'
+.Ed
+.Pp
+Create a configuration file in
+.Pa ~/.config/catgirl/tilde :
+.Bd -literal -offset indent
+host = irc.tilde.chat
+join = #ascii.town
+.Ed
+.Pp
+Load the configuration file:
+.Bd -literal -offset indent
+$ catgirl tilde
+.Ed
+.
+.Sh STANDARDS
 .Bl -item
 .It
 .Rs
+.%A Adam
+.%A Attila Molnar
+.%T invite-notify Extension
+.%I IRCv3 Working Group
+.%U https://ircv3.net/specs/extensions/invite-notify
+.Re
+.It
+.Rs
+.%A Jack Allnutt
+.%A Val Lorentz
+.%A Daniel Oaks
+.%T Modern IRC Client Protocol
+.%I ircdocs
+.%U https://modern.ircdocs.horse/index.html
+.Re
+.It
+.Rs
+.%A Kiyoshi Aman
+.%A Kyle Fuller
+.%A St\('ephan Kochen
+.%A Alexey Sokolov
+.%A James Wheare
+.%T Message Tags
+.%I IRCv3 Working Group
+.%U https://ircv3.net/specs/extensions/message-tags
+.Re
+.It
+.Rs
+.%A Kiyoshi Aman
+.%T extended-join Extension
+.%I IRCv3 Working Group
+.%U https://ircv3.net/specs/extensions/extended-join
+.Re
+.It
+.Rs
+.%A Waldo Bastian
+.%A Ryan Lortie
+.%A Lennart Poettering
+.%T XDG Base Directory Specification
+.%U https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+.%D November 24, 2010
+.Re
+.It
+.Rs
+.%A Christine Dodrill
+.%A Ryan
+.%A James Wheare
+.%T chghost Extension
+.%I IRCv3 Working Group
+.%U https://ircv3.net/specs/extensions/chghost
+.Re
+.It
+.Rs
+.%A Kyle Fuller
+.%A St\('ephan Kochen
+.%A Alexey Sokolov
+.%A James Wheare
+.%T server-time Extension
+.%I IRCv3 Working Group
+.%U https://ircv3.net/specs/extensions/server-time
+.Re
+.It
+.Rs
+.%A Lee Hardy
+.%A Perry Lorier
+.%A Kevin L. Mitchell
+.%A Attila Molnar
+.%A Daniel Oakley
+.%A William Pitcock
+.%A James Wheare
+.%T Client Capability Negotiation
+.%I IRCv3 Working Group
+.%U https://ircv3.net/specs/core/capability-negotiation
+.Re
+.It
+.Rs
+.%A S. Josefsson
+.%T The Base16, Base32, and Base64 Data Encodings
+.%I IETF
+.%R RFC 4648
+.%U https://tools.ietf.org/html/rfc4648
+.%D October 2006
+.Re
+.It
+.Rs
 .%A C. Kalt
 .%T Internet Relay Chat: Client Protocol
 .%I IETF
-.%N RFC 2812
-.%D April 2000
+.%R RFC 2812
 .%U https://tools.ietf.org/html/rfc2812
+.%D April 2000
 .Re
-.
 .It
 .Rs
-.%A Kevin L. Mitchell
-.%A Perry Lorier
-.%A Lee Hardy
-.%A William Pitcock
-.%T IRCv3.1 Client Capability Negotiation
+.%A Janne Mareike Koschinski
+.%T setname Extension
 .%I IRCv3 Working Group
-.%U https://ircv3.net/specs/core/capability-negotiation-3.1.html
+.%U https://ircv3.net/specs/extensions/setname
+.Re
+.It
+.Rs
+.%A Mantas Mikul\[u0117]nas
+.%T userhost-in-names Extension
+.%I IRCv3 Working Group
+.%U https://ircv3.net/specs/extensions/userhost-in-names
+.Re
+.It
+.Rs
+.%A Daniel Oaks
+.%T IRC Formatting
+.%I ircdocs
+.%U https://modern.ircdocs.horse/formatting.html
+.Re
+.It
+.Rs
+.%A Daniel Oaks
+.%T Standard Replies Extension
+.%I IRCv3 Working Group
+.%U https://ircv3.net/specs/extensions/standard-replies
+.Re
+.It
+.Rs
+.%A J. Oikarinen
+.%A D. Reed
+.%T Internet Relay Chat Protocol
+.%I IETF
+.%R RFC 1459
+.%U https://tools.ietf.org/html/rfc1459
+.%D May 1993
 .Re
-.
 .It
 .Rs
-.%A Jilles Tjoelker
 .%A William Pitcock
+.%A Jilles Tjoelker
 .%T IRCv3.1 SASL Authentication
 .%I IRCv3 Working Group
-.%U https://ircv3.net/specs/extensions/sasl-3.1.html
+.%U https://ircv3.net/specs/extensions/sasl-3.1
 .Re
-.
 .It
 .Rs
-.%A K. Zeilenga, Ed.
-.%Q OpenLDAP Foundation
-.%T The PLAIN Simple Authentication and Security Layer (SASL) Mechanism
-.%I IETF
-.%N RFC 4616
-.%D August 2006
-.%U https://tools.ietf.org/html/rfc4616
+.%A William Pitcock
+.%T multi-prefix Extension
+.%I IRCv3 Working Group
+.%U https://ircv3.net/specs/extensions/multi-prefix
 .Re
-.
 .It
 .Rs
-.%A S. Josefsson
-.%Q SJD
-.%T The Base16, Base32, and Base64 Data Encodings
+.%A James Wheare
+.%T Message IDs
+.%I IRCv3 Working Group
+.%U https://ircv3.net/specs/extensions/message-ids
+.Re
+.It
+.Rs
+.%A James Wheare
+.%T reply Client Tag
+.%I IRCv3 Working Group
+.%U https://ircv3.net/specs/client-tags/reply
+.Re
+.It
+.Rs
+.%A K. Zeilenga, Ed.
+.%T The PLAIN Simple Authentication and Security Layer (SASL) Mechanism
 .%I IETF
-.%N RFC 4648
-.%D October 2006
-.%U https://tools.ietf.org/html/rfc4648
+.%R RFC 4616
+.%U https://tools.ietf.org/html/rfc4616
+.%D August 2006
 .Re
 .El
 .
-.Sh CAVEATS
+.Ss Extensions
+The
 .Nm
-does not support unencrypted connections.
+client implements the
+.Sy causal.agency/consumer
+vendor-specific IRCv3 capability
+offered by
+.Xr pounce 1 .
+The consumer position is stored in the
+.Cm save
+file.
+.
+.Sh AUTHORS
+.An June McEnroe Aq Mt june@causal.agency
+.
+.Sh BUGS
+Send mail to
+.Aq Mt list+catgirl@causal.agency
+or join
+.Li #ascii.town
+on
+.Li irc.tilde.chat .