A: I hate ads, I hate using a mouse, and I hate non-programmability
and non-extensibility.
- Also, GMail encourages top-posting in a variety of ways. THIS CANNOT BE
- TOLERATED!
+ Also, GMail encourages top-posting in a variety of ways. THIS
+ CANNOT BE TOLERATED!
Q: Why the console?
-A: There are many advantages to the console. A
- few keystrokes can accomplish the work of a hundred mouse clicks
- (as any Unix user knows). Also, you don't need web browser, and you
- get instantaneous response and a simple interface.
+
+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
+ instantaneous response and a simple interface.
Q: How does Sup deal with spam?
A: You can manually mark messages as spam, which prevents them from
- showing up in future searches, but that's all that Sup does. Spam
+ showing up in future searches, but that's as far as Sup goes. Spam
filtering should be done by a dedicated tool like SpamAssassin.
Q: How do I delete a message?
author of ferret, which is the search engine behind Sup. Ferret is
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.
-
-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
projects / sup / commitdiff