catgirl/README.7

.\" To view this file, run: man ./README.7
.Dd February 19, 2022
.Dt README 7
.Os "Causal Agency"
.
.Sh NAME
.Nm catgirl
.Nd IRC client
.
.Sh DESCRIPTION
.Xr catgirl 1
is a TLS-only terminal IRC client.
.
.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 edit.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 "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
.It Pa window.c
window management
.It Pa handle.c
IRC message handling
.It Pa command.c
input command handling
.It Pa buffer.c
line wrapping
.It Pa edit.c
line editing
.It Pa complete.c
tab complete
.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 Bug
.%T IRC Suite
.%U https://text.causal.agency/010-irc-suite.txt
.%D June 19, 2020
.Re
.
.\" To view this file, run: man ./README.7
Encourage packagers to patch in text macros Maybe no one will ever do it but I think it's a fun idea. 2021-06-24 19:04:37 +00:00			`.\" To view this file, run: man ./README.7`
Factor out window management to window.c 2022-02-19 23:28:45 +00:00			`.Dd February 19, 2022`
Add README Still missing: build requirements and instructions. 2020-02-11 07:31:08 +00:00			`.Dt README 7`
			`.Os "Causal Agency"`
			`.`
			`.Sh NAME`
			`.Nm catgirl`
			`.Nd IRC client`
			`.`
			`.Sh DESCRIPTION`
Add INSTALLING section to README 2020-02-11 07:41:20 +00:00			`.Xr catgirl 1`
			`is a TLS-only terminal IRC client.`
Add README Still missing: build requirements and instructions. 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.`
Fix README typo How long has this been here? 2021-03-18 20:15:06 +00:00			`Commas are inserted between multiple nicks.`
Add README Still missing: build requirements and instructions. 2020-02-11 07:31:08 +00:00			`.It`
Add split scrolling to README 2020-04-06 20:45:20 +00:00			`Prompt:`
Add README Still missing: build requirements and instructions. 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`
Add split scrolling to README 2020-04-06 20:45:20 +00:00			`Split scroll:`
			`keeps the latest messages in view while scrolling.`
Add README Still missing: build requirements and instructions. 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`
Add split scrolling to README 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`
Add topic diffing to notable features 2020-11-11 18:27:22 +00:00			`Topic diffing:`
			`the modified portion`
			`of a channel topic change`
			`is highlighted.`
			`.It`
Update features list 2020-03-31 23:08:58 +00:00			`Ignore:`
			`visibility of filtered messages`
			`can be toggled.`
Move security to the features list The restrict option now enables real sandboxing on the two main target systems. 2021-06-28 15:55:07 +00:00			`.It`
			`Security:`
			`on`
			`.Fx`
			`and`
			`.Ox ,`
			`the`
			`.Cm restrict`
Attempt to keep "security" in README accurate It's a short summary trying to cover different systems... 2021-07-04 17:22:55 +00:00			`option enables tight sandboxing.`
			`Sandboxing is always used on`
			`.Ox .`
Add README Still missing: build requirements and instructions. 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`
Update features list 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`
Add protocol coverage to non-features list I don't feel that 100% protocol extension support should at all be a goal. 2021-01-25 19:45:30 +00:00			`Protocol coverage:`
			`IRCv3 extensions are implemented only`
			`where they contribute to`
			`the intended user experience.`
			`.It`
Add README Still missing: build requirements and instructions. 2020-02-11 07:31:08 +00:00			`Cleartext IRC:`
			`TLS is now ubiquitous`
			`and certificates are easy to obtain.`
			`.El`
			`.`
Add INSTALLING section to README 2020-02-11 07:41:20 +00:00			`.Sh INSTALLING`
			`.Nm`
Mention LibreTLS in install instructions 2020-08-04 18:38:23 +00:00			`requires ncurses and`
			`.Sy libtls ,`
			`provided by either`
			`.Lk https://git.causal.agency/libretls/about LibreTLS`
Say for instead of with 2020-08-05 16:51:44 +00:00			`(for OpenSSL)`
Mention LibreTLS in install instructions 2020-08-04 18:38:23 +00:00			`or by LibreSSL.`
Move security to the features list The restrict option now enables real sandboxing on the two main target systems. 2021-06-28 15:55:07 +00:00			`It targets`
			`.Fx ,`
			`.Ox ,`
			`macOS`
			`and Linux.`
Add Repology links to README LibreTLS in particular is gaining traction in packaging, so point to Repology pages to make users' lives easier. 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 .`
Move mention of pledge(2) and unveil(2) to README The manual is the wrong place to document platform support. 2021-01-25 18:53:55 +00:00			`.`
Add INSTALLING section to README 2020-02-11 07:41:20 +00:00			`.Bd -literal -offset indent`
Refer to long option names, prefix commands with $ 2021-12-12 01:51:49 +00:00			`$ ./configure`
			`$ make all`
			`# make install`
Add INSTALLING section to README 2020-02-11 07:41:20 +00:00			`.Ed`
			`.`
Add note about setting PKG_CONFIG_PATH 2020-02-11 23:33:19 +00:00			`.Pp`
Encourage packagers to patch in text macros Maybe no one will ever do it but I think it's a fun idea. 2021-06-24 19:04:37 +00:00			`Packagers are encouraged`
			`to patch in their own text macros in`
			`.Pa edit.c .`
			`.`
			`.Pp`
Mention LibreTLS in install instructions 2020-08-04 18:38:23 +00:00			`If installing`
			`.Sy libtls`
			`manually to`
