vmail 0.0.7 → 0.0.8

data/.gitignore

@@ -1,4 +1,7 @@
+.DS_Store
 *swp
 login.yml
 gmail.yml
 *.log
+pkg/
+.rvmrc

data/NOTES

@@ -1,4 +1,3 @@
-
 interesting. the UID don't seem to be globally unique. two different
 messages in 2 different mailboxes can have same UID
 
@@ -492,10 +491,16 @@ DONE
 - .vmailrc is a yaml file, first in current dir, then check home, can
   also use command line opts
 - fix tests
+- open_href is an improved way to open http hrefs
+- VMAIL_URL_OPENER=elinks
+- digg, reddit, etc buttons
+- note dependence on lynx on startup 
 
 NEXT:
 - help doc: just return readme file, or a vim version of it (vim filetype later)
-- note dependence on lynx in README
+  - width 780 px
+- try turning starred item color into some existing syn color group -
+  like comments
 
 later:
 - mvim - starred messages not syntax colored

data/README.markdown

@@ -1,106 +1,344 @@
 # vmail
 
-This project provides a Vim interface to Gmail.
+vmail is a Vim interface to Gmail. Here are some screenshots:
 
-This is an alpha version. To run it, you need vim or macvim. 
+Why vmail? Because every minute you spend fumbling around in a web browser is a
+minute you're not experiencing the Zen of using a real text editor and staying
+close to the Unix command line. 
+ 
+## Prerequisites
 
-You also need ruby (1.9.2 recommended but not required) and rubygems.
+* a Gmail account
+* a relatively recent version of Vim (vmail is developed against Vim 7.3)
+* Ruby (vmail is developed using Ruby 1.9.2)
+* RubyGems (if Ruby version is older than 1.9)
+* the `lynx` text-only-mode web browser is required to view HTML mail parts in vmail
 
-Once you have those prerequisites, you can install vmail with `gem install
-vmail`.
+The current version of vmail assumes a Unix environment. I'll try to make later versions accommodate Windows.
 
-To use this alpha version, you need to put a gmail.yml file in your home
-directory.
+## Installation
 
-The format of the yaml file is as follows:
+    gem install vmail
+
+## Configuration file
+
+To run vmail, create a yaml file called `.vmailrc` and save it either in the
+current directory (the directory from which you launch vmail) or in your home
+directory. 
+
+The `.vmailrc` file should look something like this. Substitute your own values.
 
     username: dhchoi@gmail.com
-    password: mypassword
+    password: password
     name: Daniel Choi
     signature: |
       --
