diff options
Diffstat (limited to 'catgirl.1')
| -rw-r--r-- | catgirl.1 | 488 |
1 files changed, 343 insertions, 145 deletions
diff --git a/catgirl.1 b/catgirl.1 index b09d55e..815eade 100644 --- a/catgirl.1 +++ b/catgirl.1 @@ -1,4 +1,4 @@ -.Dd January 25, 2021 +.Dd October 11, 2023 .Dt CATGIRL 1 .Os . @@ -8,19 +8,21 @@ . .Sh SYNOPSIS .Nm -.Op Fl KRelv +.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 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 @@ -67,11 +69,21 @@ 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 \&../ . +Files and flags listed later +on the command line +take precedence over +those listed earlier. +. +.Pp Each option is placed on a line, and lines beginning with .Ql # @@ -79,30 +91,37 @@ are ignored. The options are listed below following their corresponding flags. . -.Pp -The arguments are as follows: .Bl -tag -width Ds -.It Fl C Ar util , Cm copy = Ar util +.It Fl C Ar util | Cm copy No = Ar util Set the utility used by .Ic /copy . -Use more than once to add arguments to +Subsequent +.Cm copy +options append arguments to .Ar util . +The URL to copy is provided to +.Ar util +on standard input. The default is the first available of .Xr pbcopy 1 , .Xr wl-copy 1 , .Xr xclip 1 , .Xr xsel 1 . . -.It Fl H Ar init,bound , Cm hash = Ar init,bound -Set the initial value of -the nick color hash function -and the maximum IRC color value used. +.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, use 0,15. +To disable nick and channel colors, +use 0,0. . -.It Fl I Ar pattern , Cm highlight = Ar pattern +.It Fl I Ar pattern | Cm highlight No = Ar pattern Add a case-insensitive message highlight pattern, which may contain .Ql * , @@ -110,17 +129,13 @@ which may contain and .Ql [] wildcards as in -.Xr sh 1 . +.Xr glob 7 . The format of the pattern is as follows: .Bd -ragged -offset indent -.Ar nick Ns Oo Ar !user@host -.Oo Ar command -.Oo Ar channel -.Oo Ar message -.Oc Oc Oc Oc +.Ar nick Ns Op Ar !user@host Op Ar command Op Ar channel Op Ar message .Ed .Pp -The commands which can be filtered are: +The commands which can be matched are: .Sy INVITE , .Sy JOIN , .Sy NICK , @@ -130,40 +145,34 @@ The commands which can be filtered are: .Sy QUIT , .Sy SETNAME . . -.It Fl K , Cm kiosk -Disable the -.Ic /copy , -.Ic /debug , -.Ic /exec , -.Ic /join , -.Ic /list , -.Ic /msg , -.Ic /open , -.Ic /part , -.Ic /query , -.Ic /quote -commands. -. -.It Fl N Ar util , Cm notify = Ar util +.It Fl N Ar util | Cm notify No = Ar util Send notifications using a utility. -Use more than once to add arguments to +Subsequent +.Cm notify +options append arguments to .Ar util . -Two additional arguments are passed to -.Ar util : -a title and a description, +The window name and message +are provided to +.Ar util +as two additional arguments, appropriate for .Xr notify-send 1 . . -.It Fl O Ar util , Cm open = Ar util +.It Fl O Ar util | Cm open No = Ar util Set the utility used by .Ic /open . -Use more than once to add arguments to +Subsequent +.Cm open +options append arguments to .Ar util . +The URL to open is provided to +.Ar util +as an argument. The default is the first available of .Xr open 1 , .Xr xdg-open 1 . . -.It Fl R , Cm restrict +.It Fl R | Cm restrict Disable the .Ic /copy , .Ic /exec @@ -171,28 +180,43 @@ and .Ic /open commands, the -.Fl N +.Cm notify option, and viewing this manual with .Ic /help . . -.It Fl S Ar host , Cm bind = Ar host +.It Fl S Ar host | Cm bind No = Ar host Bind to source address .Ar host when connecting to the server. +To connect from any address +over IPv4 only, +use 0.0.0.0. +To connect from any address +over IPv6 only, +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 a Ar user : Ns Ar pass , Cm sasl-plain = Ar user : Ns Ar pass +.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. -Since this requires the account password -in plain text, -it is recommended to use SASL EXTERNAL instead with -.Fl e . +Leave +.Ar pass +blank to prompt for the password. . -.It Fl c Ar path , Cm cert = Ar path +.It Fl c Ar path | Cm cert No = Ar path Load the TLS client certificate from .Ar path . The @@ -201,19 +225,19 @@ is searched for in the same manner as configuration files. If the private key is in a separate file, it is loaded with -.Fl k . +.Cm priv . With -.Fl e , +.Cm sasl-external , authenticate using SASL EXTERNAL. Certificates can be generated with .Fl g . . -.It Fl e , Cm sasl-external +.It Fl e | Cm sasl-external Authenticate using SASL EXTERNAL, also known as CertFP. The TLS client certificate is loaded with -.Fl c . -For more information, see +.Cm cert . +See .Sx Configuring CertFP . . .It Fl g Ar path @@ -222,11 +246,11 @@ Generate a TLS client certificate using and write it to .Ar path . . -.It Fl h Ar host , Cm host = Ar host +.It Fl h Ar host | Cm host No = Ar host Connect to .Ar host . . -.It Fl i Ar pattern , Cm ignore = Ar pattern +.It Fl i Ar pattern | Cm ignore No = Ar pattern Add a case-insensitive message ignore pattern, which may contain .Ql * , @@ -234,17 +258,13 @@ which may contain and .Ql [] wildcards as in -.Xr sh 1 . +.Xr glob 7 . The format of the pattern is as follows: .Bd -ragged -offset indent -.Ar nick Ns Oo Ar !user@host -.Oo Ar command -.Oo Ar channel -.Oo Ar message -.Oc Oc Oc Oc +.Ar nick Ns Op Ar !user@host Op Ar command Op Ar channel Op Ar message .Ed .Pp -The commands which can be filtered are: +The commands which can be matched are: .Sy INVITE , .Sy JOIN , .Sy NICK , @@ -254,11 +274,13 @@ The commands which can be filtered are: .Sy QUIT , .Sy SETNAME . . -.It Fl j Ar join , Cm join = Ar join -Join the comma-separated list of channels -.Ar join . +.It Fl j Ar channels Oo Ar keys Oc | Cm join No = Ar channels Oo Ar keys Oc +Join the comma-separated list of +.Ar channels +with the optional comma-separated list of channel +.Ar keys . . -.It Fl k Ar path , Cm priv = Ar priv +.It Fl k Ar path | Cm priv No = Ar priv Load the TLS client private key from .Ar path . The @@ -266,31 +288,48 @@ The is searched for in the same manner as configuration files. . -.It Fl l , Cm log +.It Fl l | Cm log Log chat events to files in paths .Pa $XDG_DATA_HOME/catgirl/log/network/channel/YYYY-MM-DD.log . . -.It Fl n Ar nick , Cm nick = Ar nick +.It Fl m Ar mode | Cm mode No = Ar mode +Set the user +.Ar mode . +. +.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 user's name. +The default nickname is +the value of the environment variable +.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. . -.It Fl p Ar port , Cm port = Ar port +.It Fl p Ar port | Cm port No = Ar port Connect to .Ar port . The default port is 6697. . -.It Fl r Ar real , Cm real = Ar real +.It Fl q | Cm quiet +Raise the default message visibility threshold +for new windows, +hiding general events +(joins, quits, etc.). +. +.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 s Ar name , Cm save = Ar name +.It Fl s Ar name | Cm save No = Ar name Save and load the contents of windows from .Ar name in @@ -303,10 +342,11 @@ starts with or .Ql \&../ . . -.It Fl t Ar path , Cm trust = Ar path -Trust the certificate loaded from -.Ar path . -Server name verification is disabled. +.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 @@ -314,21 +354,24 @@ as configuration files. See .Sx Connecting to Servers with Self-signed Certificates . . -.It Fl u Ar user , Cm user = Ar user +.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 v , Cm debug +.It Fl v | Cm debug Log raw IRC messages 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 +.It Fl w Ar pass | Cm pass No = Ar pass Log in with the server password .Ar pass . +Leave +.Ar pass +blank to prompt for the password. .El . .Ss Configuring CertFP @@ -336,13 +379,13 @@ Log in with the server password .It Generate a new TLS client certificate: .Bd -literal -offset indent -catgirl -g ~/.config/catgirl/example.pem +$ catgirl -g ~/.config/catgirl/example.pem .Ed .It Connect to the server using the certificate: .Bd -literal -offset indent cert = example.pem -# or: catgirl -c example.pem +# or: $ catgirl -c example.pem .Ed .It Identify with services or use @@ -350,16 +393,17 @@ Identify with services or use then add the certificate fingerprint to your account: .Bd -literal -offset indent -/msg NickServ CERT ADD +/ns CERT ADD .Ed .It Enable SASL EXTERNAL to require successful authentication -when connecting: +when connecting +(not possible on all networks): .Bd -literal -offset indent cert = example.pem sasl-external -# or: catgirl -e -c example.pem +# or: $ catgirl -e -c example.pem .Ed .El . @@ -369,7 +413,7 @@ sasl-external 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 +$ catgirl -o -h irc.example.org > ~/.config/catgirl/example.pem .Ed .It Configure @@ -377,10 +421,108 @@ Configure to trust the certificate: .Bd -literal -offset indent trust = example.pem -# or: catgirl -t example.pem +# or: $ catgirl -t example.pem .Ed .El . +.Sh INTERFACE +The +.Nm +interface is split +into three areas. +. +.Ss Status Line +The top line of the terminal +shows window statuses. +Only the currently active window +and windows with activity are listed. +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 + , +.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 scroll position. +An +.Ql @ +indicates that there is unsent input +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. +.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 can be used to abbreviate a command. For example, @@ -396,8 +538,10 @@ Set or clear your away status. Send a command to ChanServ. .It Ic /invite Ar nick Invite a user to the channel. -.It Ic /join Ar channel -Join a channel. +.It Ic /join Op Ar channel Op Ar key +Join the named channel, +the current channel, +or the channel you've been invited to. .It Ic /list Op Ar channel List channels. .It Ic /me Op Ar action @@ -422,10 +566,9 @@ Start a private conversation. Quit IRC. .It Ic /quote Ar command Send a raw IRC command. -The -.Ic /debug -command is likely needed -for command output. +Use +.Ic M-- +to show unknown replies. .It Ic /say Ar message Send a regular message. .It Ic /setname Ar name @@ -436,8 +579,8 @@ Show or set the topic of the channel. Press .Ic Tab twice to copy the current topic. -.It Ic /whois Ar nick -Query information about a user. +.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 @@ -477,15 +620,22 @@ 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 -.Fl I . +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 -.Fl i . +To permanently add a pattern, +use the +.Cm ignore +option. .It Ic /move Oo Ar name Oc Ar num -Move named window to number. +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 @@ -499,9 +649,12 @@ or matching Temporarily remove a message highlight pattern. .It Ic /unignore Ar pattern Temporarily remove a message ignore pattern. -.It Ic /window Ar name -Switch to window by name. -.It Ic /window Ar num , Ic / Ns Ar num +.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. .El . @@ -589,6 +742,9 @@ Collapse all whitespace. .It Ic Tab Complete nick, channel, command or macro. .El +.Pp +Arrow and navigation keys +also work as expected. . .Ss Window Keys .Bl -tag -width Ds -compact @@ -607,11 +763,13 @@ Scroll down a page. .It Ic M-+ Raise message visibility threshold, hiding ignored messages, -general events, +general events +(joins, quits, etc.), or non-highlighted messages. .It Ic M-- Lower message visibility threshold, -showing ignored messages. +showing ignored messages +and unknown replies. .It Ic M-= Toggle mute. Muted windows do not appear in the status line @@ -640,6 +798,10 @@ Insert a blank line in the window. 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 @@ -647,7 +809,9 @@ Scroll up a page. .El . .Ss IRC Formatting -.Bl -tag -width Ds -compact +.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 @@ -656,14 +820,30 @@ Set or reset color. 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 -To set colors, follow +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 @@ -689,13 +869,10 @@ The color numbers are as follows: .Sh ENVIRONMENT .Bl -tag -width Ds .It Ev SHELL -The path executed by -.Ic /exec -with -.Fl c Ar command . -If unset, -.Pa /bin/sh -is used. +The shell used by +.Ic /exec . +The default is +.Pa /bin/sh . .It Ev USER The default nickname. .El @@ -735,26 +912,26 @@ if requested by the user, .Dv EX_UNAVAILABLE (69) if the connection is lost, -and >0 if an error occurs. +and >0 if any other error occurs. . .Sh EXAMPLES Join .Li #ascii.town from the command line: .Bd -literal -offset indent -catgirl -h chat.freenode.net -j '#ascii.town' +$ catgirl -h irc.tilde.chat -j '#ascii.town' .Ed .Pp Create a configuration file in -.Pa ~/.config/catgirl/freenode : +.Pa ~/.config/catgirl/tilde : .Bd -literal -offset indent -host = chat.freenode.net +host = irc.tilde.chat join = #ascii.town .Ed .Pp Load the configuration file: .Bd -literal -offset indent -catgirl freenode +$ catgirl tilde .Ed . .Sh STANDARDS @@ -763,13 +940,15 @@ catgirl freenode .Rs .%A Adam .%A Attila Molnar -.%T IRCv3.2 invite-notify Extension +.%T invite-notify Extension .%I IRCv3 Working Group -.%U https://ircv3.net/specs/extensions/invite-notify-3.2 +.%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 @@ -781,16 +960,16 @@ catgirl freenode .%A St\('ephan Kochen .%A Alexey Sokolov .%A James Wheare -.%T IRCv3 Message Tags +.%T Message Tags .%I IRCv3 Working Group .%U https://ircv3.net/specs/extensions/message-tags .Re .It .Rs .%A Kiyoshi Aman -.%T IRCv3.1 extended-join Extension +.%T extended-join Extension .%I IRCv3 Working Group -.%U https://ircv3.net/specs/extensions/extended-join-3.1 +.%U https://ircv3.net/specs/extensions/extended-join .Re .It .Rs @@ -804,9 +983,11 @@ catgirl freenode .It .Rs .%A Christine Dodrill -.%T IRCv3.2 chghost Extension +.%A Ryan +.%A James Wheare +.%T chghost Extension .%I IRCv3 Working Group -.%U https://ircv3.net/specs/extensions/chghost-3.2 +.%U https://ircv3.net/specs/extensions/chghost .Re .It .Rs @@ -814,19 +995,22 @@ catgirl freenode .%A St\('ephan Kochen .%A Alexey Sokolov .%A James Wheare -.%T IRCv3.2 server-time Extension +.%T server-time Extension .%I IRCv3 Working Group -.%U https://ircv3.net/specs/extensions/server-time-3.2 +.%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 -.%T IRCv3.1 Client Capability Negotiation +.%A James Wheare +.%T Client Capability Negotiation .%I IRCv3 Working Group -.%U https://ircv3.net/specs/core/capability-negotiation-3.1.html +.%U https://ircv3.net/specs/core/capability-negotiation .Re .It .Rs @@ -849,30 +1033,30 @@ catgirl freenode .It .Rs .%A Janne Mareike Koschinski -.%T IRCv3 setname Extension +.%T setname Extension .%I IRCv3 Working Group .%U https://ircv3.net/specs/extensions/setname .Re .It .Rs .%A Mantas Mikul\[u0117]nas -.%T IRCv3.2 userhost-in-names Extension +.%T userhost-in-names Extension .%I IRCv3 Working Group -.%U https://ircv3.net/specs/extensions/userhost-in-names-3.2 +.%U https://ircv3.net/specs/extensions/userhost-in-names .Re .It .Rs .%A Daniel Oaks -.%T Standard Replies Extension -.%I IRCv3 Working Group -.%U https://ircv3.net/specs/extensions/standard-replies +.%T IRC Formatting +.%I ircdocs +.%U https://modern.ircdocs.horse/formatting.html .Re .It .Rs .%A Daniel Oaks -.%T IRC Formatting -.%I ircdocs -.%U https://modern.ircdocs.horse/formatting.html +.%T Standard Replies Extension +.%I IRCv3 Working Group +.%U https://ircv3.net/specs/extensions/standard-replies .Re .It .Rs @@ -890,14 +1074,28 @@ catgirl freenode .%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 William Pitcock -.%T IRCv3.1 multi-prefix Extension +.%T multi-prefix Extension +.%I IRCv3 Working Group +.%U https://ircv3.net/specs/extensions/multi-prefix +.Re +.It +.Rs +.%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/extensions/multi-prefix-3.1 +.%U https://ircv3.net/specs/client-tags/reply .Re .It .Rs @@ -913,17 +1111,17 @@ catgirl freenode .Ss Extensions The .Nm -client can take advantage of the +client implements the .Sy causal.agency/consumer vendor-specific IRCv3 capability -implemented by +offered by .Xr pounce 1 . The consumer position is stored in the .Cm save file. . .Sh AUTHORS -.An June Bug Aq Mt june@causal.agency +.An June McEnroe Aq Mt june@causal.agency . .Sh BUGS Send mail to @@ -931,4 +1129,4 @@ Send mail to or join .Li #ascii.town on -.Li chat.freenode.net . +.Li irc.tilde.chat . |