vnews 0.0.1 → 0.0.2

data/README.markdown

@@ -0,0 +1,296 @@
+# Vnews
+
+Vnews is a fast, lightweight newsfeed reader built on top of Vim and
+MySQL.
+
+[screenshots]
+
+There are lots of newsfeed readers out there, both desktop and
+web-based. Here are some of Vnews's advantages: 
+
+* minimizes distractions; everything is rendered as plain text and pure content; images and ads are not displayed
+* makes it easy to navigate your entire feed collection using efficient keystrokes 
+* makes it easy to copy, append, or pipe text from your feeds to whatever file or program you want
+
+Vnews uses MySQL to store your feed data locally. It uses MySQL's MyISAM
+tables to provide natural-language full-text search capability.
+
+
+## Prerequisites
+
+* a recent version of Vim (Vnews is developed against Vim 7.2)
+* a recent version of Ruby: Ruby 1.9.2 is recommended
+* MySQL
+* the Unix program `tidy` 
+* the Unix program `fmt` 
+
+Vnews assumes a Unix environment. 
+
+To install Ruby 1.9.2, I recommend using the [RVM Version Manager][rvm],
+which makes it easy to install and manage different versions of Ruby.
+
+[rvm]:http://rvm.beginrescueend.com
+
+## Installation
+
+    gem install vnews
+
+Test your installation by typing `vnews -h`. You should see Vnews's help.
+
+If you run into any PATH errors, try the following: Install the RVM
+Version Manager, then install Ruby 1.9.2 through RVM, and then run `gem
+install vnews`.  This should solve any installation issues.
+
+If you ever want to uninstall Vnews from your system, execute this command:
+
+    gem uninstall vnews
+
+... and all traces of Vnews will removed.
+
+New and improved versions of Vnews will be released over time. To install the
+latest version, just type `gem install vnews` again.
+
+
+## Setup
+
+    vnews
+
+When you run Vnews for the first time, a `.vnewsrc` configuration file will be
+generated in your home directory. The top of this file will look like
+this:
+
+    host: localhost 
+    database: vnews 
+    username: root 
+    password: 
+ 
+You must edit this file to match your MySQL settings, and then run 
+
+    vnews --create-db
+
+to generate the MySQL database that will store your feed data. Leave
+`password:` blank if you don't use a MySQL password.
+
+To use MacVim as your Vnews Vim engine, you can run vnews like this
+
+    VNEWS_VIM=mvim vnews
+
+or you can `export VNEWS_VIM=mvim` in your `~/.bash_profile` and then
+just run `vnews`.
+
+## Configuring your feeds
+
+To configure your feeds, edit the bottom part of the `.vnewsrc` file.
+The bottom part of the file looks like this:
+
+    General News 
+    http://feedproxy.google.com/economist/full_print_edition
+    http://feeds.feedburner.com/TheAtlanticWire
+    
+    Humor
+    http://feed.dilbert.com/dilbert/blog
+    
+    Tech 
+    http://rss.slashdot.org/Slashdot/slashdot
+    http://feeds2.feedburner.com/readwriteweb
+    http://feedproxy.google.com/programmableweb
+    http://news.ycombinator.com/rss
+    http://daringfireball.net/index.xml
+    http://dailyvim.blogspot.com/feeds/posts/default
+    
+The configuration syntax is very simple. Feeds are organized into
+folders, e.g. "General News". Under each folder name, list the feeds you
+want to go inside that folder. You may put a feed under more than one
+folder. Feeds are listed by their URLs.  These should point to live Atom
+or RSS content.  
+
+Whenever you change the feed/folder configuration, run this command: 
+
+    vnews -u
+
+This will update the Vnews datastore to reflect the changes (including
+removing feeds). Then Vnews will update all your feeds and start a Vnews
+session.  If you don't want to start a Vnews session (e.g. if you want
+to run this as a cron job), use `vnews -U` instead.
+
+
+## Basic navigation
+
+To start Vnews, use `vnews -u` to update all your feeds before starting
+your Vnews session. To simply start the session without going through
+the update process, use the simple `vnews` command.
+
+At this point, you should see the feed items for all your feeds
+in one consolidated list.
+
+* `j` moves up the item list
+* `k` moves down the item list
+* `ENTER` from the list window displays the item under the cursor and focuses the item window
+* `ENTER` from item window returns focus to the list window
+* `C-l` displays the item under the cursor without focusing the item window
+* `SPACE` toggles full-screen mode for the current window.
+* `C-j` shows the next item without changing window focus
+* `C-k` shows the previous item without changing window focus
+
+You can also use the standard Vim window switching, rotating, and
+positioning commands.
+
+
+## Navigating feeds and folders
+
+* `,n` calls up the folder selection window
+* `,m` calls up the feed selection window, sorted alphabetically
+* `,M` calls up the feed selection window, sorted by the number of times you read an item from each feed
+
+For all of the commands, 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-n`, `C-u` or `C-p` until you highlight the right match, and
+finally press ENTER to select.
+
+
+## Unread items
+
+Unread items are marked with a `+` symbol.
+
+
+## Starring items
+
+You can star interesting feed items by using `,*` or `,8` (both use the
+same keys, the only difference being the SHIFT key). Starred items are
+colored green and made available in a specially `Starred` folder.
+
+Starred items don't get deleted when you remove the feed they came
+from from your `.vnewsrc` configuration file. 
+
+To unstar an item, press `,*` or `,8`  on a starred item.
+
+
+## Deleting items
+
+To delete items, use `,#` or `,3`. 
+
+You can also delete a range of items, e.g. if you wanted to clear out a
+backlog of items in a feed or folder.  To delete a range of items, you
+can either of these methods:
+
+* make a selection of rows in visual mode and type `:VNDelete`
+* specify a line number range with the command: `:[range]VNDelete`
+
+See `:help 10.3` to learn how to specify command line ranges.
+
+You can use `:VND` as an abbreviation for `:VNDelete`.
+
+
+## Opening webpages and hyperlinks
+
+* `,o` opens the next web hyperlink on or after the cursor in your default external web browser
+* `,h` opens the web page that the feed item is linked to
+
+Web hyperlinks  are the URLs that begin with http:// or https://. 
+
+Under the covers, Vnews uses the command `gnome-open` or `open` to
+launch your external web browser. This should cover Linux Gnome desktop
+and OS X users. You can change the command Vnews uses to open a
+hyperlink by adding this to your `~/.vimrc`:
+
+    let g:Vnews#browser_command = "your browser command here"
+
+If your Vim has `netrw` installed, you can open a hyperlink directly in
+Vim by putting the cursor on a web hyperlink and typing `gf`, `CTRL-W f`
+or `,O` (capital O). All these commands open the webpage inside your Vim
+session using `elinks` or whatever browser you set as your
+`g:netrw_http_cmd`.  See `:help netrw` for more information.
+
+
+## Searching your feeds
+
+* `:VNSearch [term]` searches your feeds for items matching `[term]`
+
+
+You can use the abbreviation `:VNS`. If there are matches, you'll see
+the matching words color-highlighted. 
+
+
+## Concatenating feed items
+
+* `:VNConcat` with a visual selection
+* `:[range]VNConcat`
+
+These commands let you concatenate feed items into a single, continuous
+text document for printing or more leisurely reading.
+
+See `:help 10.3` to learn how to specify command line ranges.
+
+
+## Updating your feeds
+
+Starting vnews with 
+
+    vnews -u
+
+will update all your feeds before opening the Vnews session.
+
+    vnews -U
+
+will update all your feeds without starting a session. You might want to
+use this option if you want to update your feeds periodically in the
+background using `cron`.
+
+If you're already in a Vnews session, you can update the current feed of
+folder by pressing `u`. 
+
+## OPML import
+
+If you want to import an OPML list of your feed subscriptions into
+Vnews, use this command:
+
+    vnews --opml [file]
+
+`[file]` is your OPML file. 
+
+You can easily import your Google Reader subscriptions this way. 
+Here's [a video][export-tutorial] that shows you how to export your Google Reader
+subscriptions to an OPML file.
+
+[export-tutorial]:http://www.clipotech.com/2007/06/opml-export-in-google-reader.html
+
+
+## Getting help
+
+Typing `,?` will open the help webpage in a browser.
+
+
+## Bug reports and feature requests
+
+Vnews is very new, so there are kinks and bugs to iron out and lot of
+desirable features to add.  If you have a bug to report or a good feature to
+suggest, please file it on the [issue tracker][1].  That will help a lot.
+
+[1]:https://github.com/danchoi/vnews/issues
+
+You can also join the [Google Group][group] and comment there.
+
+[group]:http://groups.google.com/group/vnews-users?msg=new&lnk=gcis
+
+## How to contact the developer
+
+My name is Daniel Choi. I am based in Cambridge, Massachusetts, USA, and you
+can email me at dhchoi {at} gmail.com.  
+
+
+
+
+
+
+
+
+