-      Sent via vmail. http://danielchoi.com
+      Sent via vmail. http://danielchoi.com/software/vmail.html
+
+This file should be formatted in [YAML syntax][1].
+
+[1]:http://www.yaml.org/spec/1.2/spec.html
+
+You can omit the password key-value pair if you'd rather not have the password
+saved in the file. In that case, you'll prompted for the password each time you
+start vmail.
+
+## Contacts autocompletion
+
+vmail uses vim autocompletion to help you auto-complete email addresses.
+To use this feature, generate a `vmail-contacts.txt` file in the current or
+home directory. This is a simple list of your email contacts.
+Invoking vmail with the `-g` option generates this file for you by
+collecting all the recipients and cc's from your last 500 sent
+emails. You can adjust this number by using `-g` with a number argument. 
+
+After vmail generates this file for you, you can edit it however and whenever
+you want, as long as there is one address per line.
+
+## Starting vmail
+
+Once you've created the configuration file and (optionally) the contacts file,
+you can start vmail with
+
+    vmail
+
+This opens the vmail/vim interface and shows you the last 100 messages in your
+Gmail inbox.
+
+You can have vmail show messages from any other mailbox (a.k.a. label) on
+startup by passing in the mailbox name as an argument:
+
+    vmail starred
+
+You can also pass in search parameters:
+
+    vmail important from barackobama@whitehouse.gov
+
+On startup, vmail loads 100 messages by default. You can increase or decrease
+this number by passing in a number after the mailbox name:
+
+    vmail inbox 700 subject unix
+
+## Viewing messages
+
+The first screen vmail shows you is a list of messages. You can view a message
+by moving the cursor line to it and pressing ENTER. This will split the screen
+and show the message content in the bottom pane.
+
+To full-screen the message, press SPACE when the cursor is the message window.
+To go back to the split view, press ENTER.
+
+You can full-screen the list window by pressing SPACE while the cursor is in it.
+
+In the split view, you can jump between the two panes by just pressing ENTER
+from either window.
+
+vmail loads a certain number messages at a time, starting with the most recent.
+If there are more messages that vmail hasn't loaded, you'll see a line at the
+top of the list that looks something like this:
+
+    > Load 100 more messages. 156 remaining.
+
+Put the cursor on this line and press ENTER to load more of these messages.
+
+Unread messages are marked with a `[+]` symbol.
+
+To view the raw RFC822 version of a message, type `,R` while viewing the message.
+
+## Starring, deleting, archiving, marking spam
+
+To star a message, put the cursor on it and type `,*` or alternatively `s`.
+Starring a message copies it to the `starred` mailbox.  Starred messages are
+marked with a `[*]` symbol and color-highlighted.
+
+To delete a message, put the cursor on it and type `,#` or alternatively `,d`.
+Deleting a message puts it in the `trash` mailbox. Deleting a message from the
+`trash` mailbox deletes it permanently.
+
+To archive a message, put the cursor on it and type `,e`.  Archiving a message
+moves it to the `all` mailbox.
+
+To mark a message spam, put the cursor on it and type `,!`. This moves the
+message to to the `spam` mailbox.
+
+You can use range selections in the message list when you star, delete, mark as
+spam, or archive. Use `<C-v>` to start marking a range of lines (the vertical
+position of the cursor doesn't matter).  Then type any of the above commands to
+perform an action on all the messages you selected.
+ 
+## Switching mailboxes, moving messages, copying messages to another mailbox
+
+To switch mailboxes, type `,m`. You'll see an autocomplete window appear at the top.
+The standard vim autocomplete keystrokes apply:
+
+* `C-p` and `C-n` move you up and down the match list
+* `C-e` closes the match list and lets you continue typing
+* `C-u`: when the match list is active, cycles forward through the match list and what you've typed so far; when the match list is inactive, erases what you've typed.
+* `C-x C-u` finds matches for what you've typed so far (when the match list window is closed)
+* `C-y` selects the highlighted match without triggering ENTER
+* ENTER selects the highlighted match from the match list 
+
+Tip: start typing the first 1-3 characters of the mailbox name, then press
+`C-u` or `C-p` until you highlight the right match, and finally press ENTER to
+select.
+
+To move a message to another mailbox, put the cursor on the message in the
+message list, and type `,b`. You'll be prompted to select the target mailbox.
+
+To copy a message to another mailbox, put the cursor on the message in the
+message list, and type `,B`. You'll be prompted to select the target mailbox.
+
+## Composing messages
+
+To start writing a new a email message, type `,c`. 
+
+To reply to a message, type `,r`. 
+
+To reply-all to a message, type `,a`. 
+
+To forward a message, type `,f`.
+
+All these command open a message composition window. At the top, you will see 
+mail headers like this:
+
+    from: Daniel Choi <dhchoi@gmail.com>
+    to:
+    subject:
+
+The `from:` field will be pre-filled from your `.vmailrc` configuration.
+You're responsible for fill in the `to:` and the `subject:` fields.
+You can add a `cc:` and `bcc:` field if you want.
+
+
+When you fill in the recipient addresses, you can use vim autocompletion if you
+generated a `vmail-contacts.txt` file. Start typing a name or email address, then press `C-x C-u` 
+to invoke autocompletion.
+
+Tip: Use `C-y` instead of ENTER to select a match. This will prevent you from
+creating a blank line in the middle of the email headers.
+
+Make sure your email addresses are separated by commas and that they all
+ultimately appear on the **same, unbroken line** for each field. Vim will
+probably break long lines automatically as you type them, so for now (pending a
+future enhancement), you'll have to rejoin the lines if breaks get inserted.
+
+After you fill in the headers, write your message.  Make sure there is a
+blank line between the headers and the body of your message.
+
+When you're done writing, send the message by typing `,vs` in normal mode.
+
+You can save the message as a draft in your draft mailbox by typing `,vd` in
+normal mode.
+
+At any point, you can quit the composition window by typing `q` in normal mode.
+
+## Attachments
+
+The current version of vmail can handle attachments to a certain extent.
+
+When you're viewing a message with attachments, you'll see something like this
+at the top of the message window:
+
+    INBOX 2113 4 kb
+    - image/png; name=canada.png
+    - image/gif; name=arrow_right.gif
+    ---------------------------------------
+    from: Daniel Choi <dhchoi@gmail.com>
+    date: Sun, Dec 12 08:39 AM -05:00 2010
+    to: Daniel Choi <dhchoi@gmail.com>
+    subject: attachment test
+
+    see attached
+
+To download these attachments to a local directory, type `,A`. You'll be
+prompted for a directory path.  Then vmail will save all the attachments in the
+message to this directory.
+
+To send attachments, add something like this to your new message in the message
+composition window:
+
+    from: Daniel Choi <dhchoi@gmail.com>
+    to: barackobama@whitehouse.gov
+    subject: look at this!
+
+    attach:
+    - images/middle-east-map.png
+    - images/policypaper.pdf
+    - docs/
+
+    I think you'll find this stuff interesting.
+    
+
+The `attach:` block is a YAML list. The items are paths (either relative or
+absolute) to the files you want to attach to your message. Note that you can
+also specify a directory, in which case vmail attaches every file it finds in
+that directory.
+
+One thing vmail doesn't do yet is let you forward a message with all its
+attachments intact.  This feature will be implemented in the near future. 
+
+## Printing messages to a file
+
+`,vp` from the message list prints (appends) the text content of all the selected
+messages to a file.
+
+## Invoking your web browser 
+
+When you're reading a message, `,o` opens the first hyperlink in the document
+on or after the cursor in your normal web browser.
+
+When you're reading a message with an html mail part, `,h` saves that part to a
+local file (`vmail-htmlpart.html`) and opens it in your normal web browser.
+
+By default, the command vmail uses to open your web browser is `open`. In OS X,
+this opens URLs and HTML files in the default web browser.  You can change the
+browser vmail invokes by setting the VMAIL_BROWSER environmental variable
+before you start vmail, e.g.:
+
+    export VMAIL_BROWSER='elinks'
+
+## Search queries
+
+vmail can generate a message list by performing an IMAP search on the current mailbox.
+From the message list window, type `,s`. This will prompt you for a search query. 
+The search query is an optional number specifying the number of messages to return, 
+followed by a valid IMAP search query.
+
+Here are some example search queries.
+
+    # the default 
+    100 all  
+
+    # all messages from thematrix.com domain
+    from thematrix.com  
+
+    # all messages from this person
+    from barackobama@whitehouse.gov  
+
+    # subject field search; use double quotes to enclose multiple words
+    subject "unix philosophy"  
 
-Start the program by typing `vmail` on your command line. If you want to use the Macvim 
-version, `export VMAIL_VIM=mvim` first.
+    # example of date range and multiple conditions
+    before 30-Nov-2010 since 1-Nov-2010 from prx.org  
 
-There is no real documentation as of yet, but here are the raw vimscript mappings
+Tip: When you're entering your search query, `<C-u>` clears the query line.
 
+Power-Tip: `<C-f>` opens a mini-editor that contains the current query plus a history of
+previous vmail search queries. You can edit any line in this mini-editor and
+press ENTER to perform the query on that line.
 
-## From Message List Window:
+## Using vmail with MacVim
 
-    inoremap <silent> <buffer> <esc> <Esc>:q<cr>
-    inoremap <silent> <buffer> <esc> <Esc>:q<cr>
-    noremap <silent> <buffer> <cr> :call <SID>show_message()<CR>
-    noremap <silent> <buffer> q :qal!<cr>
-    noremap <silent> <buffer> s :call <SID>toggle_star()<CR>
-    noremap <silent> <buffer> <leader>d :call <SID>delete_messages("Deleted")<CR>
-    noremap <silent> <buffer> <leader>! :call <SID>delete_messages("[Gmail]/Spam")<CR>
-    noremap <silent> <buffer> u :call <SID>update()<CR>
-    noremap <silent> <buffer> <Leader>s :call <SID>search_window()<CR>
-    noremap <silent> <buffer> <Leader>m :call <SID>mailbox_window()<CR>
-    noremap <silent> <buffer> <Leader>v :call <SID>move_to_mailbox()<CR>
-    noremap <silent> <buffer> <Leader>c :call <SID>compose_message()<CR>
-    noremap <silent> <buffer> <Leader>r :call <SID>show_message()<cr>:call <SID>compose_reply(0)<CR>
-    " reply all
-    noremap <silent> <buffer> <Leader>a :call <SID>show_message()<cr>:call <SID>compose_reply(1)<CR>
+vmail uses standard Vim by default, but vmail also works with MacVim, but not
+perfectly. In particular, there seems to be a bug in MacVim that prevents
+vmail's status line activity messages from appearing properly. Nonetheless,
+most of vmail is functional in MacVim.
 
+To use MacVim as your vmail Vim engine, `export VMAIL_VIM=mvim` before startin
+vmail.
 
-## From Message Window:
+Note that when vmail uses MacVim, the terminal window in which you invoke vmail
+will show vmail's logging output while MacVim is running. To quit vmail in
+MacVim mode, you will have to press CTRL-c in this window to stop the vmail
+process.
 
-    noremap <silent> <buffer> <cr> :call <SID>focus_list_window()<CR> 
-    noremap <silent> <buffer> <Leader>q :call <SID>focus_list_window()<CR> 
-    nnoremap <silent> <buffer> q :close<cr>
-    noremap <silent> <buffer> q <Leader>q
-    noremap <silent> <buffer> <Leader>r :call <SID>compose_reply(0)<CR>
-    noremap <silent> <buffer> <Leader>a :call <SID>compose_reply(1)<CR>
-    noremap <silent> <buffer> <Leader>R :call <SID>show_raw()<cr>
-    noremap <silent> <buffer> <Leader>f :call <SID>compose_forward()<CR><cr>
-    noremap <silent> <buffer> <leader>j :call <SID>show_next_message()<CR> 
-    noremap <silent> <buffer> <leader>k :call <SID>show_previous_message()<CR> 
-    noremap <silent> <buffer> <Leader>c :call <SID>compose_message()<CR>
-    noremap <silent> <buffer> <Leader>h :call <SID>open_html_part()<CR><cr>
-    nnoremap <silent> <buffer> <leader>d  :call <SID>focus_list_window()<cr>:call <SID>delete_messages("Deleted")<cr>
-    nnoremap <silent> <buffer> s  :call <SID>focus_list_window()<cr>:call <SID>toggle_star()<cr>
-    nnoremap <silent> <buffer> <Leader>m :call <SID>focus_list_window()<cr>:call <SID>mailbox_window()<CR>
-    nnoremap <silent> <buffer> <Leader>A :call <SID>save_attachments()<cr>
+## vmail file byproducts
 
+vmail generates a few file byproducts when it is running. It generates a
+temporary `vmailbuffer.txt` file in the current directory to hold the message
+list. This should get deleted automatically when vmail quits.
 
-## From Message Compose Window
+vmail also creates a `vmail-htmlpart.html` file in the current directory if you
+open an HTML mail part from vmail. 
 
-    noremap <silent> <buffer> <Leader>d :call <SID>deliver_message()<CR>
-    nnoremap <silent> <buffer> q :call <SID>cancel_compose()<cr>
-    nnoremap <silent> <buffer> <leader>q :call <SID>cancel_compose()<cr>
-    nnoremap <silent> <buffer> <Leader>s :call <SID>save_draft()<CR>
+Finally, vmail logs output to a `vmail.log` file which it creates in the
+current directory. You can tail this file in a separate terminal window to see
+what's going on behind the scenes as you use vmail.
 
-Other:
+## Is my gmail password secure?
 
-    nnoremap <silent> <buffer> <Space> :call <SID>toggle_fullscreen()<cr>
+In short, yes. vmail uses TLS ([Transport Layer Security][1]) to perform IMAP
+and SMTP authentication. So vmail transmits your password securely over the
+network.
 
+[1]:http://en.wikipedia.org/wiki/Transport_Layer_Security
 
+You can also be sure that the vmail code doesn't do anything nefarious with your
+Gmail password because vmail is open source. Anyone can inspect the source code
+of the copy fo vmail that runs on your computer and inspect the code at the
+[github repository][1] and at [rubygems.org][2] (where the vmail gem is
+downloaded from). 
 
-## Open Source License
+[1]:https://github.com/danchoi/vmail
+[2]:https://rubygems.org/gems/vmail
 
-The source code for vmail is governed by the MIT License, which reads as
-follows:
+## Bug reports, feature requests
 
-    Copyright (c) 2010 Daniel Choi
+Please file bug reports and features requests in the [vmail github issue tracker][1].
 
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to
-    deal in the Software without restriction, including without limitation the
-    rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
-    sell copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
+[1]:https://github.com/danchoi/vmail/issues
 
-    The above copyright notice and this permission notice shall be included in
-    all copies or substantial portions of the Software.
+## How to contact the developer
 
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-    IN THE SOFTWARE.
+My name is Daniel Choi. I am based in Cambridge, MA, and you can email me at dhchoi@gmail.com.
 

data/lib/vmail.rb

@@ -5,8 +5,16 @@ module Vmail
   extend self
 
   def start
+
     vim = ENV['VMAIL_VIM'] || 'vim'
 
+    ENV['VMAIL_BROWSER'] ||= 'open'
+
+    # check for lynx
+    if `which lynx` == ''
+      puts "You need to install lynx on your system in order to see html-only messages"
+      sleep 3
+    end
     opts = Vmail::Options.new(ARGV)
     opts.config