doc/UserGuide.txt in sup-0.0.4 vs doc/UserGuide.txt in sup-0.0.5

@@ -1,54 +1,212 @@
 Welcome to Sup! Here's how to actually use it.
 
-To get started, just run 'sup'. Assuming this is your first time,
-you'll be confronted with a mostly blank screen, and a little message
-at the bottom telling you that you have no messages. That's because
-Sup doesn't have any messages in its index. In order to add messages,
-Sup needs to have some "sources" from which to load messages.
+First, try running 'sup'. Assuming this is your first time, you'll be
+confronted with a mostly blank screen, and a notice at the bottom that
+you have no new messages. That's because Sup doesn't have any messages
+in its index yet, and has no idea where to look for them anyways.
 
 If you want to play around a little at this point, you can press 'b'
 to cycle between buffers and 'x' to kill a buffer. There's probably
 not too much interesting there, but there's a log buffer with some
 cryptic messages. You can also press '?' at any point to get a list of
 keyboard commands, but in the absense of any email, these will be
-pretty useless. When you're done, press 'q' to quit.
+mostly useless. When you're bored, press 'q' to quit.
 
-Now let's add a source to Sup. Run sup-import with a URI pointing to
-an email source. The URI should be of the form:
+We need to add some messages to Sup. In order for Sup to know about a
+message, it must be in the index. In order for Sup to load a message
+into the index, it must know about the "source" in which it
+resides. Sup stores all information necessary for search, and all
+state we have about a message, in the index, but doesn't duplicate the
+actual contents of the message itself. So when you search for messages
+or view your inbox, Sup just talks to the index (stored locally on
+disk), but when you view a message, Sup must request it from the
+source.
+
+So let's tell Sup about some sources. Run 'sup-import' with a URI
+pointing to an email source. The URI should be of the form:
 - mbox://path/to/a/filename, for an mbox file on disk. (You can also
   just provide the filename).
 - imap://imap.server/folder or imaps://secure.imap.server/folder for
-  an IMAP server.
+  an IMAP folder. (Leave the folder blank for INBOX.)
 - mbox+ssh://remote.machine/path/to/a/filename for a remote mbox file.
 
-Note: sup-import tries to be smart about setting the labels on
-      messages that it adds (including the special labels "unread" and
-      "inbox"). There are options that control this behavior, and it's
-      worth taking a look at the output of sup-import --help to make
-      sure that you don't end up with 1000 new messages that you've
-      actually already read.
+Before you actually import messages, you need to decide whether you
+want them to be archived or not. An archived message will not show up
+in your inbox. (Your inbox in Sup is, by definition, the set of all
+all non-archived messages). If you specify --force-archive, messages
+imported at *this* time will be archived, but new messages will go to
+your inbox. If you specify --archive, messages imported at *any* time
+will be automatically archived. (This is useful for sources that
+contain high-traffic mailing lists that you don't want "polluting"
+your inbox.)
 
-If sup-import requires a username and password for the source, it will
-prompt you for one. Either way, it will start loading messages from
-that source into the index. Depending on the size of the source, this
-may take some time. Don't worry! This is a one-time step, and all the
-computation done now makes operating on the index faster.
+Typically you'll want to specify --archive for every source you import
+except your actual inbox. You can also force all messages to be marked
+as read; run sup-import --help for details. The default is to preserve
+the read/unread status from the source.
 
+Now run sup-import to add the source. If it requires a username and
+password for the source, it will prompt you. Either way, it will add
+the sources to Sup, and immediately start loading messages from them
+into the index. Depending on the size of the source, this may take a
+while. Don't panic! It's a one-time process.
+
 Now, before we run 'sup' again, take a moment to edit your
 ~/.sup/config.yaml file. Replace "Your Name Here" with your name,
 "[e-mail]" with your email address, and fill in your
 .signature file if you choose. You can also set the default editor.
 
-Now run 'sup'. You should messages being loaded into your "inbox!"
-There are two things that are worth understanding at this point.
-First, Sup does not actually use folders. Instead, messages can have
-any number of labels applied to them. Rather than viewing a folder,
-you view the results of a search. So your inbox is simply the set of
-messages that have the 'inbox' label applied to them.
+We're finally ready to run 'sup'. You should see the most recent
+loaded messages appear in your inbox. Congratulations, you've got Sup
+working!
 
-Second, Sup groups together messages into threads. You rarely operate
-on an individual message in Sup.
+If you're coming from the world of traditional email, there are a
+couple differences you should be aware of at this point. First, Sup
+does not use folders. Instead, you organize and find messages by a
+combination of search and labels (knowns as 'tags' everywhere else in
+the world). I like to say that 95% of the functionality of folders is
+superceded by a quick, easy-to-access, and powerful search mechanism,
+and the other 5% by labels. (The Sup statement of philosophy has a
+little more on this.)
 
-Press enter to view a thread. 
+Search and labels are an integral part of Sup because in Sup, rather
+than viewing the contents of a folder, you view the results of a
+search. I mentioned above that your inbox is, by definition, the set
+of all messages that aren't archived. This means that your inbox is,
+in fact, the result of the search for "all messages without the label
+'archive'". It's actually slightly more complicated---we omit killed,
+deleted and spam messages as well.
 
