X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=doc%2FFAQ.txt;h=5c85d9c55346f37221dd7ad47ccecf0f483d0946;hb=56fac5b07c8beb0b6a4707f6a7f36c93ff307e1d;hp=62add38b6d49ceb1442a51c7992bdf2b1f1c0ade;hpb=a11efaf82d446ea19527c38aacaa436b7fecc94a;p=sup diff --git a/doc/FAQ.txt b/doc/FAQ.txt index 62add38..5c85d9c 100644 --- a/doc/FAQ.txt +++ b/doc/FAQ.txt @@ -1,20 +1,31 @@ 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, custom code insertion via a hook system, 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? -A: I hate ads, I hate using a mouse, and I hate non-programmability - and non-extensibility. +Q: Sup looks like a text-based Gmail. +A: I stole their ideas. And improved them! - Also, GMail encourages top-posting in a variety of ways. THIS - CANNOT BE TOLERATED! +Q: Why not just use Gmail? +A: I wrote Sup because I hate ads, I hate using a mouse, and I hate + non-programmability and non-extensibility. -Q: Why the console? + Also, Gmail doesn't let you use a monospace font, which is just + lame. -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 + Also, Gmail encourages top-posting. THIS CANNOT BE TOLERATED! + +Q: Why the console? +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? @@ -23,54 +34,99 @@ A: You can manually mark messages as spam, which prevents them from 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. +A: Currently, for mbox sources, there is a batch deletion tool that + will strip out all messages marked as spam or deleted. -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. - -Q: I got some error message about needing to run sup-import --rescan - 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 - sources don't change except by having new messages added. If that - assumption is violated, you'll have to run sup-import --rescan. - - 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 well does Sup play with other mail clients? +A: Not well at all. If messages have been moved, deleted, or altered + due to some other client, Sup will have to rebuild its index for + that message 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. -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 - taken by another project on RubyForge, and wasn't that original, - and was too long to type anyways. +Q: How do I back up my index? +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 > + This will save all message state in a big text file, which you + should probably compress. - 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: How do I restore the message state I saved in my state dump? +A: Run: + sup-sync [+] --restored --restore + where was created as above. + +Q: Ferret crashed and I can't read my index. Luckily I made a state + dump. What should I do? +Q: How do I rebuild the index completely? +A: Run: + rm -rf ~/.sup/ferret # omg wtf + sup-sync --all-sources --all --restore + 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), sup-import - --rebuild both sources at once. If you do it one at a time, you may - lose message state. (Depending, actually, on which order you do it - in. But just do them both at once.) - -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. + you'd like. Mutt's a good one. :) Then run: + sup-sync --changed + + Note that if you sup-sync only one source at a time, depending on + the order in which you do it, 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. So do them both + in one go. + +Q: What are all these "Redwood" references I see in the code? +A: That was Sup's original name. (Think pine, elm. Although I was a + Mutt user, I couldn't think of a good progression there.) But it + was taken by another project on RubyForge, and wasn't that + original, and was too long to type anyways. + + Maybe one day I'll do a huge search-and-replace on the code, but it + doesn't seem that important at this point. + +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 Armstrong. + +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