Redone moogle page.
[wikirepo] / projects / moogle / index.mdwn
1 ## Moogle - A curses based google reader client
2
3 Moogle is a curses client for google reader, influenced by the best MUA ever,
4 [Mutt][].  Like mutt moogle has keybindings for everything, and supports limit
5 expressions to restrict what you're shown.
6
7 Moogle was written to [scratch an itch][] - there were console rss
8 readers\[[1][], [2][]\] and GUI rss readers which can sync to google
9 reader\[[3][]\] and [Google Reader][] proper but no console reader which could
10 sync to google reader: enter moogle.
11
12 Moogle's not for everyone, as [Zed said][] (though he was talking about [newsbeuter][]):
13
14 > Now, I’m sure tons of people will scoff at the idea of not having graphics in
15 > their feed.  They’ve gotta have that curvy candy coated interface with the
16 > flash video about Steampunk Buttplugs posted by BoingBoing blaring right in
17 > their fucking face or else they don’t feel alive.  They don’t feel young.
18 > Dammit, they want to augment that Nerd ADD with a feed reader that goes to
19 > eleven!
20
21 If that sounds like you, maybe you won't like moogle.
22
23 [scratch an itch]: http://en.wikipedia.org/wiki/The_Cathedral_and_the_Bazaar
24 [Mutt]: http://www.mutt.org
25 [Zed said]: http://www.zedshaw.com/essays/i_want_the_mutt_of_feed_readers.html
26
27 [Google Reader]: http://google.com/reader
28 [1]: http://kiza.kcore.de/software/snownews/
29 [2]: http://www.newsbeuter.org/
30 [newsbeuter]: http://www.newsbeuter.org/
31 [3]: http://liferea.sourceforge.net/
32
33 ### Screenshot
34 <img src="moogle.png" alt="Moogle Screenshot"/>
35
36 ### Features
37
38 Why should you use moogle? 
39
40  * Google Reader synchronisation 
41  * Curses interface
42  * Powerful limit expressions
43  * Offline cache support
44  * Configurable keybindings
45  * Built in python command line
46
47 ### Getting Started
48
49 Using setting up moogle is simple: there are no configuration options, and only
50 one required configuration file, `~/.moogle/cred` which should contain your
51 google reader credentials in the form:
52
53         username@google.com,password
54
55 Moogle is a work in progress - to get going try `python frontend.py` in the
56 moogle directory, simple help is available by pressing "?".
57
58 ### Commands
59
60 The default set of commands is:
61
62         '*': star
63         ':': command
64         <down>: scroll_down
65         <space>: next_unread_message
66         <up>: scroll_up
67         '?': help
68         J: scroll_down
69         K: scroll_up
70         N: next_message
71         O: online
72         P: previous_message
73         R: read_tagged
74         T: tag_set
75         d: debug_dump_item
76         j: scroll_down
77         k: scroll_up
78         l: limit
79         n: next_message
80         o: open_item
81         p: previous_message
82         q: quit
83         s: save
84         t: tag
85         x: update
86
87 Most commands are simple, and do exactly what you'd expect.  Keybindings can be
88 created and modified at run time by using `Config.bind(key, function)`.
89
90 ### The Limit Command
91 Limit accepts a python expression and uses it to [filter][] the feed items
92 shown.  To only show items from the BBC try `Limit: "BBC" in item.feed` or to
93 show only items labelled "comics" `Limit: "comics" in item.labels`.  A full
94 list of item attributes can be seen in the [source][], or in the debug output
95 (bound to "d" by default).
96
97 [filter]: http://docs.python.org/library/functions.html#filter
98
99 Any python expression returning a boolean can be used as a limit expression,
100 but probably you'll want to limit based on some property of the each item.  Common attributes for an item are:
101
102  * `item.feed`:  The feed source
103  * `item.body`:  The body of the item, formatted as markdown
104  * `item.author`:  The author of the item
105  * `item.title`:  The item title
106  * `item.labels`:  A list of this item's labels
107  * `item.link`:  The link to the full version of this item
108  * `item.date`:  A [datetime][] object representing the time this item was written
109  * `item.entry`:  A [feedparser][] object representing this object
110
111 [datetime]: http://docs.python.org/library/datetime.html
112 [feedparser]: http://www.feedparser.org/
113
114 ### Config Save/Restore
115
116 Moogle now supports the saving and restoring of configuration to and from the
117 file `~/.moogle/config` in [YaML][].  Moogle will load an existing config file
118 during initialisation, to create a config file run `Config.save([filename])`,
119 and to run a new config run `Config.restore([filename])`.  The default
120 configuration looks like:
121
122         browser: x-www-browser
123         headers:
124         - labels
125         - author
126         - date
127         - feed
128         - title
129         history_file: /home/joe/.moogle/history
130         index_length: 5
131         keybindings:
132           '*': star
133           ':': command
134           <down>: scroll_down
135           <space>: next_unread_message
136           <up>: scroll_up
137           '?': help
138           J: scroll_down
139           K: scroll_up
140           N: next_message
141           O: online
142           P: previous_message
143           R: read_tagged
144           T: tag_set
145           d: debug_dump_item
146           j: scroll_down
147           k: scroll_up
148           l: limit
149           n: next_message
150           o: open_item
151           p: previous_message
152           q: quit
153           s: save
154           t: tag
155           x: update
156
157 The keys `<up>`, `<down>`, and `<space>` are mapped to `curses.KEY_UP`,
158 `curses.KEY_DOWN`, and `curses.KEY_SPACE` respectively.
159
160 [YaML]: http://www.yaml.org
161
162 ### Download
163
164 No packages yet - clone your own from [git](http://joe.milbourn.org.uk/git/projects/moogle).