data/Rakefile

@@ -1,37 +1,50 @@
 $LOAD_PATH.unshift File.join(File.dirname(__FILE__), 'lib')
-require 'couchrest'
 require 'yaml'
 require 'json'
-require 'vnews'
 require 'rake'
 require 'rake/testtask'
 require 'bundler'
+require 'vnews'
+require 'vnews/version'
+
 Bundler::GemHelper.install_tasks
 
-desc "Save couchdb views in lib/couchviews.yml"
-task :create_views do
-  db = CouchRest.database! "http://localhost:5984/vnews"
-  views = YAML::load File.read("lib/couchviews.yml")
-  begin
-    rev = db.get(views['_id'])['_rev']
-    puts db.save_doc(views.merge('_rev' => rev))
-  rescue RestClient::ResourceNotFound
-    puts db.save_doc(views)
-  end
-end
+desc "release and build and push new website"
+task :push => [:release, :web]
 
-desc "List feeds with recent entry titles" 
-task :list_feeds do
-  vnews = Vnews::Aggregator.new  
-  puts vnews.list_feeds.inspect
+desc "Bumps version number up one and git commits"
+task :bump do
+  basefile = "lib/vnews/version.rb"
+  file = File.read(basefile)
+  oldver = file[/VERSION = '(\d.\d.\d)'/, 1]
+  newver_i = oldver.gsub(".", '').to_i + 1
+  newver = ("%.3d" % newver_i).split(//).join('.')
+  puts oldver
+  puts newver
+  puts "Bumping version: #{oldver} => #{newver}"
+  newfile = file.gsub("VERSION = '#{oldver}'", "VERSION = '#{newver}'") 
+  File.open(basefile, 'w') {|f| f.write newfile}
+  `git commit -am 'Bump'`
 end
 
-desc "Run tests"
-task :test do 
-  $:.unshift File.expand_path("test")
-  MiniTest::Unit.autorun
+desc "build and push website"
+task :web => :build_webpage do
+  puts "Building and pushing website"
+  Dir.chdir "../project-webpages" do
+    `scp out/vnews.html zoe2@instantwatcher.com:~/danielchoi.com/public/software/`
+    `rsync -avz out/images-vnews zoe2@instantwatcher.com:~/danielchoi.com/public/software/`
+    `rsync -avz out/stylesheets zoe2@instantwatcher.com:~/danielchoi.com/public/software/`
+    `rsync -avz out/lightbox2 zoe2@instantwatcher.com:~/danielchoi.com/public/software/`
+  end
+  `open http://danielchoi.com/software/vnews.html`
 end
 
-task :default => :test
-
+desc "build webpage"
+task :build_webpage do
+  `cp README.markdown ../project-webpages/src/vnews.README.markdown`
+  Dir.chdir "../project-webpages" do
+    puts `ruby gen.rb vnews #{Vnews::VERSION}`
+    `open out/vnews.html`
+  end
+end
 

data/bin/vnews

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+begin
+  require 'vnews'
+rescue LoadError
+  require 'rubygems'
+  require 'vnews'
+end
+
+Vnews.start

data/lib/vnews.rb

@@ -7,7 +7,13 @@ require 'drb'
 class Vnews
   
   def self.start
-    puts "Starting vnews #{Vnews::VERSION}"
+
+    ["tidy", "fmt"].each do |x|
+      if `which #{x}` == ''
+        puts "Before you can run Vnews, you need to install #{x}."
+        exit
+      end
+    end
 
     if ! File.exists?(File.expand_path(Vnews::Config::CONFIGPATH))
       puts "Missing #{Vnews::Config::CONFIGPATH}"
@@ -18,6 +24,37 @@ class Vnews
       exit
     end
 
+    if ['--version', '-v', "--help", "-h"].include?(ARGV.first)
+      puts "vnews #{Vnews::VERSION}"
+      puts "by Daniel Choi dhchoi@gmail.com"
+      puts
+      puts <<-END
+---
+Usage: vnews 
+
+When you run Vnews for the first time, a .vnewsrc configuration file will be
+generated in your home directory.  You must edit this file to match your MySQL
+settings, and then run `vnews --create-db`.
+
+After that you can run `vnews` to read your feeds.
+
+Specific options:
+
+  -u, --update           Update all feeds and folders before starting vnews
+  -U                     Update all feeds and folders without starting vnews session
+  --opml [opml file]     Import feeds from an OPML file
+  --create-db            Create MySQL database configured in .vnewrc 
+  -v, --version          Show version
+  -h, --help             Show this message
+
+Please visit http://danielchoi.com/software/vnews.html for more help.
+
+--- 
+        END
+      exit
+    end
+
+
     if ARGV.first == "--create-db"
       c = File.read(Vnews::Config::CONFIGPATH) 
       top, bottom = c.split(/^\s*$/,2)
@@ -39,13 +76,17 @@ class Vnews
       puts "Done."
     end
 
-    if ['--update', '-u'].include?(ARGV.first)
+    if ['--update', '-u', '-U'].include?(ARGV.first)
       Vnews::Config.update_folders
+      if ARGV.first == '-U'
+        exit
+      end
     end
 
+    puts "Starting vnews #{Vnews::VERSION}"
     Vnews.sql_client # loads the config
 
-    vim = ENV['VMAIL_VIM'] || 'vim'
+    vim = ENV['VNEWS_VIM'] || 'vim'
     vimscript = File.join(File.dirname(__FILE__), "vnews.vim")
     vim_command = "#{vim} -S #{vimscript} "
     STDERR.puts vim_command

data/lib/vnews.vim

@@ -49,6 +49,7 @@ function! s:common_mappings()
   nnoremap <buffer> <leader>3 :call <SID>delete_item()<CR>
   nnoremap <buffer> u :call <SID>update_feed()<CR>
   nnoremap <buffer> <leader>u :call <SID>update_feed()<CR>
+  nnoremap <silent> <leader>? :call <SID>show_help()<cr>
   command! -bar -nargs=0 VNUpdateFeed  :call <SID>update_feed()
 endfunc
 
@@ -460,6 +461,13 @@ func! s:update_feed()
 endfunc
 
 
+" -------------------------------------------------------------------------------- 
+"  HELP
+func! s:show_help()
+  let command = g:Vnews#browser_command . ' ' . shellescape('http://danielchoi.com/software/vnews.html')
+  call system(command)
+endfunc
+
 command! -bar -nargs=1 VNSearch :call s:search_items(<f-args>)
 
 

data/lib/vnews/display.rb

@@ -63,7 +63,7 @@ class Vnews
     end
 
     def format_item_summary(i, width)
-      varwidth = width.to_i - 31
+      varwidth = width.to_i - 32
       feed_title = col i['feed_title'], varwidth * 0.25
       title = col i['title'], varwidth * 0.75
       word_count = i['word_count'].to_s.rjust(6)

data/lib/vnews/version.rb

@@ -1,4 +1,4 @@
 class Vnews
-  VERSION = '0.0.1'
+  VERSION = '0.0.2'
 end
 

data/vnews.gemspec

@@ -19,9 +19,8 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.add_dependency 'feed_yamlizer', '>=0.0.6'
   s.add_dependency 'nokogiri'
-
-  # remember to say in readme that fmt and tidy are required
+  s.add_dependency 'mysql2'
+  s.add_dependency 'feed_yamlizer', '>=0.0.7'
 
 end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Daniel Choi
@@ -14,11 +14,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-21 00:00:00 -05:00
+date: 2011-02-22 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: feed_yamlizer
+  name: nokogiri
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
@@ -27,13 +27,11 @@ dependencies:
       - !ruby/object:Gem::Version 
         segments: 
         - 0
-        - 0
-        - 6
-        version: 0.0.6
+        version: "0"
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: nokogiri
+  name: mysql2
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
@@ -45,10 +43,26 @@ dependencies:
         version: "0"
   type: :runtime
   version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: feed_yamlizer
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 0
+        - 7
+        version: 0.0.7
+  type: :runtime
+  version_requirements: *id003
 description: Read your feeds in Vim
 email: 
 - dhchoi@gmail.com
 executables: 
+- vnews
 - vnews-client
 extensions: []
 
@@ -59,7 +73,9 @@ files:
 - Gemfile
 - Gemfile.lock
 - MIT-LICENSE.txt
+- README.markdown
 - Rakefile
+- bin/vnews
 - bin/vnews-client
 - lib/create.sql
 - lib/vnews.rb