about summary refs log tree commit diff stats
diff options
context:
space:
mode:
-rw-r--r--README.md96
1 files changed, 43 insertions, 53 deletions
diff --git a/README.md b/README.md index 92ab758..3d085de 100644 --- a/README.md +++ b/README.md
@@ -1,36 +1,29 @@
1# shatom 1# shatom
2## an Atom feed generator in (mostly) POSIX shell 2## a feed generator in (mostly) POSIX shell
3 3
4Because of [this post in the Gemini mailing list](https://lists.orbitalfox.eu/archives/gemini/2020/003407.html), 4Because of a post in the Gemini mailing list bemoaning the inability to generate
5which bemoans the inability to generate Atom feeds using bare-bones computers, 5Atom feeds using bare-bones computers, I present `shatom`, a shell program that
6I present `shatom`, a shell program that purports to do just that. 6purports to do just that.
7 7
8It has minimal dependencies (see DEPENDENCIES, below), 8**Now with RSS 2.0 abilities baked in!**
9and is completely modifiable by the user with the config file
10(see CONFIG, below).
11 9
12And it's licensed permissively. 10It has minimal dependencies (see DEPENDENCIES, below), and is completely
13What more could you want!? 11modifiable by the user with the config file (see CONFIG, below).
14 12
15## DEPENDENCIES 13And it's licensed permissively. What more could you want!?
16 14
17- POSIX shell 15## DEPENDENCIES
18- POSIX awk (I'm 99% sure) - optional
19- GNU find - optional
20- stat - optional
21 16
22Technically, a shell is the only optional dependency -- 17- POSIX shell and tools
23if you're removing shell from the dependencies list, 18- `stat(1)` - optional, but nice to have for figuring out mtime
24you're writing another script.
25 19
26## CONFIG 20## CONFIG
27 21
28All of the functions and variables defined in `shatom` 22All of the functions and variables defined in `shatom` can be overwritten by a
29can be overwritten by a config file, by default 23config file, by default `shatom.conf.sh` in the current directory. As may be
30`shatom.conf.sh` in the current directory. 24obvious from the file's extension, it's a shell script, so you can redefine (and
31As may be obvious from the file's extension, it's a shell script, 25in fact, *should* redefine) all the variables and functions in `shatom` to suit
32so you can redefine (and in fact, *should* redefine) 26your needs.
33all the variables and functions in `shatom` to suit your needs.
34 27
35Here's a convenient list: 28Here's a convenient list:
36 29
@@ -43,7 +36,8 @@ Here's a convenient list:
43- **SITE_URL** - the base URL of your site 36- **SITE_URL** - the base URL of your site
44- **FEED_ID** - the Atom ID of the feed (default: SITE_URL) 37- **FEED_ID** - the Atom ID of the feed (default: SITE_URL)
45- **FEED_COPYRIGHT** - the copyright information of your feed 38- **FEED_COPYRIGHT** - the copyright information of your feed
46- **FEED_UPDATED** - the date your feed was last updated (default: the current time) 39- **FEED_UPDATED** - the date your feed was last updated, defaulting to the
40 current time
47 41
48### Functions 42### Functions
49 43
@@ -51,49 +45,45 @@ Here's a convenient list:
51 45
52- **recent_files** - sort files recursively, in reverse 46- **recent_files** - sort files recursively, in reverse
53 47
54#### Entry functions 48#### Item functions
55 49
56These operate on entries themselves, in the inner `for` loop of `main`. 50These operate on items themselves, in the inner `for` loop of `main`. They're
57They're all passed the path of the entry. 51all passed the path of the item. See the source for their default
58See the source for their default implementations. 52implementations.
59 53
60- **skip_entry** - whether to skip an entry (default: don't). Return 0 to skip an entry. 54- **skip_item** - whether to skip an item (default: don't). Return 0 to skip
61- **entry_url** - pull the URL out of an entry 55 an item.
62- **entry_title** - pull the title from an entry 56- **item_url** - pull the URL out of an item
63- **entry_summary** - pull the summary from an entry 57- **item_title** - pull the title from an item
64- **entry_author** - pull the author from an entry 58- **item_summary** - pull the summary from an item
65- **entry_content** - pull the content from an entry 59- **item_author** - pull the author from an item
66- **entry_updated** - pull the modification time from an entry 60- **item_content** - pull the content from an item
61- **item_updated** - pull the modification time from an item
67 62
68#### Atom functions 63#### Feed functions
69 64
70These generate the actual atom bits. 65These generate the actual feed bits. Should be pretty self-explanatory.
71Should be pretty self-explanatory.
72 66
73- **atom_header** 67- **feed_header**
74- **atom_entry** 68- **feed_item**
75- **atom_footer** 69- **feed_footer**
76 70
77## POSIX compliance 71## POSIX compliance
78 72
79This script should be 95% POSIX compliant. 73As it is written in this repo, shatom is 99% POSIX-compliant: of 176 source
80The only bits that aren't strictly so are the functions 74lines, only 2 require a non-POSIX tool, `stat(1)`. Of course, you can change
81`recent_files`, which requires GNU `find` for the `-printf` option, 75these functions to be whatever you like, so you don't have to make it
82and possibly `entry_updated`, which uses `stat`. 76POSIX-compliant if you don't want to. Go nuts!
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 77
87## Copyright 78## Copyright
88 79
89(C) 2020 Case Duckworth. 80(C) 2020 Case Duckworth. Licensed under the Good Choices License. See COPYING
90Licensed under the MIT license. 81for details.
91See LICENSE for details.
92 82
93## Contributing 83## Contributing
94 84
95Feel free to send patches, complaints, and praise 85Feel free to send patches, complaints, and praise to my
96to my [public inbox](mailto:~acdw/public-inbox@lists.sr.ht). 86[email](mailto:git+shatom@acdw.net).
97 87
98## See also 88## See also
99 89