New command table.
[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  * Mutt-like tagging of items
47
48 ### Getting Started
49
50 Using setting up moogle is simple: there are no configuration options, and only
51 one required configuration file, `~/.moogle/cred` which should contain your
52 google reader credentials in the form:
53
54         username@google.com,password
55
56 Moogle is a work in progress - to get going try `python frontend.py` in the
57 moogle directory, simple help is available by pressing "?".
58
59 ### Commands
60
61 The default set of commands is:
62
63         <space>:  Select the next unread item.
64         *:  Toggle 'star' state of the selected item.
65         ::  Execute python command in the context of this program.  DANGEROUS
66         ?:  Show help.
67         J:  Scroll the current item down.
68         K:  Scroll the current item up.
69         N:  Select the next message.
70         O:  Toggle the online state.
71         P:  Select the previous message.
72         R:  Mark all tagged items as read.
73         T:  Toggle the 'tagged' state for all items matching expr.
74         d:  Print a debug summary of the selected item.
75         j:  Scroll the current item down.
76         k:  Scroll the current item up.
77         l:  Limit the display of items according to an expression.
78         n:  Select the next message.
79         o:  Open the currently selected item
80         p:  Select the previous message.
81         q:  Quit.
82         s:  Save the current items for offline reading.
83         t:  Toggle 'tagged' state of an item.
84         x:  Force an update.
85
86 Most commands are simple, and do exactly what you'd expect.  Keybindings can be
87 created and modified at run time by using `Config.bind(key, function)`.
88
89 ### The Limit Command
90 Limit accepts a python expression and uses it to [filter][] the feed items
91 shown.  To only show items from the BBC try `Limit: "BBC" in item.feed` or to
92 show only items labelled "comics" `Limit: "comics" in item.labels`.  A full
93 list of item attributes can be seen in the [source][], or in the debug output
94 (bound to "d" by default).
95
96 [filter]: http://docs.python.org/library/functions.html#filter
97 [source]: http://joe.milbourn.org.uk/git?p=moogle;a=blob_plain;f=moogle.py;hb=HEAD
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).