added man page
This commit is contained in:
@@ -0,0 +1,505 @@
|
|||||||
|
.TH SIRC 1 "2026" "sirc" "User Commands"
|
||||||
|
.SH NAME
|
||||||
|
sirc \- simple terminal IRC client
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.B sirc
|
||||||
|
[\fIOPTIONS\fR]
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.B sirc
|
||||||
|
is a multi-server terminal IRC client written in C.
|
||||||
|
It connects to one or more IRC servers simultaneously, each in its own
|
||||||
|
thread, and presents a three-panel TUI: a channel list on the left grouped
|
||||||
|
by server, a chat area in the centre, and a user list on the right.
|
||||||
|
The top bar shows the current channel topic.
|
||||||
|
.PP
|
||||||
|
Dependencies are ncurses, OpenSSL, and pthreads only.
|
||||||
|
.SH OPTIONS
|
||||||
|
.TP
|
||||||
|
.BI \-\-host " HOST"
|
||||||
|
IRC server hostname.
|
||||||
|
Default:
|
||||||
|
.IR irc.libera.chat .
|
||||||
|
.TP
|
||||||
|
.BI \-\-port " PORT"
|
||||||
|
Server port number.
|
||||||
|
Default:
|
||||||
|
.IR 6697 .
|
||||||
|
.TP
|
||||||
|
.BI \-\-nick " NICK"
|
||||||
|
Nickname to use.
|
||||||
|
Default:
|
||||||
|
.IR circ_user .
|
||||||
|
Applied to all configured servers when no
|
||||||
|
.B \-\-host
|
||||||
|
is given.
|
||||||
|
.TP
|
||||||
|
.BI \-\-channel " CHAN"
|
||||||
|
Comma-separated list of channels to join on connect.
|
||||||
|
Example:
|
||||||
|
.IR "#python,#linux" .
|
||||||
|
.TP
|
||||||
|
.B \-\-tls
|
||||||
|
Enable TLS (default).
|
||||||
|
.TP
|
||||||
|
.B \-\-no\-tls
|
||||||
|
Disable TLS.
|
||||||
|
Use with plain-text servers, typically on port 6667.
|
||||||
|
.TP
|
||||||
|
.BI \-\-sasl\-user " USER"
|
||||||
|
SASL PLAIN username.
|
||||||
|
.TP
|
||||||
|
.BI \-\-sasl\-pass " PASS"
|
||||||
|
SASL PLAIN password.
|
||||||
|
.TP
|
||||||
|
.BI \-\-config " FILE"
|
||||||
|
Path to a configuration file.
|
||||||
|
Overrides the default search paths.
|
||||||
|
.TP
|
||||||
|
.B \-\-help
|
||||||
|
Print a short usage summary and exit.
|
||||||
|
.SH CONFIGURATION
|
||||||
|
.B sirc
|
||||||
|
reads its configuration from
|
||||||
|
.I ~/.sirc
|
||||||
|
or
|
||||||
|
.I ~/.config/sirc/config
|
||||||
|
(first found wins).
|
||||||
|
Command-line flags always override config file values.
|
||||||
|
.PP
|
||||||
|
The file uses
|
||||||
|
.B key = value
|
||||||
|
pairs.
|
||||||
|
Lines beginning with
|
||||||
|
.B #
|
||||||
|
are comments.
|
||||||
|
.PP
|
||||||
|
.B Multiple servers
|
||||||
|
are configured with
|
||||||
|
.B [server]
|
||||||
|
section blocks.
|
||||||
|
Each block defines one independent connection.
|
||||||
|
All configured servers connect simultaneously on startup.
|
||||||
|
Global keys placed before any
|
||||||
|
.B [server]
|
||||||
|
block apply as defaults to all servers.
|
||||||
|
.SS Global keys
|
||||||
|
.TP
|
||||||
|
.B nick
|
||||||
|
Default nickname inherited by all servers.
|
||||||
|
.TP
|
||||||
|
.B ignore
|
||||||
|
Comma-separated list of nicks to ignore globally.
|
||||||
|
.SS Per-server keys
|
||||||
|
.TP
|
||||||
|
.B host
|
||||||
|
Server hostname.
|
||||||
|
.TP
|
||||||
|
.B port
|
||||||
|
Port number.
|
||||||
|
.TP
|
||||||
|
.B nick
|
||||||
|
Nickname for this server (overrides the global default).
|
||||||
|
.TP
|
||||||
|
.B channel
|
||||||
|
Comma-separated channels to auto-join on connect.
|
||||||
|
.TP
|
||||||
|
.B tls
|
||||||
|
.BR true " or " false .
|
||||||
|
.TP
|
||||||
|
.B sasl_user
|
||||||
|
SASL PLAIN username.
|
||||||
|
.TP
|
||||||
|
.B sasl_pass
|
||||||
|
SASL PLAIN password.
|
||||||
|
.SS Example configuration
|
||||||
|
.PP
|
||||||
|
.nf
|
||||||
|
nick = kky
|
||||||
|
ignore = badbot,spammer
|
||||||
|
|
||||||
|
[server]
|
||||||
|
host = irc.libera.chat
|
||||||
|
port = 6697
|
||||||
|
tls = true
|
||||||
|
channel = #python,#linux
|
||||||
|
sasl_user = kky
|
||||||
|
sasl_pass = hunter2
|
||||||
|
|
||||||
|
[server]
|
||||||
|
host = irc.oftc.net
|
||||||
|
port = 6697
|
||||||
|
tls = true
|
||||||
|
channel = #debian
|
||||||
|
|
||||||
|
[server]
|
||||||
|
host = irc.rizon.net
|
||||||
|
port = 6667
|
||||||
|
tls = false
|
||||||
|
nick = kky_rizon
|
||||||
|
channel = #rice
|
||||||
|
.fi
|
||||||
|
.SH COMMANDS
|
||||||
|
All commands are entered in the input bar and begin with
|
||||||
|
.BR / .
|
||||||
|
Commands act on the current server (the server of the active channel).
|
||||||
|
.SS Messaging
|
||||||
|
.TP
|
||||||
|
.BI /msg " nick text"
|
||||||
|
Send a private message.
|
||||||
|
Opens a dedicated buffer for the conversation.
|
||||||
|
.TP
|
||||||
|
.BI /notice " target text"
|
||||||
|
Send a NOTICE.
|
||||||
|
.TP
|
||||||
|
.BI /me " text"
|
||||||
|
Send a CTCP ACTION message
|
||||||
|
.RI "( " "* nick text" " )."
|
||||||
|
.TP
|
||||||
|
.BI /ctcp " nick command"
|
||||||
|
Send a raw CTCP request.
|
||||||
|
.SS Channels
|
||||||
|
.TP
|
||||||
|
.BI /join " [#chan]"
|
||||||
|
Join a channel.
|
||||||
|
.TP
|
||||||
|
.BI /part " [#chan]"
|
||||||
|
Leave a channel.
|
||||||
|
Defaults to the current channel.
|
||||||
|
.TP
|
||||||
|
.BI /cycle " [#chan]"
|
||||||
|
Part and immediately rejoin a channel.
|
||||||
|
.TP
|
||||||
|
.BI /names " [#chan]"
|
||||||
|
Request the user list for a channel.
|
||||||
|
.TP
|
||||||
|
.BI /topic " [text]"
|
||||||
|
With no argument, display the current topic.
|
||||||
|
With an argument, set a new topic.
|
||||||
|
.TP
|
||||||
|
.BI /invite " nick [#chan]"
|
||||||
|
Invite a user to a channel.
|
||||||
|
Defaults to the current channel.
|
||||||
|
.TP
|
||||||
|
.BI /kick " nick [reason]"
|
||||||
|
Kick a user from the current channel.
|
||||||
|
.TP
|
||||||
|
.BI /mode " [target] [modes]"
|
||||||
|
Get or set channel or user modes.
|
||||||
|
.SS Users
|
||||||
|
.TP
|
||||||
|
.B /nick
|
||||||
|
Display your current nickname.
|
||||||
|
.TP
|
||||||
|
.BI /nick " newnick"
|
||||||
|
Request a nickname change.
|
||||||
|
.TP
|
||||||
|
.BI /whois " nick"
|
||||||
|
Perform a WHOIS lookup.
|
||||||
|
Results appear in the server status buffer.
|
||||||
|
.TP
|
||||||
|
.BI /who " [target]"
|
||||||
|
Send a WHO query for a channel or nick.
|
||||||
|
.TP
|
||||||
|
.BI /away " [message]"
|
||||||
|
Set an away message.
|
||||||
|
With no argument, clears away status (same as
|
||||||
|
.BR /back ).
|
||||||
|
.TP
|
||||||
|
.B /back
|
||||||
|
Clear away status.
|
||||||
|
.TP
|
||||||
|
.BI /ignore " [nick]"
|
||||||
|
Add a nick to the ignore list.
|
||||||
|
With no argument, lists all ignored nicks.
|
||||||
|
Ignored nicks' messages are silently dropped.
|
||||||
|
.TP
|
||||||
|
.BI /unignore " nick"
|
||||||
|
Remove a nick from the ignore list.
|
||||||
|
.SS Server
|
||||||
|
.TP
|
||||||
|
.BI /list " [pattern]"
|
||||||
|
Request a list of channels on the current server.
|
||||||
|
Results appear in the status buffer.
|
||||||
|
.TP
|
||||||
|
.BI /raw " line"
|
||||||
|
Send a raw IRC line directly to the server.
|
||||||
|
Alias:
|
||||||
|
.BR /quote .
|
||||||
|
.TP
|
||||||
|
.BI /server " host [port]"
|
||||||
|
Connect to an additional server at runtime.
|
||||||
|
Inherits the current nick.
|
||||||
|
.TP
|
||||||
|
.B /connect
|
||||||
|
Reconnect the current server.
|
||||||
|
.TP
|
||||||
|
.BI /quit " [message]"
|
||||||
|
Disconnect all servers and exit.
|
||||||
|
.SS UI
|
||||||
|
.TP
|
||||||
|
.B /clear
|
||||||
|
Clear the scrollback of the current channel.
|
||||||
|
.TP
|
||||||
|
.B /help
|
||||||
|
Print the command reference to the status buffer.
|
||||||
|
.SH KEYS
|
||||||
|
.TP
|
||||||
|
.B Tab
|
||||||
|
Nick completion.
|
||||||
|
Matches the word before the cursor against the current channel's user list.
|
||||||
|
Repeated Tab cycles through matches.
|
||||||
|
At the start of a line the completed nick is followed by
|
||||||
|
.BR ": " .
|
||||||
|
.TP
|
||||||
|
.BR Ctrl\-N
|
||||||
|
Switch to the next channel in visual order.
|
||||||
|
.TP
|
||||||
|
.BR Ctrl\-P
|
||||||
|
Switch to the previous channel in visual order.
|
||||||
|
.TP
|
||||||
|
.BR PgUp
|
||||||
|
Scroll the chat area up.
|
||||||
|
.TP
|
||||||
|
.BR PgDn
|
||||||
|
Scroll the chat area down.
|
||||||
|
.TP
|
||||||
|
.BR Ctrl\-W
|
||||||
|
Delete the word to the left of the cursor.
|
||||||
|
.TP
|
||||||
|
.BR Up / Down
|
||||||
|
Step through the input history.
|
||||||
|
.TP
|
||||||
|
.BR Left / Right
|
||||||
|
Move the cursor within the input line.
|
||||||
|
.TP
|
||||||
|
.BR Home / End
|
||||||
|
Jump to the start or end of the input line.
|
||||||
|
.TP
|
||||||
|
.BR Delete
|
||||||
|
Delete the character under the cursor.
|
||||||
|
.SH LAYOUT
|
||||||
|
.nf
|
||||||
|
+------------------+------------------------------------------+----------------+
|
||||||
|
| CHANNELS | topic (or blank) | USERS (n) |
|
||||||
|
| +------------------------------------------+ |
|
||||||
|
| irc.libera.chat | 12:34 -> alice joined | @alice |
|
||||||
|
| *status* | 12:34 <kky> hello | +bob |
|
||||||
|
| > #python | 12:34 <alice> hey! | charlie |
|
||||||
|
| + #linux | | |
|
||||||
|
| | | |
|
||||||
|
| irc.oftc.net | > _ | |
|
||||||
|
| *status* | | |
|
||||||
|
| #debian | | |
|
||||||
|
+------------------+------------------------------------------+----------------+
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
.B Header bar
|
||||||
|
.RS
|
||||||
|
Displays the topic of the active channel, starting from the left edge of the
|
||||||
|
chat area.
|
||||||
|
Truncated on the right if too long.
|
||||||
|
Blank when no topic is set.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
.B Channel list (left panel)
|
||||||
|
.RS
|
||||||
|
Channels are grouped under their server's full hostname.
|
||||||
|
A
|
||||||
|
.B ~
|
||||||
|
prefix on the server name indicates a disconnected server.
|
||||||
|
The
|
||||||
|
.B *status*
|
||||||
|
buffer under each server receives system messages and server output.
|
||||||
|
.PP
|
||||||
|
Channel state indicators:
|
||||||
|
.RS
|
||||||
|
.TP
|
||||||
|
.B >
|
||||||
|
Active channel.
|
||||||
|
.TP
|
||||||
|
.B +
|
||||||
|
Unread messages.
|
||||||
|
.TP
|
||||||
|
.B !
|
||||||
|
Unread mention of your nick.
|
||||||
|
.RE
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
.B Chat area (centre panel)
|
||||||
|
.RS
|
||||||
|
Messages use the following colour scheme:
|
||||||
|
.RS
|
||||||
|
.TP
|
||||||
|
.B <nick>
|
||||||
|
Per-nick colour derived from a hash of the nick name (bold).
|
||||||
|
.TP
|
||||||
|
message body
|
||||||
|
Plain white.
|
||||||
|
.TP
|
||||||
|
own messages
|
||||||
|
Yellow bold.
|
||||||
|
.TP
|
||||||
|
mentions
|
||||||
|
Red bold.
|
||||||
|
.TP
|
||||||
|
actions (/me)
|
||||||
|
Magenta italic.
|
||||||
|
.TP
|
||||||
|
join/part/quit
|
||||||
|
Gray (dimmed).
|
||||||
|
.TP
|
||||||
|
URLs
|
||||||
|
Blue underline.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
IRC formatting codes (bold \fB^B\fR, colour \fB^C\fR, italic, underline, reset)
|
||||||
|
are stripped from all text before display.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
.B User list (right panel)
|
||||||
|
.RS
|
||||||
|
Users are sorted by privilege level, then alphabetically within each group.
|
||||||
|
Mode symbols are displayed before the nick:
|
||||||
|
.RS
|
||||||
|
.TP
|
||||||
|
.B ~
|
||||||
|
Founder / owner (red bold).
|
||||||
|
.TP
|
||||||
|
.B &
|
||||||
|
Protected op (red bold).
|
||||||
|
.TP
|
||||||
|
.B @
|
||||||
|
Channel op (red bold).
|
||||||
|
.TP
|
||||||
|
.B %
|
||||||
|
Halfop (yellow bold).
|
||||||
|
.TP
|
||||||
|
.B +
|
||||||
|
Voice (yellow bold).
|
||||||
|
.TP
|
||||||
|
(space)
|
||||||
|
Regular user (white).
|
||||||
|
.RE
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
.B Input bar (bottom)
|
||||||
|
.RS
|
||||||
|
Displays a
|
||||||
|
.B ">\ "
|
||||||
|
prompt followed by the input text and a blinking cursor.
|
||||||
|
.RE
|
||||||
|
.SH FEATURES
|
||||||
|
.TP
|
||||||
|
Multiple simultaneous servers
|
||||||
|
Each server runs in its own thread with an independent nick, channel set,
|
||||||
|
and credentials.
|
||||||
|
.TP
|
||||||
|
TLS
|
||||||
|
Connections are encrypted using OpenSSL with full certificate verification
|
||||||
|
.RB ( SSL_VERIFY_PEER ).
|
||||||
|
.TP
|
||||||
|
SASL PLAIN
|
||||||
|
Per-server authentication before nick registration.
|
||||||
|
Negotiated via
|
||||||
|
.BR "CAP REQ :sasl" .
|
||||||
|
.TP
|
||||||
|
Auto-reconnect
|
||||||
|
On disconnect,
|
||||||
|
.B sirc
|
||||||
|
waits five seconds then reconnects and rejoins all open channels.
|
||||||
|
.TP
|
||||||
|
Per-nick colours
|
||||||
|
Each nick is assigned a consistent colour derived from a djb2 hash of the
|
||||||
|
nick string, used in both the chat area and the user list.
|
||||||
|
.TP
|
||||||
|
IRC formatting
|
||||||
|
All mIRC/IRC formatting codes are stripped from incoming text before it is
|
||||||
|
stored or displayed.
|
||||||
|
.TP
|
||||||
|
Topic display
|
||||||
|
The current channel topic is shown in the header bar and updated live
|
||||||
|
whenever a
|
||||||
|
.B TOPIC
|
||||||
|
message is received.
|
||||||
|
.TP
|
||||||
|
URL highlighting
|
||||||
|
Strings beginning with
|
||||||
|
.BR http:// ,
|
||||||
|
.BR https:// ,
|
||||||
|
or
|
||||||
|
.B www.\&
|
||||||
|
are rendered with a blue underline.
|
||||||
|
.TP
|
||||||
|
Nick completion
|
||||||
|
Tab-completion matches the typed prefix against the current channel's user
|
||||||
|
list.
|
||||||
|
Cycling with repeated Tab wraps around.
|
||||||
|
.TP
|
||||||
|
Ring-buffer scrollback
|
||||||
|
Each channel stores the last 500 lines in a fixed-size ring buffer with O(1)
|
||||||
|
insertion.
|
||||||
|
.TP
|
||||||
|
Global ignore list
|
||||||
|
Ignored nicks are dropped across all servers.
|
||||||
|
The list persists for the session and can be pre-populated in the config file.
|
||||||
|
.SH LIMITS
|
||||||
|
.TS
|
||||||
|
l l.
|
||||||
|
Max servers 8
|
||||||
|
Max channels (total) 128
|
||||||
|
Max users per channel 512
|
||||||
|
Scrollback per channel 500 lines
|
||||||
|
Input line length 480 characters
|
||||||
|
Input history 256 lines
|
||||||
|
Ignore list 64 nicks
|
||||||
|
Auto-join channels per server 16
|
||||||
|
.TE
|
||||||
|
.SH FILES
|
||||||
|
.TP
|
||||||
|
.I ~/.sirc
|
||||||
|
Primary configuration file.
|
||||||
|
.TP
|
||||||
|
.I ~/.config/sirc/config
|
||||||
|
Alternative configuration file location.
|
||||||
|
Consulted if
|
||||||
|
.I ~/.sirc
|
||||||
|
does not exist.
|
||||||
|
.SH EXAMPLES
|
||||||
|
Connect to Libera.Chat with TLS and SASL:
|
||||||
|
.PP
|
||||||
|
.nf
|
||||||
|
sirc --host irc.libera.chat --nick kky --sasl-user kky --sasl-pass hunter2
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
Connect without TLS on the standard plain-text port:
|
||||||
|
.PP
|
||||||
|
.nf
|
||||||
|
sirc --host irc.libera.chat --port 6667 --no-tls --nick kky
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
Join multiple channels on connect:
|
||||||
|
.PP
|
||||||
|
.nf
|
||||||
|
sirc --host irc.libera.chat --nick kky --channel '#python,#linux'
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
Use a custom configuration file:
|
||||||
|
.PP
|
||||||
|
.nf
|
||||||
|
sirc --config ~/work/irc.conf
|
||||||
|
.fi
|
||||||
|
.SH BUILDING
|
||||||
|
.nf
|
||||||
|
make
|
||||||
|
make install # installs to ~/.local/bin/sirc
|
||||||
|
PREFIX=/usr/local make install
|
||||||
|
.fi
|
||||||
|
.SH SEE ALSO
|
||||||
|
.BR irssi (1),
|
||||||
|
.BR weechat (1),
|
||||||
|
.BR nc (1),
|
||||||
|
.BR openssl (1)
|
||||||
|
.SH AUTHORS
|
||||||
|
Emmett and Claude.
|
||||||
|
.SH LICENSE
|
||||||
|
MIT
|
||||||
Reference in New Issue
Block a user