From 717645a42152c8be876b3b56367e0e63ab6c3ea5 Mon Sep 17 00:00:00 2001
From: Jeremy Baxter <jeremy@based.my.domain>
Date: Thu, 28 Jul 2022 18:27:45 +1200
Subject: [PATCH] Added matrix-send(1) manpage

---
 matrix-send.1 | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 matrix-send.1

diff --git a/matrix-send.1 b/matrix-send.1
new file mode 100644
index 0000000..d82deb3
--- /dev/null
+++ b/matrix-send.1
@@ -0,0 +1,99 @@
+.Dd $Mdocdate: July 28 2022 $
+.Dt MATRIX-SEND 1
+.Os
+.Sh NAME
+.Nm matrix-send
+.Nd send a message to a Matrix room
+.Sh SYNOPSIS
+.Nm matrix-send
+.Bk -words
+.Op Fl c
+.Op Fl h
+.Op Fl v
+.Ar message room
+.Ek
+.Sh DESCRIPTION
+.Nm
+is a script to send a message to a Matrix room.
+It works by sending a JSON request to your Matrix server. The message
+type will always be m.text, but other options may be considered in the
+future.
+.Pp
+To begin, start by making a configuration file. This always has the location of
+.Em ~/.config/matrix-send.conf .
+
+At the very least, your configuration file has to contain 3 directives:
+.Em Server ,
+.Em Username ,
+and
+.Em Password .
+Let's say your Matrix server is envs.net. Your username is john, and your password is supersecretpassword. Your configuration could look like this:
+.Bd -literal -offset indent
+Server matrix.envs.net
+Username john
+Password supersecretpassword
+.Ed
+.Pp
+In that example, we used matrix.envs.net instead of envs.net. This is because
+matrix.envs.net is the address in which the Client-Server API is listening on.
+You can find your server's Client-Server API URL in Element by entering in
+your server into the Homeserver dialogue in the sign-in screen, then hovering
+over it once entered. Your server's Client-Server API URL should appear once
+you hover over it. If it doesn't appear, you've already got it.
+.Pp
+You may have noticed that with this configuration, your password
+is visible in plain sight.
+
+At its most basic, matrix-send.conf is a shell script. This means you could
+replace the
+.Em Password
+line with something similar to this
+.Bd -literal -offset indent
+Password $(gpg -d /path/to/passwd.gpg)
+.Ed
+.Pp
+where
+.Em /path/to/passwd.gpg
+is a GPG-encrypted plain text file containing only your password.
+This line would mean that you would be asked for the passphrase required to
+decrypt your password file before authenticating. This way, your password
+is not in plain text.
+
+More information on configuration options can be found in
+.Xr matrix-send.conf 5 .
+.Pp
+To use
+.Nm ,
+you will need to get the Room ID of the room you'd like to send to.
+This will be something like
+.Em !zyxwvutsrq:example.org .
+
+Type the Room ID as the argument after the message you wish to send.
+You may have to escape the exclamation mark with a backslash. For example:
+.Bd -literal -offset indent
+matrix-send "Hello world!" \!zyxwvutsrq:example.org
+.Ed
+.Pp
+That should send a message saying
+.Em Hello world!
+to the room with the Room ID !zyxwvutsrq:example.org.
+
+By default,
+.Nm
+caches access tokens in
+.Em $HOME/.cache/matrix-send/access-token .
+If you would like to disable caching of access tokens, add NoCache to your
+.Em matrix-send.conf .
+.El
+
+.Sh FILES
+.Bl -tag -width ~/.config/matrix-send.conf
+.It Pa ~/.config/matrix-send.conf
+configuration file for
+.Nm
+.It Pa ~/.cache/matrix-send/access-token
+access token cache file
+.El
+
+.Sh SEE ALSO
+.Xr matrix-send.conf 5