sup 0.0.4 → 0.0.5

data/History.txt

@@ -1,3 +1,8 @@
+== 0.0.5 / 2007-01-05
+
+* More bugfixes, primarily for IMAP.
+* doc/UserGuide.txt
+
 == 0.0.4 / 2007-01-03
  
 * Bugfixes, primarily for threaded networking.

data/Rakefile

@@ -16,12 +16,10 @@ Hoe.new('sup', Redwood::VERSION) do |p|
 end
 
 rule 'ss?.png' => 'ss?-small.png' do |t|
-
 end
 
-
 ## is there really no way to make a rule for this?
-WWW_FILES = %w(www/index.html README.txt doc/Philosophy.txt doc/FAQ.txt)
+WWW_FILES = %w(www/index.html README.txt doc/Philosophy.txt doc/FAQ.txt doc/UserGuide.txt)
 
 SCREENSHOTS = FileList["www/ss?.png"]
 SCREENSHOTS_SMALL = []

data/bin/sup

@@ -100,7 +100,7 @@ begin
   Logger.make_buf
 
   bm.draw_screen
-  imode.load_more_threads :num => ibuf.content_height, :when_done => lambda {   reporting_thread { sleep 1; PollManager.poll } }
+  imode.load_threads :num => ibuf.content_height, :when_done => lambda {   reporting_thread { sleep 1; PollManager.poll } }
 
   PollManager.start_thread
 
@@ -129,7 +129,8 @@ begin
         when :list_buffers
           bm.spawn_unless_exists("Buffer List") { BufferListMode.new }
         when :list_contacts
-          bm.spawn_unless_exists("Contact List") { ContactListMode.new }
+          b = bm.spawn_unless_exists("Contact List") { ContactListMode.new }
+          b.mode.load_more b.content_height
         when :search
           text = bm.ask :search, "query: "
           next unless text && text !~ /^\s*$/
@@ -140,7 +141,7 @@ begin
             log "built query from #{text.inspect}: #{qobj}"
             mode = SearchResultsMode.new qobj
             bm.spawn "search: \"#{short_text}\"", mode
-            mode.load_more_threads :num => mode.buffer.content_height
+            mode.load_threads :num => mode.buffer.content_height
           rescue Ferret::QueryParser::QueryParseException => e
             bm.flash "Couldn't parse query."
           end
@@ -162,12 +163,14 @@ begin
           when 1
             m = nil
             Index.each_id_by_date(:label => :draft) { |mid, builder| m = builder.call }
-            BufferManager.spawn "Edit message", ResumeMode.new(m)
+            r = ResumeMode.new(m)
+            BufferManager.spawn "Edit message", r
+            r.edit
           else
             b = BufferManager.spawn_unless_exists(:draft) do
               mode = LabelSearchResultsMode.new [:draft]
             end
-            b.mode.load_more_threads :num => b.content_height
+            b.mode.load_threads :num => b.content_height
           end
         when :nothing
         when :redraw

data/bin/sup-import

@@ -49,6 +49,7 @@ the following options:
   --force-read:    any messages found will not be marked as new.
 
 The following options can also be specified:
+  --verbose:       print message ids as they're processed
   --the-usual:     import new messages from all usual sources
   --rebuild:       rebuild the index for the specified sources rather than
                    just adding new messages. Useful if the sources
@@ -62,6 +63,7 @@ The following options can also be specified:
 EOS
   exit
 end
+#' stupid ruby-mode
 
 ## for sources that require login information, prompt the user for
 ## that. also provide a list of previously-defined login info to
@@ -105,6 +107,7 @@ the_usual = ARGV.delete "--the-usual"
 rebuild = ARGV.delete "--rebuild"
 force_rebuild = ARGV.delete "--force-rebuild"
 optimize = ARGV.delete "--optimize"
+verbose = ARGV.delete "--verbose"
 start_at = # ok really need to use optparse or something now
   if(i = ARGV.index("--start-at"))
     raise "start-at requires a numeric argument: #{ARGV[i + 1].inspect}" unless ARGV.length > (i + 1) && ARGV[i + 1] =~ /\d/
@@ -167,7 +170,7 @@ begin
     start_offset = nil
     source.each do |offset, labels|
       start_offset ||= offset
