2021-06-24 19:04:37 +00:00
|
|
|
.\" To view this file, run: man ./README.7
|
2022-03-31 17:21:33 +00:00
|
|
|
.Dd March 31, 2022
|
2020-02-11 07:31:08 +00:00
|
|
|
.Dt README 7
|
|
|
|
|
.Os "Causal Agency"
|
|
|
|
|
.
|
|
|
|
|
.Sh NAME
|
|
|
|
|
.Nm catgirl
|
|
|
|
|
.Nd IRC client
|
|
|
|
|
.
|
|
|
|
|
.Sh DESCRIPTION
|
2020-02-11 07:41:20 +00:00
|
|
|
.Xr catgirl 1
|
|
|
|
|
is a TLS-only terminal IRC client.
|
2020-02-11 07:31:08 +00:00
|
|
|
.
|
2022-03-31 17:21:33 +00:00
|
|
|
.Pp
|
|
|
|
|
Screenshot:
|
|
|
|
|
imagine,
|
|
|
|
|
if you will,
|
|
|
|
|
text on a screen,
|
|
|
|
|
next to names
|
|
|
|
|
in a selection of colours.
|
|
|
|
|
.
|
2020-02-11 07:31:08 +00:00
|
|
|
.Ss Notable Features
|
|
|
|
|
.Bl -bullet
|
|
|
|
|
.It
|
|
|
|
|
Tab complete:
|
|
|
|
|
most recently seen or mentioned nicks
|
|
|
|
|
are completed first.
|
2021-03-18 20:15:06 +00:00
|
|
|
Commas are inserted between multiple nicks.
|
2020-02-11 07:31:08 +00:00
|
|
|
.It
|
2020-04-06 20:45:20 +00:00
|
|
|
Prompt:
|
2020-02-11 07:31:08 +00:00
|
|
|
the prompt clearly shows whether input
|
|
|
|
|
will be interpreted as a command
|
|
|
|
|
or sent as a message.
|
|
|
|
|
.It
|
2020-04-06 20:45:20 +00:00
|
|
|
Split scroll:
|
|
|
|
|
keeps the latest messages in view while scrolling.
|
2020-02-11 07:31:08 +00:00
|
|
|
.It
|
|
|
|
|
URL detection:
|
|
|
|
|
recent URLs from a particular user
|
|
|
|
|
or matching a substring
|
|
|
|
|
can be opened or copied.
|
|
|
|
|
.It
|
2020-04-06 20:45:20 +00:00
|
|
|
Nick coloring:
|
|
|
|
|
color generation based on usernames
|
|
|
|
|
remains stable across nick changes.
|
|
|
|
|
Mentions of users in messages are colored.
|
|
|
|
|
.It
|
2020-11-11 18:27:22 +00:00
|
|
|
Topic diffing:
|
|
|
|
|
the modified portion
|
|
|
|
|
of a channel topic change
|
|
|
|
|
is highlighted.
|
|
|
|
|
.It
|
2020-03-31 23:08:58 +00:00
|
|
|
Ignore:
|
|
|
|
|
visibility of filtered messages
|
|
|
|
|
can be toggled.
|
2021-06-28 15:55:07 +00:00
|
|
|
.It
|
|
|
|
|
Security:
|
|
|
|
|
on
|
|
|
|
|
.Fx
|
|
|
|
|
and
|
|
|
|
|
.Ox ,
|
|
|
|
|
the
|
|
|
|
|
.Cm restrict
|
2021-07-04 17:22:55 +00:00
|
|
|
option enables tight sandboxing.
|
|
|
|
|
Sandboxing is always used on
|
|
|
|
|
.Ox .
|
2020-02-11 07:31:08 +00:00
|
|
|
.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
|
2020-03-31 23:08:58 +00:00
|
|
|
CTCP:
|
|
|
|
|
apart from
|
|
|
|
|
.Sy ACTION ,
|
|
|
|
|
this protocol is useless at best
|
|
|
|
|
and enables abuse at worst.
|
|
|
|
|
.It
|
2021-01-25 19:45:30 +00:00
|
|
|
Protocol coverage:
|
|
|
|
|
IRCv3 extensions are implemented only
|
|
|
|
|
where they contribute to
|
|
|
|
|
the intended user experience.
|
|
|
|
|
.It
|
2020-02-11 07:31:08 +00:00
|
|
|
Cleartext IRC:
|
|
|
|
|
TLS is now ubiquitous
|
|
|
|
|
and certificates are easy to obtain.
|
|
|
|
|
.El
|
|
|
|
|
.
|
2020-02-11 07:41:20 +00:00
|
|
|
.Sh INSTALLING
|
|
|
|
|
.Nm
|
2020-08-04 18:38:23 +00:00
|
|
|
requires ncurses and
|
|
|
|
|
.Sy libtls ,
|
|
|
|
|
provided by either
|
|
|
|
|
.Lk https://git.causal.agency/libretls/about LibreTLS
|
2020-08-05 16:51:44 +00:00
|
|
|
(for OpenSSL)
|
2020-08-04 18:38:23 +00:00
|
|
|
or by LibreSSL.
|
2021-06-28 15:55:07 +00:00
|
|
|
It targets
|
|
|
|
|
.Fx ,
|
|
|
|
|
.Ox ,
|
|
|
|
|
macOS
|
|
|
|
|
and Linux.
|
2021-01-28 21:10:05 +00:00
|
|
|
.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 .
|
2021-01-25 18:53:55 +00:00
|
|
|
.
|
2020-02-11 07:41:20 +00:00
|
|
|
.Bd -literal -offset indent
|
2021-12-12 01:51:49 +00:00
|
|
|
$ ./configure
|
|
|
|
|
$ make all
|
|
|
|
|
# make install
|
2020-02-11 07:41:20 +00:00
|
|
|
.Ed
|
|
|
|
|
.
|
2020-02-11 23:33:19 +00:00
|
|
|
.Pp
|
2021-06-24 19:04:37 +00:00
|
|
|
Packagers are encouraged
|
|
|
|
|
to patch in their own text macros in
|
2022-02-20 01:37:48 +00:00
|
|
|
.Pa input.c .
|
2021-06-24 19:04:37 +00:00
|
|
|
.
|
|
|
|
|
.Pp
|
2020-08-04 18:38:23 +00:00
|
|
|
If installing
|
|
|
|
|
.Sy libtls
|
|
|
|
|
manually to
|
2020-04-01 14:25:04 +00:00
|
|
|
.Pa /usr/local ,
|
2020-08-04 18:38:23 +00:00
|
|
|
for example,
|
|
|
|
|
make sure
|
2020-04-01 14:25:04 +00:00
|
|
|
.Pa /usr/local/lib
|
2020-08-04 18:38:23 +00:00
|
|
|
appears in
|
2020-04-01 14:25:04 +00:00
|
|
|
.Pa /etc/ld.so.conf
|
2020-08-04 18:38:23 +00:00
|
|
|
or
|
|
|
|
|
.Pa /etc/ld.so.conf.d/*
|
|
|
|
|
and be sure to run
|
2020-04-01 19:07:21 +00:00
|
|
|
.Xr ldconfig 8
|
2020-08-04 18:38:23 +00:00
|
|
|
once the library is installed.
|
|
|
|
|
Set
|
|
|
|
|
.Ev PKG_CONFIG_PATH
|
|
|
|
|
for
|
|
|
|
|
.Nm ./configure
|
|
|
|
|
to find it.
|
|
|
|
|
.Bd -literal -offset indent
|
2021-12-12 01:51:49 +00:00
|
|
|
$ PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./configure
|
2020-08-04 18:38:23 +00:00
|
|
|
.Ed
|
2020-04-01 14:25:04 +00:00
|
|
|
.
|
|
|
|
|
.Pp
|
2020-02-13 02:31:09 +00:00
|
|
|
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
|
2022-02-13 01:19:18 +00:00
|
|
|
$ make -C scripts sandman
|
|
|
|
|
# make -C scripts install
|
2020-02-13 02:31:09 +00:00
|
|
|
.Ed
|
|
|
|
|
.
|
2020-02-11 07:31:08 +00:00
|
|
|
.Sh FILES
|
|
|
|
|
.Bl -tag -width "complete.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
|
2022-02-19 23:28:45 +00:00
|
|
|
.It Pa window.c
|
|
|
|
|
window management
|
2022-02-20 01:20:19 +00:00
|
|
|
.It Pa input.c
|
|
|
|
|
input handling
|
2020-02-11 07:31:08 +00:00
|
|
|
.It Pa handle.c
|
|
|
|
|
IRC message handling
|
|
|
|
|
.It Pa command.c
|
2022-02-20 01:20:19 +00:00
|
|
|
command handling
|
2020-09-02 00:35:17 +00:00
|
|
|
.It Pa buffer.c
|
|
|
|
|
line wrapping
|
2020-02-11 07:31:08 +00:00
|
|
|
.It Pa edit.c
|
|
|
|
|
line editing
|
|
|
|
|
.It Pa complete.c
|
|
|
|
|
tab complete
|
|
|
|
|
.It Pa url.c
|
|
|
|
|
URL detection
|
2021-01-16 18:30:59 +00:00
|
|
|
.It Pa filter.c
|
2020-03-31 18:30:42 +00:00
|
|
|
message filtering
|
2020-03-25 22:56:09 +00:00
|
|
|
.It Pa log.c
|
|
|
|
|
chat logging
|
2020-02-11 07:31:08 +00:00
|
|
|
.It Pa config.c
|
|
|
|
|
configuration parsing
|
|
|
|
|
.It Pa xdg.c
|
|
|
|
|
XDG base directories
|
|
|
|
|
.El
|
|
|
|
|
.
|
2020-02-13 01:16:51 +00:00
|
|
|
.Pp
|
|
|
|
|
.Bl -tag -width "scripts/notify-send.scpt" -compact
|
2021-01-18 17:12:45 +00:00
|
|
|
.It Pa scripts/chat.tmux.conf
|
|
|
|
|
example
|
|
|
|
|
.Xr tmux 1
|
|
|
|
|
configuration for multiple networks
|
|
|
|
|
and automatic reconnects
|
2020-02-13 02:31:09 +00:00
|
|
|
.It Pa scripts/sandman.m
|
|
|
|
|
sleep/wake wrapper for macOS
|
2020-02-13 01:16:51 +00:00
|
|
|
.It Pa scripts/notify-send.scpt
|
|
|
|
|
.Xr notify-send 1
|
|
|
|
|
in AppleScript
|
2021-09-27 19:16:45 +00:00
|
|
|
.It Pa scripts/build-chroot.sh
|
|
|
|
|
chroot builder for
|
|
|
|
|
.Ox
|
|
|
|
|
and
|
|
|
|
|
.Fx
|
2020-02-13 01:16:51 +00:00
|
|
|
.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
|
|
|
|
|
.
|
2020-02-11 07:31:08 +00:00
|
|
|
.Sh CONTRIBUTING
|
|
|
|
|
The upstream URL of this project is
|
|
|
|
|
.Aq Lk https://git.causal.agency/catgirl .
|
2020-05-05 21:55:29 +00:00
|
|
|
Contributions in any form can be sent to
|
|
|
|
|
.Aq Mt list+catgirl@causal.agency .
|
2020-02-11 07:31:08 +00:00
|
|
|
For sending patches by email, see
|
|
|
|
|
.Aq Lk https://git-send-email.io .
|
2021-06-17 16:11:55 +00:00
|
|
|
Mailing list archives are available at
|
|
|
|
|
.Aq Lk https://causal.agency/list/catgirl.html .
|
2020-02-11 07:31:08 +00:00
|
|
|
.
|
2021-02-09 01:27:49 +00:00
|
|
|
.Pp
|
|
|
|
|
Monetary contributions can be
|
|
|
|
|
.Lk https://liberapay.com/june/donate "donated via Liberapay" .
|
|
|
|
|
.
|
2020-02-11 07:31:08 +00:00
|
|
|
.Sh SEE ALSO
|
|
|
|
|
.Xr catgirl 1
|
2020-07-08 20:59:51 +00:00
|
|
|
.
|
2020-03-31 23:13:24 +00:00
|
|
|
.Pp
|
|
|
|
|
IRC bouncer:
|
|
|
|
|
.Lk https://git.causal.agency/pounce "pounce"
|
2020-03-31 23:17:09 +00:00
|
|
|
.
|
2020-07-08 20:59:51 +00:00
|
|
|
.Rs
|
|
|
|
|
.%A June Bug
|
|
|
|
|
.%T IRC Suite
|
|
|
|
|
.%U https://text.causal.agency/010-irc-suite.txt
|
|
|
|
|
.%D June 19, 2020
|
|
|
|
|
.Re
|
|
|
|
|
.
|
2020-03-31 23:17:09 +00:00
|
|
|
.\" To view this file, run: man ./README.7
|
