1 files changed, 43 insertions, 53 deletions

@@ -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