-      labels -= [:inbox] if force_archive
+      labels -= [:inbox] if force_archive || archive
       labels -= [:unread] if force_read
       begin
         m = Redwood::Message.new :source => source, :source_info => offset, :labels => labels
@@ -178,8 +181,9 @@ begin
           found[m.id] = true
         end
 
-        m.remove_label :unread if m.status == "RO" unless force_read
-        puts "# message at #{offset}, labels: #{labels * ', '}" unless rebuild
+        m.remove_label :unread if m.source_marked_read? unless force_read
+        puts "# message at #{offset}, labels: #{labels * ', '}" if verbose unless rebuild
+        labels.each { |l| Redwood::LabelManager << l }
         if (rebuild || force_rebuild) && 
             (docid, entry = index.load_entry_for_id(m.id)) && entry
           if force_rebuild || entry[:source_info].to_i != offset
@@ -195,9 +199,9 @@ begin
       end
       if num % 1000 == 0 && num > 0
         elapsed = Time.now - start
-        pctdone = (offset.to_f - start_offset) / (source.total.to_f - start_offset)
-        remaining = (source.total.to_f - offset.to_f) * (elapsed.to_f / (offset.to_f - start_offset))
-        puts "## #{num} (#{(pctdone * 100.0)}% done) read; #{elapsed.to_time_s} elapsed; est. #{remaining.to_time_s} remaining"
+        pctdone = source.pct_done
+        remaining = (100.0 - pctdone) * (elapsed.to_f / pctdone)
+        puts "## #{num} (#{pctdone}% done) read; #{elapsed.to_time_s} elapsed; est. #{remaining.to_time_s} remaining"
       end
     end
     puts "loaded #{num} messages" unless num == 0

data/doc/TODO

@@ -1,3 +1,5 @@
+batch deletion
+on startup, multi-threadedly call #connect on all sources 
 support for message-content modules such as ruby-talk:XXXXX detection
 use Net::SMTP
 search for other messages from author in thread-view-mode
@@ -13,9 +15,11 @@ editing of arbitrary messages
 annotations on messages
 gmail
 pop
-move sup-import argument handling to getopt or something
-mark individual messages as spam in thread-view-mode
+move sup-import argument handling to getopt
+be able to mark individual messages as spam in thread-view-mode
 
+x fix snippet repetitions with small snippets
+x fix next and previous in thread-view-mode with <unreceived messages>
 x move sup-import username/password prompts to highline
 x support different remote servers per user account
 x 'R' to quick-resume most recent draft

data/doc/UserGuide.txt

@@ -1,54 +1,212 @@
 Welcome to Sup! Here's how to actually use it.
 
-To get started, just run 'sup'. Assuming this is your first time,
-you'll be confronted with a mostly blank screen, and a little message
-at the bottom telling you that you have no messages. That's because
-Sup doesn't have any messages in its index. In order to add messages,
-Sup needs to have some "sources" from which to load messages.
+First, try running 'sup'. Assuming this is your first time, you'll be
+confronted with a mostly blank screen, and a notice at the bottom that
+you have no new messages. That's because Sup doesn't have any messages
+in its index yet, and has no idea where to look for them anyways.
 
 If you want to play around a little at this point, you can press 'b'
 to cycle between buffers and 'x' to kill a buffer. There's probably
 not too much interesting there, but there's a log buffer with some
 cryptic messages. You can also press '?' at any point to get a list of
 keyboard commands, but in the absense of any email, these will be
-pretty useless. When you're done, press 'q' to quit.
+mostly useless. When you're bored, press 'q' to quit.
 
-Now let's add a source to Sup. Run sup-import with a URI pointing to
-an email source. The URI should be of the form:
+We need to add some messages to Sup. In order for Sup to know about a
+message, it must be in the index. In order for Sup to load a message
+into the index, it must know about the "source" in which it
+resides. Sup stores all information necessary for search, and all
+state we have about a message, in the index, but doesn't duplicate the
+actual contents of the message itself. So when you search for messages
+or view your inbox, Sup just talks to the index (stored locally on
+disk), but when you view a message, Sup must request it from the
+source.
+
+So let's tell Sup about some sources. Run 'sup-import' with a URI
+pointing to an email source. The URI should be of the form:
 - mbox://path/to/a/filename, for an mbox file on disk. (You can also
   just provide the filename).
 - imap://imap.server/folder or imaps://secure.imap.server/folder for
