From 835a7a0ac8dc469968f77a28ea53d50d01224950 Mon Sep 17 00:00:00 2001 From: Solderpunk Date: Tue, 17 Mar 2020 20:57:35 +0100 Subject: [PATCH] Update README. --- README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a00cb14..24cff9d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,51 @@ -# gemfeed +# Gemfeed -Generate an Atom feed from a directory of text/gemini files. \ No newline at end of file +Gemfeed is a simple tool for generating Atom feeds for directories of +text/gemini files. It may not be adequate for large, complicated +Gemini sites, but if you have, for example, a gemlog which is just a +single directory full of .gmi files, each of which corresponds to one +post, then the idea is that you can call gemfeed from a regular +cronjob (or by hand after you write each post, if you like!) and +maintain an Atom feed for your gemlog with very little extra effort. + +Basically, when run Gemfeed will find all world-readable `.gmi` or +`.gemini` files in the current directory and add the 10 most recently +created ones to an Atom feed it will save to the file `atom.xml`. + +* Each file's creation time will be used as the corresponding entry's + update time. +* The first heading line in each file (i.e. the first line encountered + which begins with `#`, `##` or `###`) will be used as the + corresponding entry's title. If your file contains no heading line, + the filename will be used as a title instead, with its extension + removed. +* If an `index.gmi` or `index.gemini` file is found, it won't be + included as an entry in the feed, but the first heading line in the + index file will be used as the title for the feed. If your index + file contains no heading line, you'll get the dorky default "Just + another Gemini feed". + +The only information you *need* to provide to make this happen is a +base URL (with `-b` or `--base`). If you provide a base URL of +`gemini://example.org/my-gemlog/` then Gemfeed will assume that a +file it finds named `my-first-post.gmi` is accessible via the URL +`gemini://example.org/my-gemlog/my-first-post.gmi`, and that the file +it produces will be accessible via the URL +`gemini://example.org/my-gemlog/atom.xml`. Basically, you should +provide the URL which will your server will map to the directory +you're trying to generate a feed for. + +If you want to, you can provide additional information above and +beyond the base URL: + +* You can specify a directory other than the present working directory + with `-d` or `--directory`. +* You can specify a number of posts other than 10 with `-n` +* You can change the output filename with `-o` or `--output`. +* You can specify your own feed title and subtitle with `-t` or + `--title` and `-s` or `--subtitle`, respectively. If you specify a + title, it will override any heading line in your index file. +* You can specify an author name for the feed with `-a` or `--author` + and/or an author email address for the feed with `-e` or `--email`. +* If you specify `-q` or `--quiet`, Gemfeed will write nothing to + stdout unless there's a problem - ideal for cron jobs!