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