Add note about building LibreSSL manually 2020-04-01 14:25:04 +00:00			`.Pa /usr/local ,`
Mention LibreTLS in install instructions 2020-08-04 18:38:23 +00:00			`for example,`
			`make sure`
Add note about building LibreSSL manually 2020-04-01 14:25:04 +00:00			`.Pa /usr/local/lib`
Mention LibreTLS in install instructions 2020-08-04 18:38:23 +00:00			`appears in`
Add note about building LibreSSL manually 2020-04-01 14:25:04 +00:00			`.Pa /etc/ld.so.conf`
Mention LibreTLS in install instructions 2020-08-04 18:38:23 +00:00			`or`
			`.Pa /etc/ld.so.conf.d/*`
			`and be sure to run`
Mention running ldconfig after editing /etc/ld.so.conf 2020-04-01 19:07:21 +00:00			`.Xr ldconfig 8`
Mention LibreTLS in install instructions 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`
Refer to long option names, prefix commands with $ 2021-12-12 01:51:49 +00:00			`$ PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./configure`
Mention LibreTLS in install instructions 2020-08-04 18:38:23 +00:00			`.Ed`
Add note about building LibreSSL manually 2020-04-01 14:25:04 +00:00			`.`
			`.Pp`
Add sandman wrapper 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`
Move sandman build to scripts/Makefile 2022-02-13 01:19:18 +00:00			`$ make -C scripts sandman`
			`# make -C scripts install`
Add sandman wrapper 2020-02-13 02:31:09 +00:00			`.Ed`
			`.`
Add README Still missing: build requirements and instructions. 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`
Factor out window management to window.c 2022-02-19 23:28:45 +00:00			`.It Pa window.c`
			`window management`
Add README Still missing: build requirements and instructions. 2020-02-11 07:31:08 +00:00			`.It Pa handle.c`
			`IRC message handling`
			`.It Pa command.c`
			`input command handling`
Factor buffer out of ui In preparation for doing line wrapping outside of ncurses. 2020-09-02 00:35:17 +00:00			`.It Pa buffer.c`
			`line wrapping`
Add README Still missing: build requirements and instructions. 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`
Rename ignore code to filter 2021-01-16 18:30:59 +00:00			`.It Pa filter.c`
Add /ignore message filtering patterns 2020-03-31 18:30:42 +00:00			`message filtering`
Add logging functions The mkdir dance is a bit awkward... 2020-03-25 22:56:09 +00:00			`.It Pa log.c`
			`chat logging`
Add README Still missing: build requirements and instructions. 2020-02-11 07:31:08 +00:00			`.It Pa config.c`
			`configuration parsing`
			`.It Pa xdg.c`
			`XDG base directories`
			`.El`
			`.`
Document scripts in README 2020-02-13 01:16:51 +00:00			`.Pp`
			`.Bl -tag -width "scripts/notify-send.scpt" -compact`
Add example tmux(1) config Spawn one catgirl per network and handle reconnects through tmux, no extra tool required. 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`
Add sandman wrapper 2020-02-13 02:31:09 +00:00			`.It Pa scripts/sandman.m`
			`sleep/wake wrapper for macOS`
Document scripts in README 2020-02-13 01:16:51 +00:00			`.It Pa scripts/notify-send.scpt`
			`.Xr notify-send 1`
			`in AppleScript`
chroot: Factor out and add OpenBSD build 2021-09-27 19:16:45 +00:00			`.It Pa scripts/build-chroot.sh`
			`chroot builder for`
			`.Ox`
			`and`
			`.Fx`
Document scripts in README 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`
			`.`
Add README Still missing: build requirements and instructions. 2020-02-11 07:31:08 +00:00			`.Sh CONTRIBUTING`
			`The upstream URL of this project is`
			`.Aq Lk https://git.causal.agency/catgirl .`
Update email addresses 2020-05-05 21:55:29 +00:00			`Contributions in any form can be sent to`
			`.Aq Mt list+catgirl@causal.agency .`
Add README Still missing: build requirements and instructions. 2020-02-11 07:31:08 +00:00			`For sending patches by email, see`
			`.Aq Lk https://git-send-email.io .`
Add mailing list archive to README 2021-06-17 16:11:55 +00:00			`Mailing list archives are available at`
			`.Aq Lk https://causal.agency/list/catgirl.html .`
Add README Still missing: build requirements and instructions. 2020-02-11 07:31:08 +00:00			`.`
Add donation link to README 2021-02-09 01:27:49 +00:00			`.Pp`
			`Monetary contributions can be`
			`.Lk https://liberapay.com/june/donate "donated via Liberapay" .`
			`.`
Add README Still missing: build requirements and instructions. 2020-02-11 07:31:08 +00:00			`.Sh SEE ALSO`
			`.Xr catgirl 1`
Add link to "IRC Suite" post in README 2020-07-08 20:59:51 +00:00			`.`
Add pounce to README's SEE ALSO 2020-03-31 23:13:24 +00:00			`.Pp`
			`IRC bouncer:`
			`.Lk https://git.causal.agency/pounce "pounce"`
Add notes on how to view README.7 I'm feeling generous :) 2020-03-31 23:17:09 +00:00			`.`
Add link to "IRC Suite" post in README 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`
			`.`
Add notes on how to view README.7 I'm feeling generous :) 2020-03-31 23:17:09 +00:00			`.\" To view this file, run: man ./README.7`