shatom/README.md

# shatom
## 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 `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).

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 `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 (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)