Initial lektor documentation

README.md

@@ -0,0 +1,122 @@
+# Lektor: A Standard for Feed Readers
+
+**NOTE:** The entirety of this file is tentative, and subject to change
+at any time.
+
+There are two main tasks for a feed reader: _fetching_ and _viewing_.
+These two tasks, in the `lektor` system, are split apart into different
+components, mediated by a `lektordir` system. There are two main parts
+to the `lektor` architecture: the `lektor-dir` format and the
+`lektor-entry` format.
+
+## `lektor-feed`
+
+A given `feed` consists of at least a `name` (which is human-readable)
+and an `id` which unambiguously identifies the `feed` (which is
+a URI). Information about `feed`s is stored in the `src` directory
+inside a `lektor-dir`. Information about a given feed is stored inside
+`src/$hash`, where `$hash` is the SHA-1 hash of of the `feed`'s `id`.
+
+Obligatory elements include:
+
+- `id`: The URI which identifies the feed. In the case of
+RSS/Atom/ActivityStream feeds, this will generally be the URL at
+which the feed is hosted. For other things—for example, for
+services which may not have a web equivalent—it might instead be
+a tag URI or some other opaque identifier.
+- `name`: The human-readable name of the feed. This is
+produced by the fetcher and should not be changed by a viewer.
+
+Optional elements include:
+
+- `description`: A human-readable description describing
+the feed.
+- `language`: The language the feed is written in.
+- `image`: An image that can be optionally displayed with
+the channel.
+- `copyright`: The copyright notice for the feed.
+- `author`: Authorship information for the feed.
+
+### Feed example
+
+A minimal feed might look like
+
+```.bash
+cd $LEKTORDIR
+HASH=$(printf 'http://example.com/rss.xml' | sha1sum)
+mkdir -p $HASH
+
+echo http://example.com/rss.xml  >$HASH/id
+echo Example Feed                >$HASH/name
+```
+
+A feed with more entries might look like
+
+```.bash
+cd $LEKTORDIR
+HASH=$(printf 'http://example.com/rss.xml' | sha1sum)
+mkdir -p $HASH
+
+echo http://example.com/rss.xml           >$HASH/id
+echo Example Feed                         >$HASH/name
+echo 'An example feed.'                   >$HASH/description
+echo en-us                                >$HASH/language
+echo http://example.com/image.png         >$HASH/image
+echo Copyright 2015, Getty Ritter         >$HASH/copyright
+echo 'Getty Ritter <gdritter@gmail.com>'  >$HASH/author
+```
+
+## `lektor-entry`
+
+In contrast to `maildir`, entries in a `lektor-dir` are not files
+but directories adhering to a particular structure.
+
+Obligatory elements include:
+
+- `title`: The title of the entry.
+- `id`: The URI which identifies the entry. This will often be a
+URL at which the resource corresponding to the entry is available,
+but may also be an opaque identifier.
+- `content`: TBD
+- `feed`: A directory that contains all the information about the
+source `feed`. This will generally be a symlink 
+
+Optional elements include:
+
+- `author`: Names and email addressess of the authors of the entry.
+- `pubdate`: When the entry was published.
+
+## `lektor-dir`
+
+A `lektordir` is a directory with at least four subdirectories: `tmp`,
+`new`, `cur`, and `src`. A _fetcher_ is responsible for examining a feed
+and adding new entries the `lektordir` according to the following process:
+
+- The fetcher `chdir()`s to the `lektordir` directory.
+- The fetcher `stat()`s the name `tmp/$feed/$time.$pid.$host`, where
+`$feed` is the hash of the feed's `id` value, `$time`
+is the number of seconds since the beginning of 1970 GMT, `$pid` is the
+program's process ID, and `$host` is its host name.
+- If `stat()` returned anything other than `ENOENT`, the program sleeps
+for two seconds, updates `$time`, and tries the `stat()` again, a limited
+number of times.
+- The fetcher creates the directory `tmp/$feed/$time.$pid.$host`.
+- The fetcher writes the entry contents (according to the `lektor-entry`
+format) to the directory.
+- The fetcher `link()`s the file to `new/$feed/$time.$pid.$host`. At that
+instant, the entry has been successfully created.
+
+A _viewer_ is responsible for displaying new feed entries to a user
+through some mechanism. A viewer looks through the `new` directory for
+new entries. If there is a new entry, `new/$feed/$unique`, the viewer may:
+
+- Display the contents of `new/$feed/$unique`
+- Delete `new/$feed/$unique`
+- Rename `new/$feed/$unique`.
+
+A `lektordir` can contain arbitrary other directories, but for the sake
+of compatibility, these should attempt to adhere to the following
+schema:
+
+- If the extra directory contains configuration or other information
+for a given feed, it