sup 0.0.8 → 0.1

data/doc/FAQ.txt

@@ -1,18 +1,30 @@
 Sup FAQ
 -------
+
+Q: What is Sup?
+A: Sup is a console-based email client for people with a lot of email.
+   It supports tagging, very fast full-text search, automatic contact-
+   list management, and more. If you're the type of person who treats
+   email as an extension of your long-term memory, Sup is for you.
+
 Q: What does Sup stand for?
-A: It stands for "what's up?", which is more or less the question in
-   mind when I fire up my mail client.
+A: "What's up?"
+
+Q: Sup looks a lot like a text-based Gmail.
+A: I stole a lot of their ideas. And improved upon them, of course.
 
-Q: If you love GMail so much, why not just use it?
+Q: If you love Gmail so much, why not just use it?
 A: I hate ads, I hate using a mouse, and I hate non-programmability
    and non-extensibility.
 
-   Also, GMail encourages top-posting. THIS CANNOT BE TOLERATED!
+   Also, Gmail doesn't let you use a monospace font, which is just
+   plain lame.
+
+   Also, Gmail encourages top-posting. THIS CANNOT BE TOLERATED!
 
 Q: Why the console?
-A: Because a keystroke is with a hundred mouse clicks (as any Unix
-   user knows). Because you don't need web browser. Because you get
+A: Because a keystroke is worth a hundred mouse clicks, as any Unix
+   user knows. Because you don't need web browser. Because you get
    instantaneous response and a simple interface.
 
 Q: How does Sup deal with spam?
@@ -28,9 +40,8 @@ A: Ok, press the 'd' key.
 
 Q: But I want to delete it for real, not just add a 'deleted' flag in
    the index. I want it gone from disk!
-A: Ok, at some point I plan to have a batch deletion tool that will
-   run through a source and delete all messages that have a 'spam' or
-   'deleted' tags. But that doesn't exist yet.
+A: Currently, for mbox sources, there is a batch deletion tool that
+   will strip out all messages marked as spam or deleted.
 
 Q: I got some error message about needing to run sup-sync --changed
    when I tried to read a message. What's that about?
@@ -41,10 +52,6 @@ A: If messages have been moved, deleted, or altered in a source, Sup
    sources don't change except by having new messages added. If that
    assumption is violated, you'll have to sync the index.
 
-   The alternative is to rescan every source when Sup starts
-   up. Because Sup is designed to work with arbitrarily large mbox
-   files, this would not be a good idea.
-
 Q: How do I back up my index?
 Q: How do I make a state dump?
 A: Since the contents of the messages are recoverable from their
@@ -59,13 +66,10 @@ A: Run:
      sup-sync [<source>+] --restored --restore <dumpfile>
    where <dumpfile> was created as above.
 
-Q: I see this message from Ferret:
-     Error occured in index.c:825 - sis_find_segments_file
-A: Yikes! You've upgraded Ferret and the index format changed beneath
-   you. Follow the index rebuild instructions below.
-
 Q: I upgraded Ferret and the index format changed. I need to
    completely rebuild my index. How do I do this?
+Q: Ferret crashed and I can't read my index. Luckily I made a state
+   dump. What should I do?
 A: First, you'll need a complete state dump. If you haven't made
    one, you'll need to downgrade Ferret and make a state dump as
    above. Then run these commands:
@@ -83,7 +87,7 @@ A: Move the messages from the source to the target using whatever tool
 
    If you sup-sync only one source at a time, depending on the order,
    the messages may be treated as missing and then deleted from the
-   index, which means that their state will be lost when you sync the
+   index, which means that their states will be lost when you sync the
    other source.
 
 Q: What are all these "Redwood" references I see in the code?
@@ -101,3 +105,36 @@ A: Sup is only possible through the hard work of Dave Balmain, the
    really a first-class piece of software, and it's due to the
    tremendous amount of time and effort he's put in to it.
 
