Sup FAQ
-------
+
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.
-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.
+
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 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?
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?
-A: Press the 'd' key.
+A: Why delete? Unless it's spam, you might as well just archive it.
+
+Q: C'mon, really now!
+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: Deleting a message is an old-fashioned concept. In the modern
- world, disk space is cheap enough that you should never have to
- delete a message. If it's spam, save it for future analysis.
-
-Q: C'mon, really now!
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 (and, for mbox sources, will update the offsets of
- all later messages). But that doesn't exist yet.
+ 'deleted' tags. But that doesn't exist yet.
-Q: I got some error message about needing to run sup-import --rescan
+Q: I got some error message about needing to run sup-sync --changed
when I tried to read a message. What's that about?
A: If messages have been moved, deleted, or altered in a source, Sup
may have to rebuild its index for that source. For example, for
- mbox files, even reading a message changes the offsets of every
- file on disk. Rather than rescanning every time, Sup assumes
+ mbox files, reading a single unread message changes the offsets of
+ every file on disk. Rather than rescanning every time, Sup assumes
sources don't change except by having new messages added. If that
- assumption is violated, you'll have to run sup-import --rescan.
+ 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.
- 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
+ sources using sup-sync, all you need to back up is the message
+ state. To do this, simply run:
+ sup-dump > <dumpfile>
+ This will save all message state in a big text file, which you
+ should probably compress.
+
+Q: How do I restore the message state I saved in my state dump?
+A: Run:
+ sup-sync [<source>+] --restored --restore <dumpfile>
+ where <dumpfile> was created as above.
+
+Q: I upgraded Ferret and the index format changed. I need to
+ completely rebuild my index. How do I do this?
+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:
+ rm -rf ~/.sup/ferret # omg wtf
+ sup-sync --all-sources --all --restore <dumpfile>
+ Voila! A brand new index.
+
+Q: I want to move messages from one source to another. (E.g., my
+ primary inbox is an IMAP server with a quota, and I want to move
+ some of those messages to local mbox files.) How do I do that while
+ preserving message state?
+A: Move the messages from the source to the target using whatever tool
+ you'd like. Then (and this is the important part), run:
+ sup-sync --changed <source1> <source2>
+
+ 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 states will be lost when you sync the
+ other source.
Q: What are all these "Redwood" references I see in the code?
A: That was Sup's original name. (Think pine, elm. Although I am a
Maybe one day I'll do a huge search-and-replace on the code, but it
doesn't seem that important at this point.
-Q: I want to move messages from one source to another. (E.g., my
- primary inbox is an IMAP server with a quota, and I want to move
- some of those messages to local mbox files.) How do I do that while
- preserving message state?
-A: Move the messages from the source to the target using whatever tool
- you'd like. Then (and this is the important part), sup-import
- --rescan the target, and THEN the source. If you do it the other
- way around, you'll lose any message state.
-
Q: How is Sup possible?
A: Sup is only possible through the hard work of Dave Balmain, the
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.
+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 somewhat 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
+
projects / sup / blobdiff