-To be continued...
+So you could replicate the folder paradigm easily under this scheme,
+by giving each message exactly one label and only viewing the results
+of simple searches for those labels. But you'd quickly find out that
+life can be easier than that if you just trust the search engine, and
+use labels judiciously for things that are too hard to find with
+search.
+
+But enough chit-chat! Let's take a look at your inbox. You'll see that
+Sup groups messages together into threads: each line in the inbox is a
+thread, and the number in parentheses is the number of messages in
+that thread. (If there's no number in parens, it means there's just
+one message.) In Sup, you rarely operate on an individual message. The
+idea is that you rarely want to operate on a message independent of
+its context; you typically want to view, archive, kill, or label all
+the messages in a thread at one time.
+
+Use the up and down arrows to highlight a thread. ('j' and 'k' do the
+same thing, and 'J' and 'K' will scroll the whole window.  Even the
+left and right arrow keys work!) By default, Sup only loads as many
+threads as it takes to fill the window; if you'd like to load more,
+press 'M'. You can hit tab to cycle between only threads with new
+messages.
+
+Highlight a thread and press enter to view it. You'll notice that all
+messages in the thread are displayed together, layed out graphically
+by their relationship to each other (replies are nested under
+parents). By default, only the new messages in a thread are expanded,
+and the others are hidden. You can toggle an individual message's
+state by highlighting a green line and pressing enter. You can use 'E'
+to expand or collapse all messages or 'N' to expand only the new
+messages. You'll also notice that Sup hides quoted text and
+signatures. If you highlight a particular hidden chunk, you can press
+enter to expand it, or you can press 'o' to toggle every hidden chunk
+in a particular message. (Don't worry about remembering all these
+things---you can hit '?' to see the full list of keyboard commands at
+any point.)
+
+A few other useful commands while viewing a thread. Press 'd' to
+toggle a detailed header fpr a message. If you've scrolled too far to
+the right, press '[' to jump all the way to the left. Finally, you can
+press 'n' and 'p' to jump forward and backward between open
+messages. (I find that very useful!)
+
+Now press 'x' to kill the thread view buffer. You should see the inbox
+again. If you don't, you can cycle through the buffers by pressing
+'b', or you can press 'A' to see a list of all buffers and simply
+select the inbox.
+
+There are many operations you can perform on threads beyond viewing
+them. To archive a thread, press 'a'. The thread will disappear from
+your inbox, but will still appear in search results. If someone
+replies an archived thread, it will reappear in your inbox. To kill a
+thread, press '&'. Killed threads will never come back to your inbox,
+even if people reply, but will still be searchable. (This is useful
+for those interminable threads that you really have no interest in,
+but which seem to pop up on every mailing list.)
+
+If a thread is spam, press 'S'. It will disappear and won't come
+back. It won't even appear in search results (unless you explicitly
+search for spam.)
+
+You can also star a thread by pressing '*'. Starred threads are
+displayed with a little yellow asterix next to them, but otherwise
+have no special semantics. (But you can also search for them
+easily---we'll see how in a moment).
+
+To edit the labels for (all the messages in) a thread, press 'l'. Type
+in the labels as a sequence of space-separated words. To cancel the
+input, press Ctrl-G.
+
+Many of these operations can be applied to a group of threads. Press
+'t' to tag a thread. Tag a couple, then press ';' to apply the next
+command to the set of threads. ';t', of course, will untag all tagged
+messages.
+
+Ok, let's try using labels and search. Press 'L' to bring up a list of
+all the labels you've ever used, along with some special labels
+(Draft, Starred, Sent, Spam, etc.). Highlight a label and press enter
+to view all the messages with that label.
+
+What you just did was actually a specific search. For a general
+search, press "/". Now type in your query (again, Ctrl-G to cancel at
+any point.) You can just type in arbitrary text, which will be matched
+on a per-word basis against the bodies of all email in the index, or
+you can make use of the full Ferret query syntax:
+
+- Phrasal queries using double-quotes, e.g.: "three contiguous words"
+- Queries against a particular field using <field name>:<query>,
+  e.g.: label:ruby-talk, or from:[e-mail]. (Fields include:
+  body, from, to, and subject.)
+- Force occurrence and non-occurrence using + and -, e.g. +label:spam,
+  or -body:"hot soup"
+
+You can combine those all together. For example:
+     +label:ruby-talk +subject:\[ANN\] -rails
+
+Play around with the search, and see the Ferret documentation for
+details on more sophisticated queries (date ranges, "within n words",
+etc.)
+
+At this point, you're well on your way to figuring out all the cool
+things Sup can do. By repeated applications of the '?' key, see if you
+can figure out how to:
+ - List some recent contacts
+ - Easily search for all mail from a recent contact
+ - Easily search for all mail from several recent contacts!
+ - Add someone to your address book
+ - Postpone a message (i.e., save a draft)
+ - Quickly re-edit a just-saved draft message
+ - View the raw header of a message
+ - Star an individual message, not just a thread
+
+There's one last thing to be aware of when using Sup: how it interacts
+with other email programs. Sup stores data about messages in the
+index---information necessary for searching, and message state---but
+doesn't duplicate the message contents themselves. The messages remain
+on the source. If the index and the source every fall out of sync,
+e.g. due to another email client modifying the source, then Sup will
+be unable to operate on that source.
+
+For example, for mbox files, Sup stores a byte offset into the file
+for each message. If a message deleted from that file by another
+client, or even marked as read (yeah, mbox sucks), all succeeding
+offsets will be wrong.
+
+That's the bad news. The good news is that Sup is fairly good at being
+able to detect this type of situation, and fixing it is just a matter
+of running sup-import --rebuild on the source. Sup will even tell you
+how to invoke sup-import when it detects a problem. This is a
+complication you will almost certainly run in to if you use both Sup
+and another MUA on the same source, so it's good to be aware of it.
+
+Have fun, and let me know if you have any problems. --William