diff options
Diffstat (limited to 'README.7')
| -rw-r--r-- | README.7 | 307 |
1 files changed, 235 insertions, 72 deletions
diff --git a/README.7 b/README.7 index cae56bb..a26d270 100644 --- a/README.7 +++ b/README.7 @@ -1,5 +1,6 @@ -.Dd February 25, 2019 -.Dt CATGIRL 7 +.\" To view this file: $ man ./README.7 +.Dd July 9, 2023 +.Dt README 7 .Os "Causal Agency" . .Sh NAME @@ -7,105 +8,267 @@ .Nd IRC client . .Sh DESCRIPTION -.Nm -is a curses IRC client -originally intended for -use over anonymous SSH. +.Xr catgirl 1 +is a terminal IRC client. . .Pp -It requires LibreSSL -.Pq Fl ltls -and targets -.Fx , -Darwin, -.Nx +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 -GNU/Linux. +.Ox , +the +.Cm restrict +option enables tight sandboxing. +Sandboxing is always used on +.Ox . +.El . -.Sh INSTALL -On platforms other than +.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 , -copy the appropriate file to -.Pa config.mk -and modify as needed. -The default install -.Va PREFIX -is -.Pa ~/.local . +.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 -cp $(uname).mk config.mk -make -make install +$ PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./configure .Ed . -.Ss Darwin -LibreSSL is assumed to be installed with -.Xr brew 1 . +.Pp The -.Xr sandman 1 -wrapper is also installed. -. -.Ss NetBSD -LibreSSL is assumed to be installed with -.Xr pkgsrc 7 . -Due to bugs in -.Nx Ap s -.Xr curses 3 -implementation, -some of the UI is currently broken. -. -.Ss GNU/Linux -LibreSSL is assumed to be manually installed in -.Pa /usr/local -and is statically linked. +.Nm sandman +wrapper is provided for macOS +to stop and start +.Nm +on system sleep and wake. +To enable it, +configure with: +.Bd -literal -offset indent +$ ./configure --enable-sandman +.Ed . .Sh FILES -.Bl -tag -width sandman.m -compact +.Bl -tag -width "command.c" -compact .It Pa chat.h -shared state and function prototypes +global state and declarations .It Pa chat.c -command line parsing -.It Pa event.c -event loop and process spawning -.It Pa tag.c -tag (channel, query) ID assignment -.It Pa handle.c -incoming command handling -.It Pa input.c -input command handling +startup and event loop .It Pa irc.c -TLS client connection -.It Pa format.c -IRC formatting -.It Pa color.c -nick and channel coloring +IRC connection and parsing .It Pa ui.c -cursed UI -.It Pa term.c -terminal features unsupported by curses +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 tab.c -tab-complete +.It Pa complete.c +tab complete .It Pa url.c URL detection -.It Pa pls.c -functions which should not have to be written +.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 .It Pa sandman.m -utility for Darwin to signal sleep +sleep/wake wrapper for macOS .El . .Pp -.Bl -tag -width sshd_config -compact -.It Pa sshd_config -anonymous SSH configuration -.It Pa man.sh +.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/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 , .Xr sandman 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 |