Redone moogle page.
authorJoe Milbourn <joe.milbourn+git@gmail.com>
Mon, 26 Oct 2009 11:49:47 +0000 (11:49 +0000)
committerJoe Milbourn <joe.milbourn+git@gmail.com>
Mon, 26 Oct 2009 11:49:47 +0000 (11:49 +0000)
projects/moogle/index.mdwn

index fdb909e..7f3a658 100644 (file)
@@ -4,16 +4,30 @@ Moogle is a curses client for google reader, influenced by the best MUA ever,
 [Mutt][].  Like mutt moogle has keybindings for everything, and supports limit
 expressions to restrict what you're shown.
 
-Moogle was written to [scratch an itch][] - there were console rss readers\[[1][], [2][]\] and GUI rss readers which can sync to google reader\[[3][]\]
-and [Google Reader][] proper but no console reader which could sync to google
-reader: enter moogle.
+Moogle was written to [scratch an itch][] - there were console rss
+readers\[[1][], [2][]\] and GUI rss readers which can sync to google
+reader\[[3][]\] and [Google Reader][] proper but no console reader which could
+sync to google reader: enter moogle.
+
+Moogle's not for everyone, as [Zed said][] (though he was talking about [newsbeuter][]):
+
+> Now, I’m sure tons of people will scoff at the idea of not having graphics in
+> their feed.  They’ve gotta have that curvy candy coated interface with the
+> flash video about Steampunk Buttplugs posted by BoingBoing blaring right in
+> their fucking face or else they don’t feel alive.  They don’t feel young.
+> Dammit, they want to augment that Nerd ADD with a feed reader that goes to
+> eleven!
+
+If that sounds like you, maybe you won't like moogle.
 
 [scratch an itch]: http://en.wikipedia.org/wiki/The_Cathedral_and_the_Bazaar
 [Mutt]: http://www.mutt.org
+[Zed said]: http://www.zedshaw.com/essays/i_want_the_mutt_of_feed_readers.html
 
 [Google Reader]: http://google.com/reader
-[1]: http://kiza.kcore.de/software/snownews/ 
-[2]: http://www.newsbeuter.org/ 
+[1]: http://kiza.kcore.de/software/snownews/
+[2]: http://www.newsbeuter.org/
+[newsbeuter]: http://www.newsbeuter.org/
 [3]: http://liferea.sourceforge.net/
 
 ### Screenshot
@@ -28,109 +42,82 @@ Why should you use moogle?
  * Powerful limit expressions
  * Offline cache support
  * Configurable keybindings
+ * Built in python command line
 
-### Using Moogle
+### Getting Started
 
 Using setting up moogle is simple: there are no configuration options, and only
-one configuration file, `~/.moogle/cred` which should contain your google reader credentials
-in the form:
+one required configuration file, `~/.moogle/cred` which should contain your
+google reader credentials in the form:
 
        username@google.com,password
 
 Moogle is a work in progress - to get going try `python frontend.py` in the
-moogle directory, simple help is available by pressing "?".  
-
-Most commands are simple, and do exactly what you'd expect, "limit" accepts a
-python expression and uses it to [filter][] the feed items shown.  To only show
-items from the BBC try `Limit: "BBC" in item.feed` or to show only items
-labelled "comics" `Limit: "comics" in item.labels`.  A full list of item
-attributes can be seen in the [source][], or in the debug output (bound to
-"d").
+moogle directory, simple help is available by pressing "?".
+
+### Commands
+
+The default set of commands is:
+
+       '*': star
+       ':': command
+       <down>: scroll_down
+       <space>: next_unread_message
+       <up>: scroll_up
+       '?': help
+       J: scroll_down
+       K: scroll_up
+       N: next_message
+       O: online
+       P: previous_message
+       R: read_tagged
+       T: tag_set
+       d: debug_dump_item
+       j: scroll_down
+       k: scroll_up
+       l: limit
+       n: next_message
+       o: open_item
+       p: previous_message
+       q: quit
+       s: save
+       t: tag
+       x: update
+
+Most commands are simple, and do exactly what you'd expect.  Keybindings can be
+created and modified at run time by using `Config.bind(key, function)`.
+
+### The Limit Command
+Limit accepts a python expression and uses it to [filter][] the feed items
+shown.  To only show items from the BBC try `Limit: "BBC" in item.feed` or to
+show only items labelled "comics" `Limit: "comics" in item.labels`.  A full
+list of item attributes can be seen in the [source][], or in the debug output
+(bound to "d" by default).
 
 [filter]: http://docs.python.org/library/functions.html#filter