-  an IMAP server.
+  an IMAP folder. (Leave the folder blank for INBOX.)
 - mbox+ssh://remote.machine/path/to/a/filename for a remote mbox file.
 
-Note: sup-import tries to be smart about setting the labels on
-      messages that it adds (including the special labels "unread" and
-      "inbox"). There are options that control this behavior, and it's
-      worth taking a look at the output of sup-import --help to make
-      sure that you don't end up with 1000 new messages that you've
-      actually already read.
+Before you actually import messages, you need to decide whether you
+want them to be archived or not. An archived message will not show up
+in your inbox. (Your inbox in Sup is, by definition, the set of all
+all non-archived messages). If you specify --force-archive, messages
+imported at *this* time will be archived, but new messages will go to
+your inbox. If you specify --archive, messages imported at *any* time
+will be automatically archived. (This is useful for sources that
+contain high-traffic mailing lists that you don't want "polluting"
+your inbox.)
+
+Typically you'll want to specify --archive for every source you import
+except your actual inbox. You can also force all messages to be marked
+as read; run sup-import --help for details. The default is to preserve
+the read/unread status from the source.
 
-If sup-import requires a username and password for the source, it will
-prompt you for one. Either way, it will start loading messages from
-that source into the index. Depending on the size of the source, this
-may take some time. Don't worry! This is a one-time step, and all the
-computation done now makes operating on the index faster.
+Now run sup-import to add the source. If it requires a username and
+password for the source, it will prompt you. Either way, it will add
+the sources to Sup, and immediately start loading messages from them
+into the index. Depending on the size of the source, this may take a
+while. Don't panic! It's a one-time process.
 
 Now, before we run 'sup' again, take a moment to edit your
 ~/.sup/config.yaml file. Replace "Your Name Here" with your name,
 "your.email.here@domain.tld" with your email address, and fill in your
 .signature file if you choose. You can also set the default editor.
 
