README.md

@@ -1,19 +1,44 @@
 # sfeed_mastodon
 
-Mastodon-based front-end for the sfeed feed-reader. Mirror Atom/RSS feeds to Mastodon (& friends) simply and UNIX-ly.
+Mirror Atom/RSS feeds to Mastodon (& friends) simply and UNIX-ly.
+Mastodon-based front-end for the sfeed feed-reader.
 
 ![A screenshot of a post to a Pleroma server. It is a post made by sfeed_mastodon, and contains an article title (“Kajtoj ne nur gajigas la ĉielon”), a URL (https://uea.facila.org/artikoloj/legaĵoj/kajtoj-ne-nur-gajigas-la-ĉielon-r394/), and a quoted excerpt from the URL (“Kajtoj estas ŝat-okupo kaj sporto en okcidentaj landoj, kaj ili estas eĉ pli gravaj en Azio. Tie ili estas tradiciaj, tre popularaj, kaj povas esti tre belaj artaĵoj. Cetere ili delonge utilas al sporto, veter-scienco, fotado kaj militad[…]”).](res/screenshot.png)
 
-sfeed_mastodon takes output from the lovely feed-aggregator [sfeed](https://codemadness.org/sfeed-simple-feed-parser.html) and posts it to the fediverse.
 
 
+## Usage
+sfeed_mastodon takes output from the lovely feed-aggregator
+[sfeed](https://codemadness.org/sfeed-simple-feed-parser.html) and posts it to the fediverse.
+It could be considered a front-end for sfeed.
+
+You can use it to post an entire RSS feed like so:
+```
+$ FEDI_AUTH="yourAuthTokenHere"
+$ sfeed https://planet.gnu.org/rss20.xml | sfeed_mastodon https://yourServer.here
+```
+
+If you want to regularly update and mirror a feed — making it act like a normal RSS-repost bot — you
+can run it like so (after some [configuration](#sfeed)):
+```
+$ FEDI_AUTH="yourAuthorizationTokenHere"
+$ sfeed_update ~/.config/sfeedrc
+$ cat ~/.config/sfeed/* | sfeed_mastodon https://yourServer.here
+```
+
+It’s that simple. It’s safe to run these commands several times in a row  — feed entries that have
+already been posted won’t be reposted, if you use our `docs/sfeedrc.example` as your `sfeedrc`.
+
+For proper automation, you can simply put these commands in a shell script and run it regularly.
+Such a script has been provided, and is [described below](#mirror_feed) — `mirror_feed.sh`.
+
 
 ## Installation
 First, make sure to install [sfeed](https://codemadness.org/sfeed-simple-feed-parser.html).
 If Guix is your package manager:
 `$ guix install sfeed`
 
-Now, put ./sfeed_mastodon into your $PATH, somewhere. Something like /usr/local/bin, or ~/.local/bin.
+Now, put ./sfeed_mastodon into your $PATH, somewhere. Assuming `~/.local/bin/`…
 `$ cp sfeed_mastodon ~/.local/bin/`
 
 You’ve done it!
@@ -22,8 +47,9 @@ You’ve done it!
 
 ## Configuration
 ### sfeed
-We need to create a config file and feed directory for sfeed_update.
-You can use the sfeedrc.example file in this repo as a base for your own config file.
+If you want to regularly update an RSS/Atom feed and post only new entries, we need to do some
+configuration for `sfeed_update`. For this, we’ve gotta create a config file and feed directory.
+You should use the `sfeedrc.example file` in this repo as a base for your own config file.
 ```
 $ mkdir ~/.config/sfeed/
 $ cp sfeedrc.example ~/.config/sfeedrc
@@ -32,6 +58,10 @@ $ cp sfeedrc.example ~/.config/sfeedrc
 You need to edit the example sfeedrc to add in your own Atom/RSS feeds, or to change the feed path.
 You can read up more on sfeed’s configuration in its man-page¸ sfeedrc(5).
 
+Warning: If you *don’t* use the provided `sfeedrc.example` as a base for your configuration, you
+will probably end up reposting old entries — our `sfeedrc.example` only keeps the newest ones in
+the file to avoid this. So please, use `sfeedrc.example`.
+
 
 ### Mastodon
 Now, we need to find our authorization token for use with `sfeed_mastodon`.
@@ -48,21 +78,24 @@ Whenever you use sfeed_mastodon, make sure that this token is stored in the envi
 `$FEDI_AUTH`, or pass it with the `-a` parameter.
 
 
+### mirror_feed
+To automatically mirror an Atom/RSS feed, you can make a script that runs `sfeed_update` &
+`sfeed_mastodon`, and then put it in your crontab. `doc/mirror_feed.sh` is a script which does exactly this.
 
-## Usage
+To use `mirror_feed.sh` with the `~/.config/sfeedrc` from our [prior configuration](#sfeed):
 ```
-$ FEDI_AUTH="yourAuthorizationTokenHere"
-$ sfeed_update ~/.config/sfeedrc
-$ cat ~/.config/sfeed/* | sfeed_mastodon https://yourServer.here
+$ mirror_feed.sh ~/.config/
 ```
 
-It’s that simple. It’s safe to run these commands several times in a row  — feed entries that have
-already been posted won’t be reposted, if you use our example sfeedrc.
+`mirror_feed.sh` has an additional config file: `sfeedenv`. It is a simple shell script that
+exports two variables: `$FEDI_SERVER` and `$FEDI_AUTH`. It will be sourced by `mirror_feed.sh`,
+though you can optionally set these variables in the environment instead.
 
-To automatically mirror an Atom/RSS feed, you can put these commands into a script and put it in your crontab.
+Barring that, `mirror_feed.sh` expects a directory containing `sfeedrc` and a subdirectory `sfeed/`
+for posts — just like the example configuration in `~/.config` [discussed earlier](#sfeed).
 
 
-### Templates
+### Formatting
 You might want to know about the template parameter (`-t`) — this lets you tweak the output for
 sfeed_mastodon as you wish. With this, you can add specific hash-tags to your posts, for example.
 Its argument should be HTML with some variables within {{double-cramps}} for post data. 
@@ -86,6 +119,6 @@ Here are the variables you can use:
 
 
 ## Misc.
-Author: ([@jadedctrl:jam.xwx.moe](https://jam.xwx.moe/users/jadedctrl))  
+Author: [@jadedctrl:jam.xwx.moe](https://jam.xwx.moe/users/jadedctrl)  
 Source: https://notabug.org/jadedctrl/sfeed_mastodon  
 License: GPLv3

doc/mirror_feed.sh

@@ -0,0 +1,55 @@
+#!/bin/sh
+#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
+# Name: mirror_feed
+# Desc: Mirror an RSS/Atom feed to the fediverse, piecemeal.
+# Reqs: sfeed, sfeed_update, sfeed_mastodon
+# Date: 2023-11-19
+# Lisc: GPLv3
+# Auth: @jadedctrl@jam.xwx.moe
+#―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
+
+usage() {
+	echo "usage: $(basename $0) [-h] DIRECTORY"
+	echo "Updates an sfeed feed and posts new entries to the fediverse."
+	echo ""
+	echo "DIRECTORY must contain:"
+	echo "  * The sfeed_update(1) config file, sfeedrc(5)."
+	echo "  * 'sfeed/', a directory where posts are to be stored."
+	echo ""
+	echo "Optionally, DIRECTORY can contain 'sfeedenv', a script defining"
+	echo "the variables \$FEDI_AUTH and \$FEDI_SERVER."
+}
+
+
+MIRROR_DIR="$1"
+
+if test -z "$MIRROR_DIR" -o "$MIRROR_DIR" = "-h" -o "$MIRROR_DIR" = "--help"; then
+	usage
+	exit 2
+fi
+
+
+if test ! -d "$MIRROR_DIR"; then
+	1>&2 echo "The given DIRECTORY '$MIRROR_DIR' doesn’t seem to be a directory at"
+	1>&2 echo "all. Would you mind giving it another go?"
+	1>&2 echo ""
+	1>&2 usage
+	exit 3
+fi
+
+
+if test -f "$MIRROR_DIR/sfeedenv"; then
+	source "$MIRROR_DIR/sfeedenv" 2> /dev/null
+fi
+if test -z "$FEDI_AUTH" -o -z "$FEDI_SERVER"; then
+	1>&2 echo "The environment variables \$FEDI_AUTH and \$FEDI_SERVER are undefined."
+	1>&2 echo "Please set them before running $(basename "$0"), or define them in a"
+	1>&2 echo "script at the path '$MIRROR_DIR/sfeedenv'."
+	1>&2 echo ""
+	1>&2 usage
+	exit 4
+fi
+
+
+sfeed_update "$MIRROR_DIR/.sfeedrc"
+cat "$MIRROR_DIR/sfeed/* | sfeed_mastodon "$FEDI_SERVER"

doc/sfeedenv.example

@@ -0,0 +1,2 @@
+export FEDI_AUTH=your_fedi_auth_key_here
+export FEDI_SERVER=https://your_server_here.co.uk