274 lines
4.7 KiB
Groff
274 lines
4.7 KiB
Groff
.\" To view this file: $ man ./README.7
|
|
.Dd July 30, 2022
|
|
.Dt README 7
|
|
.Os "Causal Agency"
|
|
.
|
|
.Sh NAME
|
|
.Nm catgirl
|
|
.Nd IRC client
|
|
.
|
|
.Sh DESCRIPTION
|
|
.Xr catgirl 1
|
|
is a terminal IRC client.
|
|
.
|
|
.Pp
|
|
Screenshot:
|
|
imagine,
|
|
if you will,
|
|
text on a screen,
|
|
next to names
|
|
in a selection of colours.
|
|
.
|
|
.Ss Notable Features
|
|
.Bl -bullet
|
|
.It
|
|
Tab complete:
|
|
most recently seen or mentioned nicks
|
|
are completed first.
|
|
Commas are inserted between multiple nicks.
|
|
.It
|
|
Prompt:
|
|
the prompt clearly shows whether input
|
|
will be interpreted as a command
|
|
or sent as a message.
|
|
.It
|
|
Split scroll:
|
|
keeps the latest messages in view while scrolling.
|
|
.It
|
|
URL detection:
|
|
recent URLs from a particular user
|
|
or matching a substring
|
|
can be opened or copied.
|
|
.It
|
|
Nick coloring:
|
|
color generation based on usernames
|
|
remains stable across nick changes.
|
|
Mentions of users in messages are colored.
|
|
.It
|
|
Topic diffing:
|
|
the modified portion
|
|
of a channel topic change
|
|
is highlighted.
|
|
.It
|
|
Ignore:
|
|
visibility of filtered messages
|
|
can be toggled.
|
|
.It
|
|
Security:
|
|
on
|
|
.Fx
|
|
and
|
|
.Ox ,
|
|
the
|
|
.Cm restrict
|
|
option enables tight sandboxing.
|
|
Sandboxing is always used on
|
|
.Ox .
|
|
.El
|
|
.
|
|
.Ss Non-features
|
|
.Bl -bullet
|
|
.It
|
|
Dynamic configuration:
|
|
all configuration happens
|
|
in a simple text file
|
|
or on the command line.
|
|
.It
|
|
Multi-network:
|
|
a terminal multiplexer such as
|
|
.Xr screen 1
|
|
or
|
|
.Xr tmux 1
|
|
(or just your regular terminal emulator tabs)
|
|
can be used to connect
|
|
.Nm
|
|
to multiple networks.
|
|
.It
|
|
Reconnection:
|
|
when the connection to the server is lost,
|
|
.Nm
|
|
exits.
|
|
It can be run in a loop
|
|
or connected to a bouncer,
|
|
such as
|
|
.Lk https://git.causal.agency/pounce "pounce" .
|
|
.It
|
|
CTCP:
|
|
apart from
|
|
.Sy ACTION ,
|
|
this protocol is useless at best
|
|
and enables abuse at worst.
|
|
.It
|
|
Protocol coverage:
|
|
IRCv3 extensions are implemented only
|
|
where they contribute to
|
|
the intended user experience.
|
|
.It
|
|
Cleartext IRC:
|
|
TLS is now ubiquitous
|
|
and certificates are easy to obtain.
|
|
.El
|
|
.
|
|
.Sh INSTALLING
|
|
.Nm
|
|
requires ncurses and
|
|
.Sy libtls ,
|
|
provided by either
|
|
.Lk https://git.causal.agency/libretls/about LibreTLS
|
|
(for OpenSSL)
|
|
or by LibreSSL.
|
|
It targets
|
|
.Fx ,
|
|
.Ox ,
|
|
macOS
|
|
and Linux.
|
|
.Nm
|
|
and
|
|
.Sy libtls
|
|
may be packaged for your system.
|
|
Check the Repology pages for
|
|
.Lk https://repology.org/project/catgirl/versions catgirl
|
|
and
|
|
.Lk https://repology.org/project/libretls/versions libretls .
|
|
.
|
|
.Bd -literal -offset indent
|
|
$ ./configure
|
|
$ make all
|
|
# make install
|
|
.Ed
|
|
.
|
|
.Pp
|
|
Packagers are encouraged
|
|
to patch in their own text macros in
|
|
.Pa input.c .
|
|
.
|
|
.Pp
|
|
If installing
|
|
.Sy libtls
|
|
manually to
|
|
.Pa /usr/local ,
|
|
for example,
|
|
make sure
|
|
.Pa /usr/local/lib
|
|
appears in
|
|
.Pa /etc/ld.so.conf
|
|
or
|
|
.Pa /etc/ld.so.conf.d/*
|
|
and be sure to run
|
|
.Xr ldconfig 8
|
|
once the library is installed.
|
|
Set
|
|
.Ev PKG_CONFIG_PATH
|
|
for
|
|
.Nm ./configure
|
|
to find it.
|
|
.Bd -literal -offset indent
|
|
$ PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./configure
|
|
.Ed
|
|
.
|
|
.Pp
|
|
The
|
|
.Nm sandman
|
|
wrapper is provided for macOS
|
|
to stop and start
|
|
.Nm
|
|
on system sleep and wake.
|
|
Install it as follows:
|
|
.Bd -literal -offset indent
|
|
$ make -C scripts sandman
|
|
# make -C scripts install
|
|
.Ed
|
|
.
|
|
.Sh FILES
|
|
.Bl -tag -width "command.c" -compact
|
|
.It Pa chat.h
|
|
global state and declarations
|
|
.It Pa chat.c
|
|
startup and event loop
|
|
.It Pa irc.c
|
|
IRC connection and parsing
|
|
.It Pa ui.c
|
|
curses interface
|
|
.It Pa window.c
|
|
window management
|
|
.It Pa input.c
|
|
input handling
|
|
.It Pa handle.c
|
|
IRC message handling
|
|
.It Pa command.c
|
|
command handling
|
|
.It Pa buffer.c
|
|
line wrapping
|
|
.It Pa edit.c
|
|
line editing
|
|
.It Pa cache.c
|
|
ordered cache
|
|
.It Pa url.c
|
|
URL detection
|
|
.It Pa filter.c
|
|
message filtering
|
|
.It Pa log.c
|
|
chat logging
|
|
.It Pa config.c
|
|
configuration parsing
|
|
.It Pa xdg.c
|
|
XDG base directories
|
|
.El
|
|
.
|
|
.Pp
|
|
.Bl -tag -width "scripts/notify-send.scpt" -compact
|
|
.It Pa scripts/chat.tmux.conf
|
|
example
|
|
.Xr tmux 1
|
|
configuration for multiple networks
|
|
and automatic reconnects
|
|
.It Pa scripts/sandman.m
|
|
sleep/wake wrapper for macOS
|
|
.It Pa scripts/notify-send.scpt
|
|
.Xr notify-send 1
|
|
in AppleScript
|
|
.It Pa scripts/build-chroot.sh
|
|
chroot builder for
|
|
.Ox
|
|
and
|
|
.Fx
|
|
.It Pa scripts/chroot-prompt.sh
|
|
name prompt wrapper for chroot
|
|
.It Pa scripts/chroot-man.sh
|
|
.Xr man 1
|
|
implementation for chroot
|
|
.It Pa scripts/sshd_config
|
|
.Xr sshd 8
|
|
configuration for public chroot
|
|
.El
|
|
.
|
|
.Sh CONTRIBUTING
|
|
The upstream URL of this project is
|
|
.Aq Lk https://git.causal.agency/catgirl .
|
|
Contributions in any form can be sent to
|
|
.Aq Mt list+catgirl@causal.agency .
|
|
For sending patches by email, see
|
|
.Aq Lk https://git-send-email.io .
|
|
Mailing list archives are available at
|
|
.Aq Lk https://causal.agency/list/catgirl.html .
|
|
.
|
|
.Pp
|
|
Monetary contributions can be
|
|
.Lk https://liberapay.com/june/donate "donated via Liberapay" .
|
|
.
|
|
.Sh SEE ALSO
|
|
.Xr catgirl 1
|
|
.
|
|
.Pp
|
|
IRC bouncer:
|
|
.Lk https://git.causal.agency/pounce "pounce"
|
|
.
|
|
.Rs
|
|
.%A June McEnroe
|
|
.%T IRC Suite
|
|
.%U https://text.causal.agency/010-irc-suite.txt
|
|
.%D June 19, 2020
|
|
.Re
|
|
.
|
|
.\" To view this file: $ man ./README.7
|