-Welcome to Sup! Here's how to actually use it.
+Welcome to Sup! Here's how to get started.
-First, try running '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 yet.
+First, try running 'sup'. Since 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 hasn't loaded
+anything into 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.
-
-Let's add some messages. In order for Sup to know about an email, it
-must be in the index. In order for Sup to load them it the index, it
-must know the "source" which holds them. The way Sup works is that the
-index holds all the information that is necessary to search, and all
-the state we have about the message (labels, read/unread, etc.), but
-doesn't contain the message itself. When you search or show your
-inbox, Sup just talks to the index (stored locally on disk). When you
-view a message, Sup then goes back to the source and requests it in
-full. Sup also periodically polls the sources for new messages.
-
-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. (The folder can be blank.)
-- mbox+ssh://remote.machine/path/to/a/filename for a remote mbox file.
-
-There are a few important arguments to sup-import when adding a
-source. The first decision you need to make is whether you want
-messages to be marked as new or not. If you specify --force-read, all
-messages imported at this time will be marked as read. (New messages
-pulled from this source at a later date will be new, of course.) The
-default is to retain the read/unread status as it is in the source.
-
-The second decision is whether you want messages from this source to
-be archived or not. An archived message is one that does not show up
-in your inbox. If you specify --force-archive, messages imported at
-this time will not appear in the inbox. If you specify --archive,
-messages imported at *any* time will not appear in the inbox. (This is
-useful for sources that contain high-traffic mailing lists that you
-don't want "polluting" your inbox.)
-
-Now run sup-import. (You can run it on multiple sources at once.) If
-it requires a username and password for the source, it will prompt you
-for one. Either way, it will add that source to Sup, and immediately
-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 process, and all the computation done now makes operating
-on the index faster.
-
-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.
-(If you have multiple email addresses that correspond to this account,
-you can specify them under :alternates, and if you have multiple
-separate email-receiving accounts, you can add new items to :accounts,
-but that requires a little YAML knowledge and is beyond the scope of
-this introduction.)
-
-Ok, we're finally ready to run Sup! Run 'sup'. You should see messages
-being loaded into your "inbox" from the index. Congratulations!
-
-There are two things that are worth understanding at this point.
-First, Sup does not 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.
-
-Second, Sup groups together messages into threads. You rarely operate
-on an individual message in Sup. Each line in the inbox is a thread,
+keyboard commands, but in the absence of any email, these will be
+mostly useless. When you get bored, press 'q' to quit.
+
+To actually use Sup for email, we need to load messages into the
+index. The index is where Sup stores all message state (e.g. read or
+unread, any message labels), and all information necessary for
+searching and for threading messages. Sup only knows about messages in
+its index.
+
+We can add messages to the index by telling Sup about the "source"
+where the messages reside. Sources are things like IMAP folders, mbox
+folders, maildir directories, and Gmail accounts (in the future). Sup
+doesn't duplicate the actual message content in the index; it only
+stores whatever information is necessary for searching, threading and
+labelling. So when you search for messages or view your inbox, Sup
+talks only to the index (stored locally on disk). When you view a
+thread, Sup requests the full content of all the messages from the
+source.
+
+The easiest way to set up all your sources is to run "sup-config".
+This will interactively walk you through some basic configuration,
+prompt you for all the sources you need, and optionally import
+messages from them. Sup-config uses two other tools, sup-add and
+sup-sync, to load messages into the index. In the future you may make
+use of these tools directly (see below).
+
+Once you've run sup-config, you're ready to run 'sup'. You should see
+the most recent unarchived messages appear in your inbox.
+Congratulations, you've got Sup working!
+
+If you're coming from the world of traditional MUAs, there are a
+couple differences you should be aware of at this point. First, Sup
+has no folders. Instead, you organize and find messages by a
+combination of search and labels (knowns as 'tags' everywhere else in
+the world). 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 nothing more than the result of the search for all
+messages with the label "inbox". (It's actually slightly more
+complicated---we omit messages marked as killed, deleted or spam.)
+
+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.
+The idea is that a labeling system that allows arbitrary, user-defined
+labels, supplemented by a quick and easy-to-access search mechanism
+provides all the functionality that folders does, plus much more, at a
+far lower cost to the user. (The Sup philosophical treatise has a
+little more on this.)
+
+Now 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.)
-
-So 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 do something useful!) 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 also hit tab to cycle between only new
+thread. (If there's no number, there's just one message in the
+thread.) In Sup, most operations are on threads, not individual
+messages. The ideais 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.
-Press enter to view a thread once you've highlighted it. You'll notice
-that all messages in the thread are displayed together. By default,
-only the new messages in a thread are expanded; the others are
-hidden. Press 'E' to expand / collapse all messages, and 'N' to expand
-only the new messages. Use the arrow keys just as before to move
-around the message. You'll also notice that Sup hides quoted text and
-signatures. If you highlight a particular one, you can press enter to
-expand it. You can also press 'o' to open every hidden section in a
-particular message.
-
-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, for threads that
-are very large, you can press 'n' and 'p' to jump forward and backward
-between open messages.
-
-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.
-
-There are many operations you can perform on threads beyond just
-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 (with
-the new message in its proper place).
-
-To kill a thread, press '&'. Killed threads will never come back to
-your inbox, even if people reply (but will still be searchable). Useful
-for those interminable threads that you really have no interest in.
-
-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 functionality. (But you can also search for them
-easily---we'll see how in a moment).
-
-As I mentioned before, messages have labels. 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
-control-G.
+Highlight a thread and press enter to view it. You'll notice that all
+messages in the thread are displayed together, laid 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. (Remember, 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 for 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,
+aligning the display as necessary.
+
+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 'B' 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 star a thread by pressing '*'. Starred threads are displayed
+with a little yellow asterisk 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 talk about labels and searching. Press 'L'
+Ok, let's try using labels and search. Press 'L' to do a quick label
+search. You'll be prompted for a label; simply hit enter to bring up
+scrollable 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:matz@ruby-lang.org. (Fields include:
+ body, from, to, and subject.)
+- Force non-occurrence by -, e.g. -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 application 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. As I described at the beginning of the
+document, Sup stores data about messages in the index, 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 pretty good at being
+able to detect this type of situation, and fixing it is just a matter
+of running sup-sync --changed on the source. Sup will even tell you
+how to invoke sup-sync 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
+
+Appending A: sup-add and sup-sync
+---------------------------------
+
+Instead of using sup-config to add a new source, you can manually run
+'sup-add' with a URI pointing to it. The URI should be of the form:
+- mbox://path/to/a/filename, for an mbox file on disk.
+- maildir://path/to/a/filename, for a maildir directory on disk.
+- imap://imap.server/folder for an unsecure IMAP folder.
+- imaps://secure.imap.server/folder for a secure IMAP folder.
+- mbox+ssh://remote.machine/path/to/a/filename for a remote mbox file.
+
+Before you add the source, you need make three decisions. The first is
+whether you want Sup to regularly poll this source for new messages.
+By default it will, but if this is a source that will never have new
+messages, you can specify --unusual. Sup polls only "usual" sources.
+
+The second is whether you want messages from the source to be
+automatically archived. An archived message will not show up in your
+inbox, but will be found when you search. (Your inbox in Sup is, by
+definition, the set of all all non-archived messages). Specify
+--archive to automatically archive all messages from the source. This
+is useful for sources that contain, for example, high-traffic mailing
+lists that you don't want polluting your inbox.
+
+The final decision is whether you want any labels automatically
+applied to messages from this source. You can use --labels to do this.
+
+If Sup requires account information, e.g. for IMAP servers and remote
+mbox files, sup-add will ask for it.
+
+Now that you've added the source, let's import all the current
+messages from it, by running sup-sync with the source URI. You can
+specify --archive to automatically archive all messages in this
+import; typically you'll want to specify this for every source you
+import except your actual inbox. You can also specify --read to mark
+all imported messages as read; the default is to preserve the
+read/unread status from the source.
+
+sup-sync will now load all the messages from the source into the
+index. Depending on the size of the source, this may take a while.
+Don't panic! It's a one-time process.
+
+Appending B: Handling high-volume mailing lists
+-----------------------------------------------
+
+Here's what I recommend:
+1. Use procmail to filter messages from the list into a distinct source.
+2. Add that source to Sup as a usual source with auto-archive turned
+ on, and with a label corresponding to the mailing list name.
+ (E.g.: sup-add mbox:/home/me/Mail/ruby-talk -a -l ruby-talk)
+3. Voila! Sup will load new messages into the index but not into the
+ inbox, and you can browse the mailing list traffice at any point by
+ searching for that label.
+
+
+
projects / sup / blobdiff