diff options
| -rw-r--r-- | catgirl.1 | 382 |
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 |