# shatom
## a feed generator in (mostly) POSIX shell

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.

**Now with RSS 2.0 abilities baked in!**

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

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, defaulting to the
  current time

### Functions

#### File functions

- **recent_files** - sort files recursively, in reverse

#### Item functions

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

#### Feed functions

These generate the actual feed bits.  Should be pretty self-explanatory.

- **feed_header**
- **feed_item**
- **feed_footer**

## POSIX compliance

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 Good Choices License.  See COPYING
for details.

## Contributing

Feel free to send patches, complaints, and praise to my
[email](mailto:git+shatom@acdw.net).

## See also

- [gemfeed](https://tildegit.org/solderpunk/gemfeed)
- [RFC 4287](https://tools.ietf.org/html/rfc4287)