-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
+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.
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
-mostly useless. When you're bored, press 'q' to quit.
-
-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:
+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.
+
+So let's add some sources to Sup's source list. Run 'sup-add' 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 folder. (Leave the folder blank for INBOX.)
- mbox+ssh://remote.machine/path/to/a/filename for a remote mbox file.
-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.
-
-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
+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-import 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-import 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.
-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.
+We're almost ready. But 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.
-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!
+Ok, now 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 email, there are a
couple differences you should be aware of at this point. First, Sup
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.
+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
projects / sup / blobdiff