Add the manual page

2 files changed, 363 insertions, 0 deletions

diff --git a/quarg.1 b/quarg.1
new file mode 100644
index 0000000..9b25a49
--- /dev/null
+++ b/quarg.1
@@ -0,0 +1,359 @@
+.Dd May 5, 2021
+.Dt QUARG 1
+.Os
+.Sh NAME
+.Nm quarg
+.Nd search Quassel logs for matching messages and print them
+.Sh SYNOPSIS
+.Nm
+.Op Fl de
+.Op Fl l Ar num
+.Op Fl o Ar order
+.Op Fl b Ar buffer
+.Op Fl B Ar buftype
+.Op Fl f Ar msgflag
+.Op Fl m Ar prefix
+.Op Fl n Ar nick
+.Op Fl N Ar network
+.Op Fl Q Ar user
+.Op Fl t Ar msgtype
+.Op Fl -after Ar date
+.Op Fl -around Ar date Ns Op / Ns Ar range
+.Op Fl -before Ar date
+.Op Fl -joined | -no-joined
+.Op Ar keyword Op Ar keyword ...
+.Nm
+.Fl h | -help
+.Sh DESCRIPTION
+.Nm
+searches Quassel logs for messages matching a set of conditions and
+prints the results.
+See
+.Sx CONNECTING TO QUASSEL
+for more information on how to set up the database connection.
+.Pp
+A condition is any option from the
+.Sx CONDITIONS
+section.
+At least one condition needs to be specified.
+If multiple different types of conditions are given, all of them must
+match.
+The same condition can be specified multiple times with different
+arguments, in which case it matches any of the arguments.
+.Pp
+If there are any results,
+.Nm
+prints each match using Quassel's message format, prefixed with the
+timestamp in local time and the origin buffer of the message separated
+by the tab
+character.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl d
+Prints additional debug information.
+This includes the
+.Em SELECT
+statements executed by SQL as well as an internal representation of the
+conditions passed to
+.Nm .
+.It Fl e
+Interprets any
+.Ar keyword
+as a
+.Em LIKE
+expression.
+This allows the use of the
+.Sq %
+placeholder.
+If no placeholders are given, matches the
+.Ar keyword
+exactly.
+.It Fl l Ar num
+Limits the number of matches to
+.Ar num .
+.It Fl o Ar order
+Specifies in which order to sort the messages.
+Matches are always sorted by timestamp.
+.Ar order
+can be
+.Sy asc
+for ascending order or
+.Sy desc
+for descending order.
+The default is
+.Sy asc .
+.Pp
+This option is useful in conjunction with
+.Fl l Ar num ,
+as it may be used to have
+.Nm
+limit output to the oldest
+.Pq Sy asc
+or most recent
+.Pq Sy desc
+.Ar num
+matches.
+.It Fl h | -help
+Shows the integrated help page and exits.
+.El
+.Sh CONDITIONS
+The conditions are as follows:
+.Bl -tag -width Ds
+.It Ar keyword
+Matches messages containing
+.Ar keyword .
+.It Fl b Ar buffer
+Matches messages in a specific buffer, given by its name as displayed in
+the Quassel client.
+.It Fl B Ar buftype
+Matches messages in buffers of a specific type.
+.Pp
+.Ar buftype
+can be one of
+.Sy channel ,
+.Sy query ,
+or
+.Sy status ,
+for channels, queries, and the status (or
+.Dq network )
+buffers respectively.
+.It Fl f Ar msgflag
+Matches messages of a specific context, given by a flag name.
+.Pp
+The flag names are as follows:
+.Bl -tag -width Ds
+.It Sy highlight
+Messages that triggered Quassel's
+.Dq Remote Highlight
+rules.
+By default this includes messages containing the current nickname.
+.It Sy none
+Messages that do not have any flag set.
+.It Sy self
+Messages that were sent by Quassel users themselves.
+.El
+.It Fl m Ar prefix
+Matches messages sent by nicknames that have a specific channel
+membership prefix as defined in the
+.Sy Channel Membership Prefix section Ns No [1]
+of the Modern IRC Client Protocol specification.
+.Pp
+Common prefixes include
+.Sq @
+for operators,
+.Sq %
+for half-ops, and
+.Sq +
+for voiced users.
+.Pp
+Note that multiple prefixes may be set at the same time (for example a
+voiced operator).
+In this case, any prefix will match, but the printed message will only
+show the
+.Dq highest
+one.
+.It Fl n Ar nick
+Matches messages sent by a specific user, given by nickname.
+.It Fl N Ar network
+Matches messages in a specific network, given by its name as displayed
+in the Quassel client.
+.It Fl Q Ar user
+Matches messages relating to a specific Quassel user, given by their
+user name.
+.Pp
+This condition is only useful if the Quassel database contains logs
+for multiple Quassel users.
+Without this condition,
+.Nm
+matches messages from any Quassel user.
+.It Fl t Ar msgtype
+Matches messages of a specific type.
+.Pp
+.Ar msgtype
+can be one of the following, corresponding to IRC messages as defined
+in
+.Sy RFC 1459 Ns No [2] :
+.Sy invite ,
+.Sy join ,
+.Sy kick ,
+.Sy kill ,
+.Sy mode ,
+.Sy nick ,
+.Sy notice ,
+.Sy part ,
+.Sy privmsg ,
+.Sy quit ,
+.Sy topic .
+.Pp
+In addition,
+.Nm
+supports the following message types:
+.Bl -tag -width Ds
+.It Sy action
+The CTCP ACTION message.
+.It Sy error
+Error messages as reported to the user by Quassel.
+.It Sy netsplit_join
+Messages indicating the end of a netsplit, along with the users who
+rejoined.
+.It Sy netsplit_quit
+Messages indicating an ongoing netsplit, along with the users who quit.
+.It Sy server
+Server messages as reported to the user by Quassel.
+.El
+.It Fl -joined
+Matches messages in channels that are currently joined.
+.It Fl -no-joined
+Matches messages in channels that are currently not joined.
+.Pp
+Note that as a result of the implementation in Quassel, this condition
+matches all query buffers.
+If this is undesirable, combine this condition with
+.Fl B No channel .
+.El
+.Pp
+In addition,
+.Nm
+supports matching on message timestamps.
+Wherever a date is passed as an argument to a condition,
+.Nm
+parses it according to the
+.Sy ISO-8601
+standard.
+.Pp
+A date may include a time element and a time zone offset.
+If no time zone offset is given, the date is assumed to be in local
+time.
+Refer to
+.Sy dateutil's isoparse documentation Ns No [3]
+for detailed information.
+.Pp
+The conditions that match on message timestamps are as follows:
+.Bl -tag -width Ds
+.It Fl -after Ar date
+Matches messages that were sent after
+.Ar date .
+.It Fl -around Ar date Ns Op / Ns Ar range
+Matches messages sent after
+.Ar date -
+.Ar range
+and before
+.Ar date +
+.Ar range .
+If
+.Ar range
+is not given, defaults to 12 hours.
+.Pp
+.Ar range
+consists of a number and an optional suffix
+.Sq h
+for hours or
+.Sq m
+for minutes.
+If no suffix is given, defaults to hours.
+.Pp
+For example,
+.Dq 2021-02-18 20:55Z/10m
+matches messages sent between 20:45 and 21:05.
+This is equivalent to the following:
+.Bd -literal -offset indent
+quarg --after '2021-02-18 20:45Z' --before '2021-02-18 21:05Z'
+.Ed
+.Pp
+This option cannot be used with
+.Fl -after
+or
+.Fl -before .
+.It Fl -before Ar date
+Matches messages that were sent before
+.Ar date .
+.El
+.Sh CONNECTING TO QUASSEL
+In order to access Quassel's logs,
+.Nm
+needs access to the Quassel database.
+The easiest way to achieve this is to have it running on the database
+host and remotely invoke it using
+.Xr ssh 1 .
+Alternatively, the database port (or socket) may be forwarded to a local
+machine
+via
+.Xr ssh 1
+and used with a local
+.Nm
+instance.
+.Pp
+.Nm
+uses SQLAlchemy which supports both SQLite and PostgreSQL backends.
+The psycopg2 backend is recommended for the latter.
+.Pp
+If Quassel uses the PostgreSQL backend,
+it is highly recommended to set up a read-only database role
+specifically for
+.Nm .
+Furthermore, consider using the
+.Sy Peer Authentication Ns No [4]
+method with a dedicated user.
+This type of authentication removes the need for a password and
+also works over a forwarded connection.
+.Pp
+.Nm
+reads the database URL from an INI-style configuration file.
+See
+.Sx FILES
+for the location of this file.
+The URL is specified in the
+.Em Database
+section using the
+.Em url
+key.
+See
+.Sy Database URLs Ns No [5]
+for details on the URL format.
+.Pp
+The following is a valid configuration file specifying a connection to a
+local PostgreSQL instance via its default socket:
+.Bd -literal -offset indent
+[Database]
+url = postgresql+psycopg2://quarg@/quassel?host=/run/postgresql
+.Ed
+.Sh FILES
+.Bl -tag -width Ds
+.It Em $XDG_CONFIG_HOME/quarg/config
+The configuration file for
+.Nm .
+.El
+.Pp
+.Nm
+adheres to the XDG Base Directory Specification.
+If $XDG_CONFIG_HOME is unset or empty, it will default to
+.Em ~/.config
+.Sh NOTES
+.Bl -enum
+.It
+.Sy Channel Membership Prefixes
+.Pp
+https://modern.ircdocs.horse/#channel-membership-prefixes
+.It
+.Sy RFC 1459
+.Pp
+https://tools.ietf.org/html/rfc1459
+.It
+.Sy dateutil isoparse
+.Pp
+https://dateutil.readthedocs.io/en/stable/parser.html#dateutil.parser.isoparse
+.It
+.Sy Peer Authentication
+.Pp
+https://www.postgresql.org/docs/13/auth-peer.html
+.It
+.Sy Database URLs
+.Pp
+https://docs.sqlalchemy.org/en/14/core/engines.html#database-urls
+.El
+.Sh AUTHORS
+.An -nosplit
+.Nm
+was written by
+.An Wolfgang Müller Aq Mt wolf@oriole.systems
diff --git a/setup.py b/setup.py
index 055c344..15a8372 100644
--- a/setup.py
+++ b/setup.py
@@ -9,6 +9,10 @@ setuptools.setup(
         packages=setuptools.find_packages(),
         python_requires=">=3.8",
 
+        data_files = [
+            ('man/man1', ['quarg.1'])
+        ],
+
         entry_points = {
             'console_scripts': [
                 'quarg = quarg.main:main',