-[source]: http://joesbox.vm.bytemark.co.uk/cgi-bin/viewvc.cgi/moogle/moogle.py?root=src&view=markup
-
-#### Limit Expressions
-
-Moogle supports python expressions to limit the items shown in the index.  The
-expression must return a boolean value, for example to show only unread items
-`'read' not in item.labels`.  The item properties available are:
-
-       item.feed 
-       item.body
-       item.author
-       item.title
-       item.labels
-       item.link
-       item.date
-       item.entry
-
-
-#### Commands
-<table>
-<tr><td><pre>Commands.add_label</pre></td>
-       <td>Prompts for a label to add to the currently selected item.</td></tr>
-<tr><td><pre>Commands.command</pre></td>
-       <td>Run a python expression with access to the internal state.</td></tr>
-<tr><td><pre>Commands.edit_labels</pre></td>
-       <td>Edit the labels for the currently selected item.</td></tr>
-<tr><td><pre>Commands.help</pre></td>
-       <td>Show help.</td></tr>
-<tr><td><pre>Commands.limit</pre></td>
-       <td>Apply a limit expression to the items shown in the index.</td></tr>
-<tr><td><pre>Commands.next_message</pre></td>
-       <td>Select the next message.</td></tr>
-<tr><td><pre>Commands.next_unread_message</pre></td>
-       <td>Select the next unread message.</td></tr>
-<tr><td><pre>Commands.online</pre></td>
-       <td>Toggle the online/offline state.</td></tr>
-<tr><td><pre>Commands.open_item</pre></td>
-       <td>Open the selected item using `x-www-browser`.</td></tr>
-<tr><td><pre>Commands.previous_message</pre></td>
-       <td>Select the previous message.</td></tr>
-<tr><td><pre>Commands.quit</pre></td>
-       <td>Quit.</td></tr>
-<tr><td><pre>Commands.save_history</pre></td>
-       <td>Save the current command histories to a named file.</td></tr>
-<tr><td><pre>Commands.scroll_down</pre></td>
-       <td>Scroll the selected message body.</td></tr>
-<tr><td><pre>Commands.scroll_up</pre></td>
-       <td>Scroll the selected message body.</td></tr>
-<tr><td><pre>Commands.star</pre></td>
-       <td>Toggle the 'starred' status of the selected item.</td></tr>
-<tr><td><pre>Commands.toggle_label</pre></td>
-       <td>Toggle the given item for the selected item.</td></tr>
-<tr><td><pre>Commands.update</pre></td>
-       <td>Synchronise with google reader.</td></tr>
-</table>
-
-#### Default Keybindings
-<table>
-<tr><td>Key</td><td>Action</td></tr>
-<tr><td><code>:</code></td><td>Execute python command in the context of this program.</td></tr>
-<tr><td><code>j</code></td><td>Scroll the current item down.</td></tr>
-<tr><td><code>J</code></td><td>Scroll the current item down.</td></tr>
-<tr><td><code>k</code></td><td>Scroll the current item up.</td></tr>
-<tr><td><code>K</code></td><td>Scroll the current item up.</td></tr>
-<tr><td><code>l</code></td><td>Limit the display of items according to an expression.</td></tr>
-<tr><td><code>n</code></td><td>Select the next message.</td></tr>
-<tr><td><code>N</code></td><td>Select the next message.</td></tr>
-<tr><td><code>o</code></td><td>Open the currently selected item</td></tr>
-<tr><td><code>O</code></td><td>Toggle the online state.</td></tr>
-<tr><td><code>p</code></td><td>Select the previous message.</td></tr>
-<tr><td><code>P</code></td><td>Select the previous message.</td></tr>
-<tr><td><code>q</code></td><td>Quit.</td></tr>
-<tr><td><code>?</code></td><td>Show help.</td></tr>
-<tr><td><code>space</code></td><td>Select the next unread item.</td></tr>
-<tr><td><code>T</code></td><td>Edit labels for the selected item.</td></tr>
-<tr><td><code>*</code></td><td>Toggle 'star' state of the selected item.</td></tr>
-<tr><td><code>x</code></td><td>Force an update.</td></tr>
-</table>
-
-#### Config Save/Restore
+
+Any python expression returning a boolean can be used as a limit expression,
+but probably you'll want to limit based on some property of the each item.  Common attributes for an item are:
+
+ * `item.feed`:  The feed source
+ * `item.body`:  The body of the item, formatted as markdown
+ * `item.author`:  The author of the item
+ * `item.title`:  The item title
+ * `item.labels`:  A list of this item's labels
+ * `item.link`:  The link to the full version of this item
+ * `item.date`:  A [datetime][] object representing the time this item was written
+ * `item.entry`:  A [feedparser][] object representing this object
+
+[datetime]: http://docs.python.org/library/datetime.html
+[feedparser]: http://www.feedparser.org/
+
+### Config Save/Restore
 
 Moogle now supports the saving and restoring of configuration to and from the
-file `~/.moogle/config` in [YaML][].  The default configuration looks like:
+file `~/.moogle/config` in [YaML][].  Moogle will load an existing config file
+during initialisation, to create a config file run `Config.save([filename])`,
+and to run a new config run `Config.restore([filename])`.  The default
+configuration looks like:
 
        browser: x-www-browser
        headers: