Add README

1 files changed, 101 insertions, 0 deletions

@@ -0,0 +1,101 @@
+# gemshimfeed
+## an Atom feed generator in (mostly) POSIX shell
+
+Because of [this post in the Gemini mailing list](https://lists.orbitalfox.eu/archives/gemini/2020/003407.html),
+which bemoans the inability to generate Atom feeds using bare-bones computers,
+I present `gemshimfeed`, a shell program that purports to do just that.
+
+It has minimal dependencies (see DEPENDENCIES, below),
+and is completely modifiable by the user with the config file
+(see CONFIG, below).
+
+And it's licensed permissively.
+What more could you want!?
+
+## DEPENDENCIES
+
+- POSIX shell
+- POSIX awk (I'm 99% sure) - optional
+- GNU find - optional
+- stat - optional
+
+Technically, a shell is the only optional dependency --
+if you're removing shell from the dependencies list,
+you're writing another script.
+
+## CONFIG
+
+All of the functions and variables defined in `gemshimfeed`
+can be overwritten by a config file, by default
+`gemshimfeed.conf.sh` in the current directory.
+As may be obvious from the file's extension, it's a shell script,
+so you can redefine (and in fact, *should* redefine)
+all the variables and functions in `gemshimfeed` to suit your needs.
+
+Here's a convenient list:
+
+### Variables
+
+- **FEED_TITLE** - the title of your feed
+- **FEED_AUTHOR** - the author of your feed (you!)
+- **FEED_SUBTITLE** - the subtitle of your feed
+- **FEED_URL** - the URL where your feed can be accessed
+- **SITE_URL** - the base URL of your site
+- **FEED_ID** - the Atom ID of the feed (default: SITE_URL)
+- **FEED_COPYRIGHT** - the copyright information of your feed
+- **FEED_UPDATED** - the date your feed was last updated (default: the current time)
+
+### Functions
+
+#### File functions
+
+- **recent_files** - sort files recursively, in reverse
+
+#### Entry functions
+
+These operate on entries themselves, in the inner `for` loop of `main`.
+They're all passed the path of the entry.
+See the source for their default implementations.
+
+- **skip_entry** - whether to skip an entry (default: don't).  Return 0 to skip an entry.
+- **entry_url** - pull the URL out of an entry
+- **entry_title** - pull the title from an entry
+- **entry_summary** - pull the summary from an entry
+- **entry_author** - pull the author from an entry
+- **entry_content** - pull the content from an entry
+- **entry_updated** - pull the modification time from an entry
+
+#### Atom functions
+
+These generate the actual atom bits.
+Should be pretty self-explanatory.
+
+- **atom_header**
+- **atom_entry**
+- **atom_footer**
+
+## POSIX compliance
+
+This script should be 95% POSIX compliant.
+The only bits that aren't strictly so are the functions
+`recent_files`, which requires GNU `find` for the `-printf` option, 
+and possibly `entry_updated`, which uses `stat`.
+I've included commentary toward POSIX-ifying these if need be,
+but since this is a quick-and-dirty proof-of-concept,
+I leave actually doing so as an exercise to the reader.
+
+## Copyright
+
+(C) 2020 Case Duckworth.
+Licensed under the MIT license.
+See LICENSE for details.
+
+## Contributing
+
+Feel free to send patches, complaints, and praise
+to my [public inbox](mailto:~acdw/public-inbox@lists.sr.ht).
+
+## See also
+
+- [gemfeed](https://tildegit.org/solderpunk/gemfeed)
+- [RFC 4287](https://tools.ietf.org/html/rfc4287)