git.cworth.org Git - sup/blob - doc/FAQ.txt

   1 Sup FAQ
   2 -------
   3
   4 Q: What is Sup?
   5 A: Sup is a console-based email client for people with a lot of email.
   6    It supports tagging, very fast full-text search, automatic contact-
   7    list management, custom code insertion via a hook system, and more.
   8    If you're the type of person who treats email as an extension of your
   9    long-term memory, Sup is for you.
  10
  11 Q: What does Sup stand for?
  12 A: "What's up?"
  13
  14 Q: Sup looks like a text-based Gmail.
  15 A: I stole their ideas. And improved them!
  16
  17 Q: Why not just use Gmail?
  18 A: I wrote Sup because I hate ads, I hate using a mouse, and I hate
  19    non-programmability and non-extensibility.
  20
  21    Also, Gmail doesn't let you use a monospace font, which is just
  22    lame.
  23
  24    Also, Gmail encourages top-posting. THIS CANNOT BE TOLERATED!
  25
  26 Q: Why the console?
  27 A: Because a keystroke is worth a hundred mouse clicks, as any Unix
  28    user knows. Because you don't need web browser. Because you get
  29    instantaneous response and a simple interface.
  30
  31 Q: How does Sup deal with spam?
  32 A: You can manually mark messages as spam, which prevents them from
  33    showing up in future searches, but that's as far as Sup goes. Spam
  34    filtering should be done by a dedicated tool like SpamAssassin.
  35
  36 Q: How do I delete a message?
  37 A: Why delete? Unless it's spam, you might as well just archive it.
  38
  39 Q: C'mon, really now!
  40 A: Ok, press the 'd' key.
  41
  42 Q: But I want to delete it for real, not just add a 'deleted' flag in
  43    the index. I want it gone from disk!
  44 A: Currently, for mbox sources, there is a batch deletion tool that
  45    will strip out all messages marked as spam or deleted.
  46
  47 Q: How well does Sup play with other mail clients?
  48 A: Not well at all. If messages have been moved, deleted, or altered
  49    due to some other client, Sup will have to rebuild its index for
  50    that message source. For example, for mbox files, reading a single
  51    unread message changes the offsets of every file on disk. Rather
  52    than rescanning every time, Sup assumes sources don't change except
  53    by having new messages added. If that assumption is violated,
  54    you'll have to sync the index.
  55
  56 Q: How do I back up my index?
  57 A: Since the contents of the messages are recoverable from their
  58    sources using sup-sync, all you need to back up is the message
  59    state. To do this, simply run:
  60       sup-dump > <dumpfile>
  61    This will save all message state in a big text file, which you
  62    should probably compress.
  63
  64 Q: How do I restore the message state I saved in my state dump?
  65 A: Run:
  66      sup-sync [<source>+] --restored --restore <dumpfile>
  67    where <dumpfile> was created as above.
  68
  69 Q: Ferret crashed and I can't read my index. Luckily I made a state
  70    dump. What should I do?
  71 Q: How do I rebuild the index completely?
  72 A: Run:
  73      rm -rf ~/.sup/ferret    # omg wtf
  74      sup-sync --all-sources --all --restore <dumpfile>
  75    Voila! A brand new index.
  76
  77 Q: I want to move messages from one source to another. (E.g., my
  78    primary inbox is an IMAP server with a quota, and I want to move
  79    some of those messages to local mbox files.) How do I do that while
  80    preserving message state?
  81 A: Move the messages from the source to the target using whatever tool
  82    you'd like. Mutt's a good one. :) Then run:
  83      sup-sync --changed <source1> <source2>
  84
  85    Note that if you sup-sync only one source at a time, depending on
  86    the order in which you do it, the messages may be treated as
  87    missing and then deleted from the index, which means that their
  88    states will be lost when you sync the other source. So do them both
  89    in one go.
  90
  91 Q: What are all these "Redwood" references I see in the code?
  92 A: That was Sup's original name. (Think pine, elm. Although I was a
  93    Mutt user, I couldn't think of a good progression there.) But it
  94    was taken by another project on RubyForge, and wasn't that
  95    original, and was too long to type anyways.
  96
  97    Maybe one day I'll do a huge search-and-replace on the code, but it
  98    doesn't seem that important at this point.
  99
 100 Common Problems
 101 ---------------
 102
 103 P: I see this message from Ferret:
 104      Error occured in index.c:825 - sis_find_segments_file
 105 S: Yikes! You've upgraded Ferret and the index format changed beneath
 106    you. Follow the index rebuild instructions above.
 107
 108 P: I get some error message from Rubymail about frozen strings when
 109    importing messages with attachments.
 110 S: The current solution is to directly modify RubyMail. Change line 159 of
 111    multipart.rb to:
 112      chunk = chunk[0..start]
 113    This is because RubyMail hasn't been updated since like Ruby 1.8.2.
 114    Please bug Matt Armstrong.
 115
 116 P: I see this error:
 117      /usr/local/lib/ruby/1.8/yaml.rb:133:in `transfer': allocator undefined for Bignum (TypeError)
 118 S: You need to upgrade to Ruby 1.8.5. YAML in earlier versions can't
 119    parse BigNums, but Sup relies on that for Maildir and IMAP.
 120
 121 P: I see this error:
 122      /usr/lib/ruby/1.8/net/imap.rb:204: uninitialized constant Net::IMAP::SSL (NameError)
 123 S: You need to install a package called libssl-ruby or something similar.
 124    Or, don't use imaps:// sources. Ruby's IMAP library otherwise fails in
 125    this completely uninformative manner.
 126
 127 P: When I run Sup remotely and view an HTML attachment, an existing
 128    Firefox on the *local* machine is redirected to the attachment
 129    file, which it can't find (since it's on the remote machine). How do
 130    I view HTML attachments in this environment?
 131 S: Put this in your ~/.mailcap on the machine you run Sup on:
 132       text/html; /usr/bin/firefox -a sup '%s'; description=HTML Text; test=test -n "$DISPLAY";  nametemplate=%s.html