FAQ.txt in sup-0.1

- old
+ new

@@ -1,20 +1,32 @@
 Sup FAQ
 -------
+
+Q: What is Sup?
+A: Sup is a console-based email client for people with a lot of email.
+   It supports tagging, very fast full-text search, automatic contact-
+   list management, and more. If you're the type of person who treats
+   email as an extension of your long-term memory, Sup is for you.
+
 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.
+A: "What's up?"
 
-Q: If you love GMail so much, why not just use it?
+Q: Sup looks a lot like a text-based Gmail.
+A: I stole a lot of their ideas. And improved upon them, of course.
+
+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.
 
+   Also, Gmail encourages top-posting. THIS CANNOT BE TOLERATED!
+
 Q: Why the console?
-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
+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 as far as Sup goes. Spam
@@ -26,27 +38,22 @@
 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: 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. But that doesn't exist yet.
+A: Currently, for mbox sources, there is a batch deletion tool that
+   will strip out all messages marked as spam or deleted.
 
 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, 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 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.
-
 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:
@@ -57,17 +64,14 @@
 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 see this message from Ferret:
-     Error occured in index.c:825 - sis_find_segments_file
-A: Yikes! You've upgraded Ferret and the index format changed beneath
-   you. Follow the index rebuild instructions below.
-
 Q: I upgraded Ferret and the index format changed. I need to
    completely rebuild my index. How do I do this?
+Q: Ferret crashed and I can't read my index. Luckily I made a state
+   dump. What should I do?
 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>
@@ -81,11 +85,11 @@
    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 state will be lost when you sync 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
    Mutt user, I couldn't think of a good progression there.) But it was
@@ -99,5 +103,38 @@
 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 completely 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