From 4b51c0e3f87e354efe41c5fcbd480741ab9fcad3 Mon Sep 17 00:00:00 2001
From: emma <emma@tebibyte.media>
Date: Tue, 8 Nov 2022 01:38:07 -0500
Subject: [PATCH] more README

---
 README.md  | 70 ++++++++++++++++++++++++++++++++++++++++++++++--------
 xdg-sanity |  2 ++
 2 files changed, 62 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 1d5b144..a190fcb 100644
--- a/README.md
+++ b/README.md
@@ -14,21 +14,38 @@ AUR](https://aur.archlinux.org/packages/xdg-sanity).
 
 ### From Source
 
-First, make sure you have `curl(1)`, `xdg-utils(1)` (or an alternative like
-[handlr](https://github.com/chmln/handlr)), and
-[tomcat](https://git.tebibyte.media/emma/tomcat) installed. Then, clone this
-repository and move the `xdg-sanity` binary wherever your operating system
-stores locally-installed binaries. This is usually `/usr/local/bin` or
+Dependencies:
+- `curl(1)`
+- `xdg-utils(1)` or `handlr(1)`
+- `tomcat(1)`
+
+You can get `tomcat` [here](https://git.tebibyte.media/emma/tomcat)
+
+Instructions:
+Clone this repository and move the `xdg-sanity` binary wherever your operating
+system stores locally-installed binaries. This is usually `/usr/local/bin` or
 `$HOME/.local/bin` for your user. Make sure the installation location is in your
 `$PATH`.
 
 Create an `xdg-sanity.desktop` file either manually or with `gendesk(1)`,
-placing it, also, where your OS stores locally-installed `.desktop` files,
-usually `/usr/local/applications`. Set your default web browser to that
-`.desktop` file with `xdg-settings(1)` or an equivalent.
+placing it where your OS stores locally-installed `.desktop` files, which is
+usually `/usr/local/share/applications` or `$XDG_DATA_HOME/applications` for 
+your user. Set your default web browser to that `.desktop` file with
+`xdg-settings(1)` or an equivalent.
 
-Add your default web browser to `$XDG_CONFIG_HOME/xdg-sanity.toml` so the
-script can forward links to it.
+### Configuration
+
+This program uses [TOML](https://toml.io/en/v1.0.0) for its configuration. The
+configuration file is set up like this:
+```
+$ cat $XDG_CONFIG_HOME/xdg-sanity.toml
+[tools]
+browser = "firefox"
+xdg = "handlr launch"
+```
+
+The options available for `xdg` are `handlr launch` if you use `handlr(1)` and
+`xdg-open` if you use `xdg-utils(1)`.
 
 ### Usage
 
@@ -36,3 +53,36 @@ script can forward links to it.
 
 Open links from applications outside your web browser as normal. Alternatively,
 you can call `xdg-sanity` directly with the only argument accepted being a URI.
+
+#### Extensions
+
+Extensions are written using TOML and are stored in either 
+`/usr/share/xdg-sanity` when installed from a package manager,
+`/usr/local/share/xdg-sanity` when installed locally, or 
+`$XDG_DATA_HOME/xdg-sanity` for your user.
+
+There are two types of extensions: MIME and replace. MIME extensions are parsed
+first and replace the MIME type of the content being fetched. Replace extensions
+change the URI passed to the command to another.
+
+The type of the extension depends on the file name. MIME extensions should have
+a name ending in `-mime.toml` and replace extensions should have 
+`-replace.toml`.
+
+Here's what a MIME extension looks like:
+```
+cat $XDG_DATA_HOME/xdg-sanity/youtube-mime.toml
+[replace]
+urls = [ "youtube.com", "youtu.be" ]
+
+[with]
+mime = "video/vnd.youtube.yt"
+```
+and here's what a replace extension looks like:
+```
+cat $XDG_DATA_HOME/xdg-sanity/youtube-replace.toml
+[replace]
+urls = [ "youtube.com", "youtu.be" ]
+
+[with] 
+url = "https://piped.mint.lgbt/"
diff --git a/xdg-sanity b/xdg-sanity
index 9fc0c99..6df361a 100755
--- a/xdg-sanity
+++ b/xdg-sanity
@@ -68,6 +68,7 @@ while test -n "$1"; do
 	for file in \
 		"$XDG_DATA_HOME"/xdg-sanity/*-mime.toml \
 	  /usr/share/xdg-sanity/*-mime.toml \
+		/usr/local/share/xdg-sanity/*-mime.toml \
 		/dev/null
 	do
 		i=$(tomcat replace.urls "$file" | sed 's/	/\n/g' | xargs wc -l)
@@ -83,6 +84,7 @@ while test -n "$1"; do
 	for file in \
 		"$XDG_DATA_HOME"/xdg-sanity/*-replace.toml \
 	  /usr/share/xdg-sanity/*-replace.toml \
+		/usr/local/share/xdg-sanity/*-replace.toml \
 		/dev/null
 	do
     i=$(tomcat replace.urls "$file" | sed 's/	/\n/g' | xargs wc -l)