From d8386840210b3d0cc42abd1692479b15d968b286 Mon Sep 17 00:00:00 2001 From: Case Duckworth Date: Tue, 2 Aug 2022 23:02:34 -0500 Subject: Update README --- README.md | 96 ++++++++++++++++++++++++++++----------------------------------- 1 file changed, 43 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 92ab758..3d085de 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,29 @@ # shatom -## an Atom feed generator in (mostly) POSIX shell +## a 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 `shatom`, a shell program that purports to do just that. +Because of a post in the Gemini mailing list bemoaning the inability to generate +Atom feeds using bare-bones computers, I present `shatom`, 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). +**Now with RSS 2.0 abilities baked in!** -And it's licensed permissively. -What more could you want!? +It has minimal dependencies (see DEPENDENCIES, below), and is completely +modifiable by the user with the config file (see CONFIG, below). -## DEPENDENCIES +And it's licensed permissively. What more could you want!? -- POSIX shell -- POSIX awk (I'm 99% sure) - optional -- GNU find - optional -- stat - optional +## DEPENDENCIES -Technically, a shell is the only optional dependency -- -if you're removing shell from the dependencies list, -you're writing another script. +- POSIX shell and tools +- `stat(1)` - optional, but nice to have for figuring out mtime ## CONFIG -All of the functions and variables defined in `shatom` -can be overwritten by a config file, by default -`shatom.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 `shatom` to suit your needs. +All of the functions and variables defined in `shatom` can be overwritten by a +config file, by default `shatom.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 `shatom` to suit +your needs. Here's a convenient list: @@ -43,7 +36,8 @@ Here's a convenient list: - **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) +- **FEED_UPDATED** - the date your feed was last updated, defaulting to the + current time ### Functions @@ -51,49 +45,45 @@ Here's a convenient list: - **recent_files** - sort files recursively, in reverse -#### Entry functions +#### Item 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. +These operate on items themselves, in the inner `for` loop of `main`. They're +all passed the path of the item. 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 +- **skip_item** - whether to skip an item (default: don't). Return 0 to skip + an item. +- **item_url** - pull the URL out of an item +- **item_title** - pull the title from an item +- **item_summary** - pull the summary from an item +- **item_author** - pull the author from an item +- **item_content** - pull the content from an item +- **item_updated** - pull the modification time from an item -#### Atom functions +#### Feed functions -These generate the actual atom bits. -Should be pretty self-explanatory. +These generate the actual feed bits. Should be pretty self-explanatory. -- **atom_header** -- **atom_entry** -- **atom_footer** +- **feed_header** +- **feed_item** +- **feed_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. +As it is written in this repo, shatom is 99% POSIX-compliant: of 176 source +lines, only 2 require a non-POSIX tool, `stat(1)`. Of course, you can change +these functions to be whatever you like, so you don't have to make it +POSIX-compliant if you don't want to. Go nuts! ## Copyright -(C) 2020 Case Duckworth. -Licensed under the MIT license. -See LICENSE for details. +(C) 2020 Case Duckworth. Licensed under the Good Choices License. See COPYING +for details. ## Contributing -Feel free to send patches, complaints, and praise -to my [public inbox](mailto:~acdw/public-inbox@lists.sr.ht). +Feel free to send patches, complaints, and praise to my +[email](mailto:git+shatom@acdw.net). ## See also -- cgit 1.4.1-21-gabe81