Add README
This commit is contained in:
parent
4ab4980462
commit
29ef191b1b
|
@ -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)
|
Loading…
Reference in New Issue