Update documentation for version 2.0

Makefile

@@ -3,7 +3,8 @@ PREFIX = /usr/local
 MANPREFIX = ${PREFIX}/man
 
 config:
-	cp matrix-send.conf ~/.config/matrix-send.conf
+	mkdir -p ~/.config/matrix-send
+	cp config.lua ~/.config/matrix-send/config.lua
 
 install:
 	cp -f matrix-send ${DESTDIR}${PREFIX}/bin
@@ -11,4 +12,4 @@ install:
 	mkdir -p ${DESTDIR}${MANPREFIX}/man1
 	cp -f matrix-send.1 ${DESTDIR}${MANPREFIX}/man1
 	mkdir -p ${DESTDIR}${MANPREFIX}/man5
-	cp -f matrix-send.conf.5 ${DESTDIR}${MANPREFIX}/man5
+	cp -f matrix-send-config.5 ${DESTDIR}${MANPREFIX}/man5

README.md

@@ -1,22 +1,16 @@
 # matrix-send
 
-A script that sends a message to a Matrix room.
+A script that sends messages to Matrix rooms.
 
 [Read the manual page](https://jtbx.codeberg.page/man/matrix-send.1)
 
 ---
 
-**Syntax:** `matrix-send message room`
-
-**Example:** `matrix-send "Hello world\!" \!aBcDeFgHiJkLmNoP:example.org`
-
----
-
 matrix-send is a simple script that sends a message to a Matrix room.
 
-It does this by sending a JSON message to your Matrix server. The message types that are supported are *m.text*, and *m.notice*.
+It does this by sending a JSON message to your Matrix server. The message types that are supported are `m.text`, and `m.notice`.
 
-It is mainly designed for automation. I use it on a private Matrix room of mine.
+It is mainly designed for automation.
 
 There aren't any plans for matrix-send to support encryption.
 

config.lua

@@ -0,0 +1,31 @@
+login = {
+	-- The Matrix server to use.
+	server = "matrix-client.matrix.org", -- matrix.org
+
+	-- The user to log in to.
+	username = "user",
+
+	-- The password for the user.
+	password = "password",
+
+	-- The access token to use (instead of credentials).
+	-- If token equals nil, credentials are used.
+	-- If token is not nil, credentials are ignored.
+	token = nil
+
+	-- The server value needs to be provided.
+	-- You can choose to login with user credentials or a
+	-- token. One of them needs to be provided.
+}
+
+rooms = {
+	-- Room aliases.
+	-- Here you can add aliases for rooms,
+	-- instead of having to type the confusing
+	-- Room ID every single time you send a message.
+	-- Examples:
+	--my_alias = "!AbCdEfGhIjKl:burger.land",
+	--lounge = "!MnOpQrSTuVWxYz:gaming.bruvs"
+	-- When you want to send to a Matrix room, you
+	-- can just type the alias instead of the long Room ID.
+}

default_config.lua

@@ -0,0 +1,49 @@
+-- The configuration file for matrix-send is written in Lua format.
+-- Here is a list of all possible options in the configuration file.
+-- Default values appear after the '=' sign.
+
+login = {
+	-- The Matrix server to use.
+	server = nil,
+
+	-- The user to log in to.
+	username = nil,
+
+	-- The password for the user.
+	password = nil,
+
+	-- The access token to use (instead of credentials).
+	-- If token equals nil, credentials are used.
+	-- If token is not nil, credentials are ignored.
+	token = nil
+
+	-- The server value needs to be provided.
+	-- You can choose to login with user credentials or a
+	-- token. One of them needs to be provided.
+}
+
+cache = {
+	-- The path to cache access tokens at.
+	location = "~/.cache/matrix-send",
+
+	-- Disable caching access tokens?
+	disable = false
+}
+
+rooms = {
+	-- Room aliases.
+	-- Here you can add aliases for rooms,
+	-- instead of having to type the confusing
+	-- Room ID every single time you send a message.
+	-- Examples:
+	--my_alias = "!AbCdEfGhIjKl:burger.land",
+	--lounge = "!MnOpQrSTuVWxYz:gaming.bruvs"
+	-- When you want to send to a Matrix room, you
+	-- can just type the alias instead of the long Room ID.
+}
+
+advanced = {
+	-- The default event type.
+	-- Can be either m.text or m.notice.
+	event = "m.text"
+}

matrix-send

@@ -104,58 +104,6 @@ function confpanic(s)
 	os.exit(1)
 end
 
---[[
-	The configuration file for matrix-send is written in Lua format.
-	Here is a list of all possible options in the configuration file.
-	Default values appear after the '=' sign.
-
-	login = {
-		-- The Matrix server to use.
-		server = nil,
-
-		-- The user to log in to.
-		username = nil,
-
-		-- The password for the user.
-		password = nil,
-
-		-- The access token to use (instead of credentials).
-		-- If token equals nil, credentials are used.
-		-- If token is not nil, credentials are ignored.
-		token = nil
-
-		-- The server value needs to be provided.
-		-- You can choose to login with user credentials or a
-		-- token. One of them needs to be provided.
-	}
-
-	cache = {
-		-- The path to cache access tokens at.
-		location = "~/.cache/matrix-send",
-
-		-- Disable caching access tokens?
-		disable = false
-	}
-
-	rooms = {
-		-- Room aliases.
-		-- Here you can add aliases for rooms,
-		-- instead of having to type the confusing
-		-- Room ID every single time you send a message.
-		-- Examples:
-		--my_alias = "!AbCdEfGhIjKl:burger.land",
-		--lounge = "!MnOpQrSTuVWxYz:gaming.bruvs"
-		-- When you want to send to a Matrix room, you
-		-- can just type the alias instead of the long Room ID.
-	}
-
-	advanced = {
-		-- The default event type.
-		-- Can be either m.text or m.notice.
-		event = "m.text"
-	}
---]]
-
 -- Default configuration file
 default_config = [[
 -- Default configuration file for matrix-send

matrix-send-config.5

@@ -0,0 +1,65 @@
+.Dd $Mdocdate: January 1 2023 $
+.Dt MATRIX-SEND-CONFIG 5
+.Os
+.Sh NAME
+.Nm config.lua
+.Nd configuration file for
+.Xr matrix-send 1
+.Sh DESCRIPTION
+.Xr matrix-send 1
+sends messages to Matrix rooms. In order to send a message however, it needs
+credentials for the account sending the message. These credentials are provided
+in the
+.Nm
+configuration file, as well as other options if you need them.
+.Pp
+The configuration file is in Lua format, meaning
+you can write whatever Lua code you wish inside.
+.Pp
+The following configuration options are available:
+.Bl -tag -width 11n
+.Bl -tag -width login.server
+.It Ic login.server Ar server
+The Client-Server API address of the Matrix server being used.
+.It Ic login.username Ar username
+The username of the account being used.
+.It Ic login.password Ar password
+The password for the account being used.
+.It Ic login.token Ar token
+Instead of authenticating via username and password to obtain an access token, use
+.Ar token
+as the access token.
+.It Ic cache.location Ar location
+Use
+.Ar location
+as the cache location.
+.It Ic cache.disable
+Don't cache anything.
+.It Ic advanced.event Ar type
+Modify the default event type from the default (m.text) to
+.Ar type .
+Supported types are m.text, and m.notice.
+.El
+.Sh FILES
+.Bl -tag -width ~/.config/matrix-send/config.lua -compact
+.It Pa ~/.config/matrix-send/config.lua
+.Xr matrix-send 1
+configuration file
+.It Pa ~/.cache/matrix-send
+default cache directory
+.El
+.Sh EXAMPLES
+The following example logs into the user 'john' of the server
+matrix-client.matrix.org, and the password 'supersecretpassword',
+and sets the default event type to m.notice.
+.Bd -literal -offset indent
+login = {
+	server = "matrix-client.matrix.org",
+	username = "john",
+	password = "supersecretpassword"
+}
+
+advanced.event = "m.notice"
+.Ed
+.Sh SEE ALSO
+.Xr matrix-send 1

matrix-send.1

@@ -1,4 +1,4 @@
-.Dd $Mdocdate: August 4 2022 $
+.Dd $Mdocdate: January 1 2023 $
 .Dt MATRIX-SEND 1
 .Os
 .Sh NAME
@@ -8,19 +8,24 @@
 .Nm matrix-send
 .Bk -words
 .Op Fl t Ar type
-.Op Fl C Ar config
+.Op Fl c Ar config
-.Op Fl chV
+.Op Fl CV
 .Ar message room
 .Ek
 .Sh DESCRIPTION
 .Nm
-is a script that sends a message to a Matrix room.
+sends messages to Matrix rooms.
-It works by sending a JSON message to your Matrix server. The default message
+The default event type is m.text (standard text message),
-type is m.text, but you can specify a custom type with
+but you can specify a custom type with
 .Em -t .
 .Pp
 The options are as follows:
 .Bl -tag -width keyword
+.It Fl C
+Clear cached access tokens and transaction IDs then exit.
+.It Fl c Ar config
+Instead of reading the default configuration file (~/.config/matrix-send.conf), read
+.Ar config .
 .It Fl t Ar type
 Change the event type to
 .Ar type .
@@ -30,49 +35,52 @@ and
 .Em m.notice .
 Default is
 .Em m.text .
-.It Fl C Ar config
-Instead of reading the default configuration file (~/.config/matrix-send.conf), read
-.Ar config .
-.It Fl c
-Clear cached access tokens.
-.It Fl h
-Show the help menu, then exit.
 .It Fl V
-Print version and program information, then exit.
+Print version information and exit.
 .El
 .Pp
 To begin, start by making a configuration file. This always has the location of
-.Em ~/.config/matrix-send.conf .
+.Em ~/.config/matrix-send/config.lua .
 
-At the very least, your configuration file has to contain 3 directives:
+At the very least, your configuration file has to contain three values:
-.Em Server ,
+.Em login.server ,
-.Em Username ,
+.Em login.username ,
 and
-.Em Password .
+.Em login.password .
-Let's say your Matrix server is envs.net. Your username is john, and your 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
+login = {
-Username john
+	server = "matrix.envs.net",
-Password supersecretpassword
+	username = "john",
+	password = "supersecretpassword"
+}
 .Ed
 .Pp
-In that example, we used matrix.envs.net instead of envs.net. This is because
+It could also look like this:
+.Bd -literal -offset indent
+login.server = "matrix.envs.net"
+login.username = "john"
+login.password = "supersecretpassword"
+.Ed
+.Pp
+In those examples, 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
+You can find this address in Element by entering in your server into the
-your server into the Homeserver dialogue in the sign-in screen, then hovering
+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.
+you hover over it. If it doesn't appear, you should already have 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
+If you would like to have to encrypt your password before use,
+you could
 replace the
-.Em Password
+.Em login.password
 line with something similar to this
 .Pp
-.Dl Password $(gpg -d /path/to/passwd.gpg)
+	login.password = sh "gpg -d /path/to/passwd.gpg"
 .Pp
 where
 .Em /path/to/passwd.gpg
@@ -82,7 +90,7 @@ 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 .
+.Xr matrix-send-config 5 .
 .Pp
 To use
 .Nm ,
@@ -102,9 +110,13 @@ to the room with the Room ID !zyxwvutsrq:example.org.
 By default,
 .Nm
 caches access tokens in
-.Em $HOME/.cache/matrix-send/access-token .
+.Em $HOME/.cache/matrix-send/token .
-If you would like to disable caching of access tokens, add NoCache to your
+If you would like to disable caching of access tokens, add
-.Em matrix-send.conf .
+.Pp
+.Dl cache.disable = true
+.Pp
+to your
+.Em config.lua .
 .Pp
 Encryption is not supported. All messages will be sent unencrypted.
 There are currently no plans to add encryption to
@@ -112,19 +124,19 @@ There are currently no plans to add encryption to
 .El
 
 .Sh FILES
-.Bl -tag -width ~/.config/matrix-send.conf
+.Bl -tag -width ~/.config/matrix-send/config.lua
-.It Pa ~/.config/matrix-send.conf
+.It Pa ~/.config/matrix-send/config.lua
 configuration file for
 .Nm
-.It Pa ~/.cache/matrix-send/access-token
+.It Pa ~/.cache/matrix-send
-access token cache file
+cache directory
 .El
 
 .Sh EXAMPLES
-Send a message saying "How are you?" to the Matrix room !TfbDbeqp:example.org:
+Send a message saying "Hello world!" to the Matrix room !TfbDbeqp:example.org:
 .Pp
-.Dl matrix-send 'How are you?' !TfbDbeqp:example.org
+.Dl matrix-send 'Hello world!' \\!TfbDbeqp:example.org
 .Pp
 
 .Sh SEE ALSO
-.Xr matrix-send.conf 5
+.Xr matrix-send-config 5

matrix-send.conf

@@ -1,17 +0,0 @@
-## Example basic configuration for matrix-send
-# A line with an option (e.g. 'Username jeremy') is a "directive".
-# A line with only one word (e.g. 'NoCache') is a "statement".
-# Comments start with a pound (#)
-# Additional options can be found in matrix-send.conf(5)
-
-# The Server directive is for your server's Matrix Client-Server API URL.
-# matrix-send assumes that this is valid.
-# matrix.org's CS API URL is matrix-client.matrix.org.
-# You can find it by typing it into Element's sign in page and hovering your mouse over it.
-Server matrix.envs.net
-
-# The Username directive is your username for that server.
-Username john
-
-# The Password directive is your password for your account.
-Password supersecretpassword

matrix-send.conf.5

@@ -1,60 +0,0 @@
-.Dd $Mdocdate: August 4 2022 $
-.Dt MATRIX-SEND.CONF 5
-.Os
-.Sh NAME
-.Nm matrix-send.conf
-.Nd configuration file for
-.Xr matrix-send 1
-.Sh DESCRIPTION
-.Xr matrix-send 1
-sends messages to Matrix rooms. In order to send a message however, it needs
-credentials for the account sending the message. These credentials are provided
-in the
-.Nm
-configuration file, as well as other options if you need them.
-.Pp
-The following configuration options are available:
-.Bl -tag -width 11n
-.Bl -tag -width keepenv
-.It Ic Server Ar server
-The Client-Server API address of the Matrix server being used.
-.It Ic Username Ar username
-The username of the account being used.
-.It Ic Password Ar password
-The password for the account being used.
-.It Ic AccessToken Ar token
-Instead of authenticating via username and password to obtain an access token, use
-.Ar token
-as the access token.
-.It Ic CacheLocation Ar location
-Modify the cache location from the default (~/.cache) to
-.Ar location .
-.It Ic NoCache
-Don't cache access tokens.
-.It Ic DefaultEvent Ar type
-Modify the default event type from the default (m.text) to
-.Ar type .
-Supported types are m.text, and m.notice.
-.It Ic PrettyPrint
-Pretty-print the JSON server messages.
-.El
-.Sh FILES
-.Bl -tag -width ~/.config/matrix-send.conf -compact
-.It Pa ~/.config/matrix-send.conf
-.Xr matrix-send 1
-configuration file.
-.It Pa ~/.cache
-Default cache location.
-.El
-.Sh EXAMPLES
-The following example logs into the user johndoe of the server with the
-Client-Server API address of matrix-client.matrix.org with the password
-supersecretpassword, and sets the default event type to m.notice.
-.Bd -literal -offset indent
-Server matrix-client.matrix.org
-Username johndoe
-Password supersecretpassword
-DefaultEvent m.notice
-.Ed
-.Sh SEE ALSO
-.Xr matrix-send 1