.Dd October 21, 2023
.Dt README 7
.Os "Causal Agency"
.
.Sh NAME
.Nm litterbox
.Nd IRC logger
.
.Sh DESCRIPTION
.Xr litterbox 1
is a TLS-only IRC logger.
It logs events from IRC in a SQLite database,
indexing messages for full-text search.
It is intended for use with
the IRC bouncer
.Lk https://git.causal.agency/pounce pounce ,
but can also be used independently
as a logging bot.
.
.Pp
.Nm
provides the
.Xr scoop 1
command-line query utility.
A web interface for
.Nm
is provided by
.Lk https://git.causal.agency/scooper scooper .
Some formats of plain text logs
can be imported into the
.Nm
database with
.Xr unscoop 1 .
.
.Sh INSTALLING
.Nm
requires SQLite3 and
.Sy libtls ,
provided by either
.Lk https://git.causal.agency/libretls/about LibreTLS
(for OpenSSL)
or by LibreSSL.
It targets
.Fx ,
.Ox
and Linux.
.Bd -literal -offset indent
\&./configure
make all
sudo make install
.Ed
.
.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
On
.Ox
the recommended way to run
.Nm
is with the process supervisor
.Lk https://git.causal.agency/kitd kitd .
.
.Sh FILES
.Bl -tag -width "litterbox.c" -compact
.It Pa database.h
database functions and schema
.It Pa litterbox.c
IRC logging
.It Pa scoop.c
query building and output formatting
.It Pa unscoop.c
log file processing
.It Pa config.c
.Xr getopt_long 3 Ns -integrated
configuration parsing
.It Pa xdg.c
XDG base directories
.El
.
.Sh CONTRIBUTING
The upstream URL of this project is
.Aq Lk https://git.causal.agency/litterbox .
Contributions in any form can be sent to
.Aq Mt list+litterbox@causal.agency .
For sending patches by email, see
.Aq Lk https://git-send-email.io .
.
.Pp
Monetary contributions can be
.Lk https://liberapay.com/june/donate "donated via Liberapay" .
.
.Sh SEE ALSO
.Xr litterbox 1 ,
.Xr scoop 1 ,
.Xr unscoop 1
.
.Bl -item
.It
IRC bouncer:
.Lk https://git.causal.agency/pounce pounce
.It
Web interface:
.Lk https://git.causal.agency/scooper scooper
.It
.Rs
.%A June McEnroe
.%T IRC Suite
.%U https://text.causal.agency/010-irc-suite.txt
.%D June 19, 2020
.Re
.El