-Now run 'sup'. You should messages being loaded into your "inbox!"
-There are two things that are worth understanding at this point.
-First, Sup does not actually use folders. Instead, messages can have
-any number of labels applied to them. Rather than viewing a folder,
-you view the results of a search. So your inbox is simply the set of
-messages that have the 'inbox' label applied to them.
+We're finally ready to run 'sup'. You should see the most recent
+loaded messages appear in your inbox. Congratulations, you've got Sup
+working!
+
+If you're coming from the world of traditional email, there are a
+couple differences you should be aware of at this point. First, Sup
+does not use folders. Instead, you organize and find messages by a
+combination of search and labels (knowns as 'tags' everywhere else in
+the world). I like to say that 95% of the functionality of folders is
+superceded by a quick, easy-to-access, and powerful search mechanism,
+and the other 5% by labels. (The Sup statement of philosophy has a
+little more on this.)
+
+Search and labels are an integral part of Sup because in Sup, rather
+than viewing the contents of a folder, you view the results of a
+search. I mentioned above that your inbox is, by definition, the set
+of all messages that aren't archived. This means that your inbox is,
+in fact, the result of the search for "all messages without the label
+'archive'". It's actually slightly more complicated---we omit killed,
+deleted and spam messages as well.
+
+So you could replicate the folder paradigm easily under this scheme,
+by giving each message exactly one label and only viewing the results
+of simple searches for those labels. But you'd quickly find out that
+life can be easier than that if you just trust the search engine, and
+use labels judiciously for things that are too hard to find with
+search.
+
+But enough chit-chat! Let's take a look at your inbox. You'll see that
+Sup groups messages together into threads: each line in the inbox is a
+thread, and the number in parentheses is the number of messages in
+that thread. (If there's no number in parens, it means there's just
+one message.) In Sup, you rarely operate on an individual message. The
+idea is that you rarely want to operate on a message independent of
+its context; you typically want to view, archive, kill, or label all
+the messages in a thread at one time.
+
+Use the up and down arrows to highlight a thread. ('j' and 'k' do the
+same thing, and 'J' and 'K' will scroll the whole window.  Even the
+left and right arrow keys work!) By default, Sup only loads as many
+threads as it takes to fill the window; if you'd like to load more,
+press 'M'. You can hit tab to cycle between only threads with new
+messages.
+
+Highlight a thread and press enter to view it. You'll notice that all
+messages in the thread are displayed together, layed out graphically
+by their relationship to each other (replies are nested under
+parents). By default, only the new messages in a thread are expanded,
+and the others are hidden. You can toggle an individual message's
+state by highlighting a green line and pressing enter. You can use 'E'
+to expand or collapse all messages or 'N' to expand only the new
+messages. You'll also notice that Sup hides quoted text and
+signatures. If you highlight a particular hidden chunk, you can press
+enter to expand it, or you can press 'o' to toggle every hidden chunk
+in a particular message. (Don't worry about remembering all these
+things---you can hit '?' to see the full list of keyboard commands at
+any point.)
+
+A few other useful commands while viewing a thread. Press 'd' to
+toggle a detailed header fpr a message. If you've scrolled too far to
+the right, press '[' to jump all the way to the left. Finally, you can
+press 'n' and 'p' to jump forward and backward between open
+messages. (I find that very useful!)
+
+Now press 'x' to kill the thread view buffer. You should see the inbox
+again. If you don't, you can cycle through the buffers by pressing
+'b', or you can press 'A' to see a list of all buffers and simply
+select the inbox.
+
+There are many operations you can perform on threads beyond viewing
+them. To archive a thread, press 'a'. The thread will disappear from
+your inbox, but will still appear in search results. If someone
+replies an archived thread, it will reappear in your inbox. To kill a
+thread, press '&'. Killed threads will never come back to your inbox,
+even if people reply, but will still be searchable. (This is useful
+for those interminable threads that you really have no interest in,
+but which seem to pop up on every mailing list.)
+
+If a thread is spam, press 'S'. It will disappear and won't come
+back. It won't even appear in search results (unless you explicitly
+search for spam.)
+
+You can also star a thread by pressing '*'. Starred threads are
+displayed with a little yellow asterix next to them, but otherwise
+have no special semantics. (But you can also search for them
+easily---we'll see how in a moment).
+
+To edit the labels for (all the messages in) a thread, press 'l'. Type
+in the labels as a sequence of space-separated words. To cancel the
+input, press Ctrl-G.
+
+Many of these operations can be applied to a group of threads. Press
+'t' to tag a thread. Tag a couple, then press ';' to apply the next
+command to the set of threads. ';t', of course, will untag all tagged
+messages.
+
+Ok, let's try using labels and search. Press 'L' to bring up a list of
+all the labels you've ever used, along with some special labels
+(Draft, Starred, Sent, Spam, etc.). Highlight a label and press enter
+to view all the messages with that label.
+
+What you just did was actually a specific search. For a general
+search, press "/". Now type in your query (again, Ctrl-G to cancel at
+any point.) You can just type in arbitrary text, which will be matched
+on a per-word basis against the bodies of all email in the index, or
+you can make use of the full Ferret query syntax:
+
+- Phrasal queries using double-quotes, e.g.: "three contiguous words"
+- Queries against a particular field using <field name>:<query>,
+  e.g.: label:ruby-talk, or from:matz@ruby-lang.org. (Fields include:
+  body, from, to, and subject.)
+- Force occurrence and non-occurrence using + and -, e.g. +label:spam,
+  or -body:"hot soup"
+
+You can combine those all together. For example:
+     +label:ruby-talk +subject:\[ANN\] -rails
+
+Play around with the search, and see the Ferret documentation for
+details on more sophisticated queries (date ranges, "within n words",
+etc.)
+
+At this point, you're well on your way to figuring out all the cool
+things Sup can do. By repeated applications of the '?' key, see if you
+can figure out how to:
+ - List some recent contacts
+ - Easily search for all mail from a recent contact
+ - Easily search for all mail from several recent contacts!
+ - Add someone to your address book
+ - Postpone a message (i.e., save a draft)
+ - Quickly re-edit a just-saved draft message
+ - View the raw header of a message
+ - Star an individual message, not just a thread
+
+There's one last thing to be aware of when using Sup: how it interacts
+with other email programs. Sup stores data about messages in the
+index---information necessary for searching, and message state---but
+doesn't duplicate the message contents themselves. The messages remain
+on the source. If the index and the source every fall out of sync,
+e.g. due to another email client modifying the source, then Sup will
+be unable to operate on that source.
 
-Second, Sup groups together messages into threads. You rarely operate
-on an individual message in Sup.
+For example, for mbox files, Sup stores a byte offset into the file
+for each message. If a message deleted from that file by another
+client, or even marked as read (yeah, mbox sucks), all succeeding
+offsets will be wrong.
 
-Press enter to view a thread. 
+That's the bad news. The good news is that Sup is fairly good at being
+able to detect this type of situation, and fixing it is just a matter
+of running sup-import --rebuild on the source. Sup will even tell you
+how to invoke sup-import when it detects a problem. This is a
+complication you will almost certainly run in to if you use both Sup
+and another MUA on the same source, so it's good to be aware of it.
 
-To be continued...
+Have fun, and let me know if you have any problems. --William

data/lib/sup.rb

@@ -13,7 +13,7 @@ class Object
 end
 
 module Redwood
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 
   BASE_DIR   = ENV["SUP_BASE"] || File.join(ENV["HOME"], ".sup")
   CONFIG_FN  = File.join(BASE_DIR, "config.yaml")
@@ -105,7 +105,7 @@ else
         :email => "your.email.here@domain.tld",
         :alternates => [],
         :sendmail => "/usr/sbin/sendmail -oem -ti",
-        :sig_file => File.join(ENV["HOME"], ".signature")
+        :signature => File.join(ENV["HOME"], ".signature")
       }
     },
     :editor => ENV["EDITOR"] || "/usr/bin/vi",