+Common Problems
+---------------
+
+P: I see this message from Ferret:
+     Error occured in index.c:825 - sis_find_segments_file
+S: Yikes! You've upgraded Ferret and the index format changed beneath
+   you. Follow the index rebuild instructions above.
+
+P: I get some error message from Rubymail about frozen strings when
+   importing messages with attachments.
+S: The current solution is to directly modify RubyMail. Change line 159 of
+   multipart.rb to:
+     chunk = chunk[0..start]
+   This is because RubyMail hasn't been updated since like Ruby 1.8.2.
+   Please bug Matt Lickey.
+
+P: I see this error:
+     /usr/local/lib/ruby/1.8/yaml.rb:133:in `transfer': allocator undefined for Bignum (TypeError)
+S: You need to upgrade to Ruby 1.8.5. YAML in earlier versions can't
+   parse BigNums, but Sup relies on that for Maildir and IMAP.
+
+P: I see this error:
+     /usr/lib/ruby/1.8/net/imap.rb:204: uninitialized constant Net::IMAP::SSL (NameError)
+S: You need to install a package called libssl-ruby or something similar.
+   Or, don't use imaps:// sources. Ruby's IMAP library otherwise fails in
+   this completely uninformative manner.
+
+P: When I run Sup remotely and view an HTML attachment, an existing
+   Firefox on the *local* machine is redirected to the attachment
+   file, which it can't find (since it's on the remote machine). How do
+   I view HTML attachments in this environment?
+S: Put this in your ~/.mailcap on the machine you run Sup on:
+      text/html; /usr/bin/firefox -a sup '%s'; description=HTML Text; test=test -n "$DISPLAY";  nametemplate=%s.html

data/doc/Philosophy.txt

@@ -1,57 +1,58 @@
 Should an email client have a philosophy? For many people, email is
-one of our primary means of communication. Something so important
-ought to warrant a little thought.
+one of our primary means of communication, and email archives are an
+integral part of our long-term memory. Something so important ought to
+warrant a little thought.
 
 Here's Sup's philosophy.
 
 Using "traditional" email clients today is increasingly problematic.
-Anyone who's on a high-traffic mailing list knows this.  My ruby-talk
+Anyone who's on a high-traffic mailing list knows this. My ruby-talk
 folder is 430 megs and Mutt sits there for 60 seconds while it opens
-it. Keeping up with the all the new traffic is painful, even with
+it. Keeping up with the all the new traffic is impossible, even with
 Mutt's excellent threading features, simply because there's so much of
 it. A single thread can span several pages in the folder index view
-alone! And Mutt is probably the fastest email client out there, and
-certainly most featureful and in terms of threading and mailing list
-support. God help me if I try and throw Thunderbird at that.
+alone! And Mutt is probably the fastest, most mailing-list aware email
+client out there. God help me if I try and use Thunderbird.
 
-The principle problem with traditional clients is that they deal with
+The problem with traditional clients like Mutt is that they deal with
 individual pieces of email. This places a high mental cost on the user
 for each incoming email, by forcing them to ask: Should I keep this
-email, or delete it? If I keep it, where should I file it?  For
-example, I've spent the last 10 years of my life laboriously
-hand-filing every email message I received and feeling a mild sense of
-panic every time an email was both "from Mom" and "about school". The
-massive amounts of email that many people receive, and the cheap cost
-of storage, have made these questions both more costly and less useful
-to answer.
+email, or delete it? If I keep it, where should I file it? I've spent
+the last 10 years of my life laboriously hand-filing every email
+message I received and feeling a mild sense of panic every time an
+email was both "from Mom" and "about school". The massive amounts of
+email that many people receive, and the cheap cost of storage, have
+made these questions both more costly and less useful to answer.
 
-I think GMail has taken the right approach. As a long-time Mutt user,
-I was pretty much blown away when I first saw people use GMail,
-because I saw them treat email differently from how I ever had.  I saw
-that making certain operations quantitatively easier (namely, search)
-resulted in a qualitative difference in usage. You didn't have to
-worry about filing things into folders correctly, because you could
-just find things later by searching for them. I also saw how
-thread-centrism was advantageous over message-centrism when message
-volume was high: if nothing else, there's simply less of them.
+Contrast that with using Gmail. As a long-time Mutt user, I was blown
+away when I first saw someone use Gmail. They treated their email
+differently from how I ever had. They never filed email and they never
+deleted it. They relied on an immediate, global, full-text search, and
+thread-level tagging, to do everything I'd ever done with Mutt, but
+with a trivial cost to the user at message receipt time.
 
-Much of the inspiration for Sup was based on GMail. I think it's to
-the GMail designers' credit that they started with a somewhat ad-hoc
+From Gmail I learned that making certain operations quantitatively
+easier (namely, search) resulted in a qualitative improvement in
+usage. I also learned how thread-centrism was advantageous over
+message-centrism when message volume was high: most of the time, a
+message and its context deserve the same treatment. I think it's to
+the Gmail designers' credit that they started with a somewhat ad-hoc
 idea (hey, we're really good at search engines, so maybe we can build
 an email client on top of one) and managed to build something that was
 actually better than everything else out there. At least, that's how I
 imagine in happened. Maybe they knew what they were doing from the
 start.
 
-But ultimately, GMail wasn't right for me (fuck top posting and HTML
-mail), which is why the idea for Sup was born.
+Unfortunately, there's a lot to Gmail I can't tolerate (top posting,
+HTML mail, one-level threads, and ads come to mind, never mind the
+fact that it's not FOSS). Thus Sup was born.
 
 Sup is based on the following principles, which I stole directly from
-GMail:
+Gmail:
 
-- An immediately accessible and fast search capability over the
-  entire email archive eliminates most of the need for folders,
-  and eliminates the necessity of having to ever delete email.
+- An immediately accessible and fast search capability over the entire
+  email archive eliminates most of the need for folders, and most of
+  the necessity of deleting email.
 
 - Labels eliminate what little need for folders search doesn't cover.
 
@@ -65,4 +66,4 @@ do with the fantastic productivity of a console- and keyboard-based
 application, the usefulness of multiple buffers, the necessity of
 handling multiple email accounts, etc. But those are just details!
 
-Let me know what you think.
+Try it and let me know what you think.

data/doc/TODO

@@ -1,66 +1,96 @@
-for 0.0.8
----------
-x nice little startup config program
-x bugfix: triggering a pageup when cursor scrolling up jumps to the
-   bottom of the page rather than the next line
-x bugfix: final logging messages to stdout?
-x bugfix: mbox directory shouldn't generate an exception, just an error
-x bugfix: m in thread-view-mode when a person is not selected should open up a
-   blank compose-mode rather than do nothing
-x bugfix: stars on messages with blue backgrounds still have green bgs
-x ferret upgrade script (dump & restore)
-x bugfix: mark messages as read immediately when t-v-m is opened
-x compose in thread-view-mode auto-fills in person
-x bugfix: 'N' in thread-view-mode (expand only new messages) crashes
-x bugfix: detect source corruption at startup
-x maildir
-x bugfix: single-line messages come empty upon reply
-
-next release
-------------
-_ bugfix: when one new message comes into an imap folder, we don't
-   catch it until a reload (sometimes?)
-_ bugfix: add new message counts until keypress
-_ bugfix: attachment filenames sometimes not detected (filename=)
-_ split out threading & message chunk parsing to a separate library
+for 0.1
+-------
+x bugfix: any interactive prompt after "No new messages." flash has an
+   empty line above it.
+x detect other sup instances and do something intelligent (because
+x refactor all the *-search-results-mode classes
+x decode RFC 2047 ("encoded word") headers
+  - see: http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/101949, http://dev.rubyonrails.org/ticket/6807
+   ferret crashes violently with more than one index writer open)
+x create attachments
+x add arbitrary labels to sources
+x improve sup-config
+x autoload more threads when you go down
+x add a sync-back tool that at least works for mboxes
+x thread by subject configurable in config.yaml
+x view as text command if the mime view command fails for an attachment
+x bugfix: attachment filenames sometimes not detected (filename=)
+x bugfix: rmail multipart error
+x bugfix: sup-add not prompting for old accounts, i think? possibly because
+    sources no longer respond_to? :username due to Recoverable wrapping
+x wide character support
+x i18n support
+x tab completion on labels
 
-near future
----------
-_ Net::SMTP support (cuz I'm going to need it soon)
-_ create attachments
+for next release
+----------------
+_ use trac or something. this file is getting a little silly.
+_ gpg integration
+_ user-defined hooks
+_ saved searches
+_ bugfix: missing sources should be handled better
+_ tab completion for contacts
+_ bugfix: screwing the headers when editing causes a crash
+_ bugfix: sometimes, when one new message comes into an imap folder,
+   we don't catch it until a reload. but we do see a message
+   indicating they're loaded to inbox (imap only? hard to reproduce.)
+_ bugfix: need a better way to force an address to a particular name,
+   for things like evite addresses
+_ bugfix: ferret flakiness: just added message but can't find it
+_ add new message counts until keypress
+_ bugfix: deadlock (on rubyforge)
+_ bugfix: ferret corrupt index problem at index.c:901. see http://ferret.davebalmain.com/trac/ticket/279
+_ bugfix: read before thread-index has finished loading then hides the
+   thread?!? wtf. (on jamie)_ bugfix: width in index-mode needs to be
+   determined per-character rather than per-byte
+_ search results: highlight relevant snippets and open to relevant
+   portion of thread
+_ rss feed reading
 _ forward attachments
 _ select all, starred, to me, etc
 _ undo
-_ gmail
+_ gmail support
 _ warnings: top-posting, missing attachment, ruby-talk:XXXX detection
-_ mboxz, mboxbz
+_ Net::SMTP support
+_ more control character support in buffer line editing
 
 future
 ------
-search results: highlight relevant snippets and open to relevant portion of thread
-email address to name mapping needs some work. automatic email addresses (noreply@...) are often assigned to something screwy.
-decode RFC 2047 ("encoded word") headers
-  - see: http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/101949, http://dev.rubyonrails.org/ticket/6807
+mboxz, mboxbz
 swappable keymappings
-within-buffer search
-bugfix: when returning from a shelling out, ncurses is crazy 
-more control character support in buffer line editing
-wide character support
-i18n support
-batch deletion
-tab completion on labels, contacts
-contact selector in edit-message-mode
-maybe: filters
-maybe: rangefilter on the initial inbox to only consider the most recent 1000 messages
+bugfix: when returning from a shelling out, sometime ncurses is crazy
+   and refuses to interpret any keystrokes
+better batch deletion (extend to non-mbox sources)
 annotations on messages
 pop
 be able to mark individual messages as spam in thread-view-mode
 toggle wrapping
 maybe: de-archived messages auto-added to inbox
-prune old entries from contacts.txt so that it doesn't arbitrarily
+prune old entries from contacts.txt so that it doesn't grow without bound
+
+maybe
+-----
+split out threading & message chunk parsing to a separate library
+filters
+rangefilter on the initial inbox to only consider the most recent 1000 messages
 
 done
 ----
+x nice little startup config program
+x bugfix: triggering a pageup when cursor scrolling up jumps to the
+   bottom of the page rather than the next line
+x bugfix: final logging messages to stdout?
+x bugfix: mbox directory shouldn't generate an exception, just an error
+x bugfix: m in thread-view-mode when a person is not selected should open up a
+   blank compose-mode rather than do nothing
+x bugfix: stars on messages with blue backgrounds still have green bgs
+x ferret upgrade script (dump & restore)
+x bugfix: mark messages as read immediately when t-v-m is opened
+x compose in thread-view-mode auto-fills in person
+x bugfix: 'N' in thread-view-mode (expand only new messages) crashes
+x bugfix: detect source corruption at startup
+x maildir
+x bugfix: single-line messages come empty upon reply
 x make 'A' archive in thread-view-mode
 x remove stupid percent_done source methods (still useful; made it optional)
 x don't quit while writing thread index state to disk or with unsaved drafts/messages

data/doc/UserGuide.txt

@@ -2,137 +2,101 @@ Welcome to Sup! Here's how to get started.
 
 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 have any messages
-in its index yet, and has no idea where to look for them anyways.
+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
+keyboard commands, but in the absence of any email, these will be
 mostly useless. When you get bored, press 'q' to quit.
 
-I mentioned that Sup's index was empty. 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, so we've got to add some to
-it.
-
-We 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. 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.
+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.
+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).
 
-sup-config works by calling sup-add and sup-sync with the right
-arguments. If you have a non-trivial setup, you may need to run
-sup-add and sup-sync manually.
-
-You can manually add a source to Sup's source list by running
-'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 an 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 two 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.
-
-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.
-
-Ok, now run 'sup'. You should see the most recent unarchived messages
-appear in your inbox. Congratulations, you've got Sup working!
+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
-does not use folders. Instead, you organize and find messages by a
+has no folders. Instead, you organize and find messages by a
 combination of search and labels (knowns as 'tags' everywhere else in
-the world). I claim 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 philosophical treatise has a
+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.)
 
-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 with the label
-"inbox". (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 for things that are too hard to find with
-search.
-
 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, there's just one message.) In Sup, most
-operations are on threads, not individual messages. 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.
+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
+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 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. (You can hit '?' to see the full list of
-keyboard commands at any point.)
+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 fpr a message. If you've scrolled too far 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.
+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
@@ -148,14 +112,14 @@ 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.)
+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).
+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
@@ -166,10 +130,11 @@ Many of these operations can be applied to a group of threads. Press
 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.
+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
@@ -181,11 +146,10 @@ you can make use of the full Ferret query syntax:
 - 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 using + and -, e.g. +label:spam,
-  or -body:"hot soup"
+- Force non-occurrence by -, e.g. -body:"hot soup"
 
 You can combine those all together. For example:
-     +label:ruby-talk +subject:\[ANN\] -rails
+     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",
@@ -204,18 +168,17 @@ can figure out how to:
  - 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, 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
+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
@@ -223,3 +186,60 @@ 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.
+
+
+