doc clarification
Getty Ritter
9 years ago
| 1 | 1 | # Lektor: A Standard for Feed Readers |
| 2 | 2 | |
| 3 | **NOTE:** The entirety of this file is tentative, and subject to change | |
| 4 | at any time. | |
| 5 | ||
| 6 | There are two main tasks for a feed reader: _fetching_ and _viewing_. | |
| 7 | These two tasks, in the `lektor` system, are split apart into different | |
| 8 | components, mediated by a `lektor-dir` system. A `lektor-dir` contains | |
| 9 | two kinds of information: information about feeds (sources of new | |
| 10 | entries) and information about entries themselves. | |
| 11 | ||
| 12 | 3 | # At A Glance |
| 13 | 4 | |
| 14 | 5 | A given user has their own `lektor-dir`. A `lektor-dir` contains both |
| 15 |
"feeds" and "entries". Two kinds of programs operate on `lektor |
|
| 6 | "feeds" and "entries". Two kinds of programs operate on `lektor-dir`s | |
| 16 | 7 | in two different capcities: a _fetcher_ produces entries for one or |
| 17 | 8 | more feeds, and a _viewer_ manages entries once produced and shows |
| 18 | 9 | them to some user. A given `lektor-dir` can have multiple fetchers |
| 41 | 32 | |
| 42 | 33 | ## `lektor-feed` |
| 43 | 34 | |
| 44 | A given `feed` consists of at least a `name` (which is human-readable) | |
| 45 | and an `id` which unambiguously identifies the `feed` (which is | |
| 46 | a URI). Information about `feed`s is stored in the `src` directory | |
| 35 | A given `feed` consists of at least a human-readable `name` | |
| 36 | and a URI `id` which unambiguously identifies the `feed`. | |
| 37 | Information about `feed`s is stored in the `src` directory | |
| 47 | 38 | inside a `lektor-dir`. Information about a given feed is stored inside |
| 48 | 39 | `src/$hash`, where `$hash` is the SHA-1 hash of of the `feed`'s `id`. |
| 49 | 40 | |
| 53 | 44 | RSS/Atom/ActivityStream feeds, this will generally be the URL at |
| 54 | 45 | which the feed is hosted. For other things—for example, for |
| 55 | 46 | services which may not have a web equivalent—it might instead be |
| 56 |
a |
|
| 47 | a [tag URI](http://tools.ietf.org/html/rfc4151) or some other | |
| 48 | opaque identifier. | |
| 57 | 49 | - `name`: The human-readable name of the feed. This is |
| 58 |
produced by the fetcher and should not be changed by a viewer |
|
| 50 | produced by the fetcher and should not be changed by a viewer, | |
| 51 | even if a user wants to alias the name to something else. | |
| 59 | 52 | |
| 60 | 53 | Optional elements for a `feed` include: |
| 61 | 54 | |
| 223 | 216 | # create entries every hour |
| 224 | 217 | while true; do |
| 225 | 218 | TIME=$(date '+%s') |
| 226 |
ENTRY="$HASH/$TIME. |
|
| 219 | ENTRY="$HASH/$TIME.P$$.$HOST" | |
| 227 | 220 | |
| 228 | 221 | # if the file exists, wait two seconds and try again |
| 229 | 222 | RETRY=0 |