data/lib/sup/buffer.rb

@@ -217,7 +217,6 @@ class BufferManager
     if true
       buf = @buffers.last
       buf.resize Ncurses.rows - minibuf_lines, Ncurses.cols
-      File.open("asdf.txt", "a") { |f| f.puts "dirty #@dirty, (re)drawing #{buf.mode.name}" }
       @dirty ? buf.draw : buf.redraw
     end
 
@@ -233,7 +232,6 @@ class BufferManager
   ## the mode is expensive, as it often is.
   def spawn_unless_exists title, opts={}
     if @name_map.member? title
-      Redwood::log "buffer '#{title}' already exists, raising to front"
       raise_to_front @name_map[title] unless opts[:hidden]
     else
       mode = yield
@@ -292,7 +290,10 @@ class BufferManager
     end
   end
 
+  ## not really thread safe.
   def ask domain, question, default=nil
+    raise "impossible!" if @asking
+
     @textfields[domain] ||= TextField.new Ncurses.stdscr, Ncurses.rows - 1, 0, Ncurses.cols
     tf = @textfields[domain]
 
@@ -310,7 +311,10 @@ class BufferManager
     ret = nil
     tf.position_cursor
     Ncurses.sync { Ncurses.refresh }
+
+    @asking = true
     while tf.handle_input(Ncurses.nonblocking_getch); end
+    @asking = false
 
     ret = tf.value
     Ncurses.sync { tf.deactivate }
@@ -369,7 +373,9 @@ class BufferManager
 
   def minibuf_lines
     @minibuf_mutex.synchronize do
-      [(@flash ? 1 : 0) + @minibuf_stack.compact.size, 1].max
+      [(@flash ? 1 : 0) + 
+       (@asking ? 1 : 0) +
+       @minibuf_stack.compact.size, 1].max
     end
   end
   
@@ -383,8 +389,9 @@ class BufferManager
 
     Ncurses.mutex.lock unless opts[:sync] == false
     Ncurses.attrset Colormap.color_for(:none)
+    adj = @asking ? 2 : 1
     m.each_with_index do |s, i|
-      Ncurses.mvaddstr Ncurses.rows - i - 1, 0, s + (" " * [Ncurses.cols - s.length, 0].max)
+      Ncurses.mvaddstr Ncurses.rows - i - adj, 0, s + (" " * [Ncurses.cols - s.length, 0].max)
     end
     Ncurses.refresh if opts[:refresh]
     Ncurses.mutex.unlock unless opts[:sync] == false
@@ -406,7 +413,7 @@ class BufferManager
 
     if block_given?
       begin
-        yield
+        yield id
       ensure
         clear id
       end