about summary refs log tree commit diff stats
diff options
context:
space:
mode:
-rw-r--r--README.md101
1 files changed, 101 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..c2c1bc6 --- /dev/null +++ b/README.md
@@ -0,0 +1,101 @@
1# gemshimfeed
2## an Atom feed generator in (mostly) POSIX shell
3
4Because of [this post in the Gemini mailing list](https://lists.orbitalfox.eu/archives/gemini/2020/003407.html),
5which bemoans the inability to generate Atom feeds using bare-bones computers,
6I present `gemshimfeed`, a shell program that purports to do just that.
7
8It has minimal dependencies (see DEPENDENCIES, below),
9and is completely modifiable by the user with the config file
10(see CONFIG, below).
11
12And it's licensed permissively.
13What more could you want!?
14
15## DEPENDENCIES
16
17- POSIX shell
18- POSIX awk (I'm 99% sure) - optional
19- GNU find - optional
20- stat - optional
21
22Technically, a shell is the only optional dependency --
23if you're removing shell from the dependencies list,
24you're writing another script.
25
26## CONFIG
27
28All of the functions and variables defined in `gemshimfeed`
29can be overwritten by a config file, by default
30`gemshimfeed.conf.sh` in the current directory.
31As may be obvious from the file's extension, it's a shell script,
32so you can redefine (and in fact, *should* redefine)
33all the variables and functions in `gemshimfeed` to suit your needs.
34
35Here's a convenient list:
36
37### Variables
38
39- **FEED_TITLE** - the title of your feed
40- **FEED_AUTHOR** - the author of your feed (you!)
41- **FEED_SUBTITLE** - the subtitle of your feed
42- **FEED_URL** - the URL where your feed can be accessed
43- **SITE_URL** - the base URL of your site
44- **FEED_ID** - the Atom ID of the feed (default: SITE_URL)
45- **FEED_COPYRIGHT** - the copyright information of your feed
46- **FEED_UPDATED** - the date your feed was last updated (default: the current time)
47
48### Functions
49
50#### File functions
51
52- **recent_files** - sort files recursively, in reverse
53
54#### Entry functions
55
56These operate on entries themselves, in the inner `for` loop of `main`.
57They're all passed the path of the entry.
58See the source for their default implementations.
59
60- **skip_entry** - whether to skip an entry (default: don't). Return 0 to skip an entry.
61- **entry_url** - pull the URL out of an entry
62- **entry_title** - pull the title from an entry
63- **entry_summary** - pull the summary from an entry
64- **entry_author** - pull the author from an entry
65- **entry_content** - pull the content from an entry
66- **entry_updated** - pull the modification time from an entry
67
68#### Atom functions
69
70These generate the actual atom bits.
71Should be pretty self-explanatory.
72
73- **atom_header**
74- **atom_entry**
75- **atom_footer**
76
77## POSIX compliance
78
79This script should be 95% POSIX compliant.
80The only bits that aren't strictly so are the functions
81`recent_files`, which requires GNU `find` for the `-printf` option,
82and possibly `entry_updated`, which uses `stat`.
83I've included commentary toward POSIX-ifying these if need be,
84but since this is a quick-and-dirty proof-of-concept,
85I leave actually doing so as an exercise to the reader.
86
87## Copyright
88
89(C) 2020 Case Duckworth.
90Licensed under the MIT license.
91See LICENSE for details.
92
93## Contributing
94
95Feel free to send patches, complaints, and praise
96to my [public inbox](mailto:~acdw/public-inbox@lists.sr.ht).
97
98## See also
99
100- [gemfeed](https://tildegit.org/solderpunk/gemfeed)
101- [RFC 4287](https://tools.ietf.org/html/rfc4287)