commit de05b3508ece1410a6200e4cb683d7ec1bf8c464
parent 5af6eb7deb0b44c4326d0d9ef9f1b644a4a6c959
Author: emmett1 <me@emmett1.my>
Date: Tue, 31 Mar 2026 07:50:35 +0800
added man page
Diffstat:
| A | sirc.1 | | | 505 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 505 insertions(+), 0 deletions(-)
diff --git a/sirc.1 b/sirc.1
@@ -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
