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.
+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
keyboard commands, but in the absense of any email, these will be
mostly useless. When you're bored, press 'q' to quit.
-Let's add some messages to Sup. In order for Sup to know about a
+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 works by storing all the information that is necessary to
-search, and all the state we have about the message (labels,
-read/unread, etc.) in the index, but not storing the actual contents
-of the message itself. So when you search or show your inbox, Sup just
-talks to the index (stored locally on disk), and when you view a
-message, Sup requests it in full from the to the source.
+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:
an IMAP folder. (Leave the folder blank for INBOX.)
- mbox+ssh://remote.machine/path/to/a/filename for a remote mbox file.
-Before you actually import message, you need to decide whether you
-want messages them to be archived or not. An archived message will not
-show up in your inbox. (Your inbox is, by definition, 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.)
+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.)
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.)
-
-Run sup-import to add the source. You can run it on multiple sources
-at once if you want to apply the same set of flags to all of them. If
-sup-import requires a username and password for the source, it will
-prompt you for one. 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 some time. Don't worry! This
-is a one-time process, and all the computation done now makes actually
-using the index faster.
+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,
"your.email.here@domain.tld" with your email address, and fill in your
.signature file if you choose. You can also set the default editor.
-Ok, we're finally ready---run 'sup'. You should see messages being
-loaded into your inbox from the index. Congratulations!
+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!
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
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. We'll get to search in a moment, but if you're
-unfamiliar with labels, they're just any arbitrary word that you can
-attach to a message, and any message can have zero or more labels. So
-you can think of folders as labels in the case where you're restricted
-to exactly one label per message.
-
-The reason this works at all is due to the second thing you should be
-aware of: 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, in fact the result of the search for "all messages
-without the label 'archive'. (It's actually slightly more complicated
-than that---we omit killed, deleted and spam messages as well.)
-
-So you could replicate the folder experience easily under this scheme,
+and the other 5% by labels. (The Sup statement of philosophy has a
+little more on this.)
+
+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.
+
+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 to find those things that are too hard with
-search. (The best label I've seen someone use: "contact-info".)
+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
+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, it means there's just one
-message.) In Sup, you rarely operate on an individual message. The
+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 given thread at one time.
+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, just like
-scroll-lock used to. 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.
+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, and their relationship
-is shown graphically (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, and 'N' to expand only the new messages. You'll also
-notice that Sup hides quoted text and signatures. If you highlight a
-particular one, you can press enter to expand it, or you can press 'o'
-to toggle every hidden section in a particular message. (Don't worry
-about remembering all these things---you can hit '?' to see the full
-list at any point.)
+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. 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!)
+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 that 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.
+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 to the thread, it will reappear in your inbox. To kill a
+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.
+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
You can also star a thread by pressing '*'. Starred threads are
displayed with a little yellow asterix next to them, but otherwise
-have no functionality. (But you can also search for them
+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
command to the set of threads. ';t', of course, will untag all tagged
messages.
-Ok, let's use 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, Spam, etc.). Highlight a label and press enter to view all
-the messages with that label.
+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.
-To search, press "/" and type in your query (again, Ctrl-G to cancel
-at any point.) You can just type in arbitrary text, which will be
-matched against the bodies of all email in the index, or you can make
-use of the full Ferret query syntax:
+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:matz@ruby-lang.org. (Fields include:
body, from, to, and subject.)
-- Force occurrence and non-occurrence with + and -, e.g. +label:spam, or
- -body:"hot soup"
+- 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
etc.)
At this point, you're well on your way to figuring out all the cool
-things Sup can do. With judicious use of the '?' key, see if you can
-figure out how to:
- - List your recent contacts
- - Add someone to your address book
+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
projects / sup / commitdiff