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
   7    contact-list management, and more. If you're the type of person
   8    who subscribed to high-volume mailing lists and never deletes any
   9    email, Sup is for you.
  10
  11 Q: What does Sup stand for?
  12 A: "What's up?"
  13
  14 Q: Sup looks a lot like a text-based Gmail.
  15 A: I stole a lot of their ideas. And improved upon them, of course.
  16
  17 Q: If you love Gmail so much, why not just use it?
  18 A: I hate ads, I hate using a mouse, and I hate non-programmability
  19    and non-extensibility.
  20
  21    Also, Gmail doesn't let you use a monospace font, which is just
  22    plain 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: I got some error message about needing to run sup-sync --changed
  48    when I tried to read a message. What's that about?
  49 A: If messages have been moved, deleted, or altered in a source, Sup
  50    may have to rebuild its index for that source. For example, for
  51    mbox files, reading a single unread message changes the offsets of
  52    every file on disk. Rather than rescanning every time, Sup assumes
  53    sources don't change except by having new messages added. If that
  54    assumption is violated, you'll have to sync the index.
  55
  56 Q: How do I back up my index?
  57 Q: How do I make a state dump?
  58 A: Since the contents of the messages are recoverable from their
  59    sources using sup-sync, all you need to back up is the message
  60    state. To do this, simply run:
  61       sup-dump > <dumpfile>
  62    This will save all message state in a big text file, which you
  63    should probably compress.
  64
  65 Q: How do I restore the message state I saved in my state dump?
  66 A: Run:
  67      sup-sync [<source>+] --restored --restore <dumpfile>
  68    where <dumpfile> was created as above.
  69
  70 Q: I upgraded Ferret and the index format changed. I need to
  71    completely rebuild my index. How do I do this?
  72 Q: Ferret crashed and I can't read my index. Luckily I made a state
  73    dump. What should I do?
  74 A: First, you'll need a complete state dump. If you haven't made
  75    one, you'll need to downgrade Ferret and make a state dump as
  76    above. Then run these commands:
  77      rm -rf ~/.sup/ferret    # omg wtf
  78      sup-sync --all-sources --all --restore <dumpfile>
  79    Voila! A brand new index.
  80
  81 Q: I want to move messages from one source to another. (E.g., my
  82    primary inbox is an IMAP server with a quota, and I want to move
  83    some of those messages to local mbox files.) How do I do that while
  84    preserving message state?
  85 A: Move the messages from the source to the target using whatever tool
  86    you'd like. Then (and this is the important part), run:
  87      sup-sync --changed <source1> <source2>
  88
  89    If you sup-sync only one source at a time, depending on the order,
  90    the messages may be treated as missing and then deleted from the
  91    index, which means that their states will be lost when you sync the
  92    other source.
  93
  94 Q: What are all these "Redwood" references I see in the code?
  95 A: That was Sup's original name. (Think pine, elm. Although I am a
  96    Mutt user, I couldn't think of a good progression there.) But it was
  97    taken by another project on RubyForge, and wasn't that original,
  98    and was too long to type anyways.
  99
 100    Maybe one day I'll do a huge search-and-replace on the code, but it
 101    doesn't seem that important at this point.
 102
 103 Q: How is Sup possible?
 104 A: Sup is only possible through the hard work of Dave Balmain, the
 105    author of ferret, which is the search engine behind Sup. Ferret is
 106    really a first-class piece of software, and it's due to the
 107    tremendous amount of time and effort he's put in to it.
 108
 109 Common Problems
 110 ---------------
 111
 112 P: I see this message from Ferret:
 113      Error occured in index.c:825 - sis_find_segments_file
 114 S: Yikes! You've upgraded Ferret and the index format changed beneath
 115    you. Follow the index rebuild instructions above.
 116
 117 P: I get some error message from Rubymail about frozen strings when
 118    importing messages with attachments.
 119 S: The current solution is to directly modify RubyMail. Change line 159 of
 120    multipart.rb to:
 121      chunk = chunk[0..start]
 122    This is because RubyMail hasn't been updated since like Ruby 1.8.2.
 123    Please bug Matt Lickey.
 124
 125 P: I see this error:
 126      /usr/local/lib/ruby/1.8/yaml.rb:133:in `transfer': allocator undefined for Bignum (TypeError)
 127 S: You need to upgrade to Ruby 1.8.5. YAML in earlier versions can't
 128    parse BigNums, but Sup relies on that for Maildir and IMAP.
 129
 130 P: I see this error:
 131      /usr/lib/ruby/1.8/net/imap.rb:204: uninitialized constant Net::IMAP::SSL (NameError)
 132 S: You need to install a package called libssl-ruby or something similar.
 133    Or, don't use imaps:// sources. Ruby's IMAP library otherwise fails in
 134    this completely uninformative manner.
 135
 136 P: When I run Sup remotely and view an HTML attachment, an existing
 137    Firefox on the *local* machine is redirected to the attachment
 138    file, which it can't find (since it's on the remote machine). How do
 139    I view HTML attachments in this environment?
 140 S: Put this in your ~/.mailcap on the machine you run Sup on:
 141       text/html; /usr/bin/firefox -a sup '%s'; description=HTML Text; test=test -n "$DISPLAY";  nametemplate=%s.html