poddb_client 0.1.4 → 0.1.5

data/README.markdown

@@ -1,15 +1,11 @@
 # poddb
 
-Poddb lets you find, track, and download podcasts from the Unix command line and Vim.
-
-[screenshots]
+_Podcatching for nerds, Zen minimalists, and unix fanatics_.
 
+Poddb lets you browse, search, and download podcasts from the Unix command line
+and Vim.
 
-## Benefits
-
-* Search for podcasts from the command line
-* Lean Vim interface to navigate, favorite, and download podcasts
-* Handle podcasts directly as files; use any tool to play them
+[screenshots]
 
 
 ## Prerequisites
@@ -29,6 +25,9 @@ Poddb assumes a Unix (POSIX) environment.
 
 ## Install
 
+Poddb can be installed as a Ruby gem. Please note that while the tool is called
+**poddb**, the gem is called **poddb_client**.
+
     gem install poddb_client
 
 Test your installation by typing `poddb -h`. You should see poddb's help.
@@ -36,87 +35,192 @@ Test your installation by typing `poddb -h`. You should see poddb's help.
 On some systems you may run into a PATH issue, where the system can't find the
 `poddb` command after installation. You might want to try 
 
-    sudo gem install poddb
+    sudo gem install poddb_client
 
 to see if that puts `poddb` on your PATH.
 
 If you ever want to uninstall Poddb from your system, just execute this command:
 
-    gem uninstall poddb
+    gem uninstall poddb_client
 
-and all traces of Poddb will removed, except the application-specific files it
-creates during execution. These files are created in a directory called `~/.poddb`.
+This will remove all traces of Poddb, except for the application-specific files
+it creates in a directory called `~/.poddb`. These you'll have to remove
+manually.
 
 
 ## How to use it
 
-Invoke `poddb` from command line interface, passing it flags and search terms.
-After you press `ENTER`, Poddb will send the query over the internet to the poddb
-server. The server will send back data, and poddb will launch Vim to let you
-navigate and interact with the results.
+You invoke `poddb` from command line interface, passing it flags and search
+terms. Poddb will send the query over the internet to the poddb server. (So you
+must be online to use Poddb, though once you've downloaded some podcast audio
+or video files you can play them entirely offline.) The server will send back
+data, and poddb will launch Vim to let you navigate and interact with the query
+results.
 
-The command line interface is as follows:
+Here is a partial synopsis of the command line interface. A more detailed guide
+to using Poddb follows.
 
     Usage: poddb [options] [query]
 
-        -f, --from-favorites             Show all recent items from favorite podcasts
+        -f, --from-favorites             Show all recent episodes from favorite podcasts
         -a, --add PODCAST_URL            Add podcast with PODCAST_URL to the poddb database
         -l, --list [QUERY]               List all podcasts in the poddb database
                                          (If QUERY is supplied, will return matching podcasts)
         -F, --favorite-podcasts          Show favorite podcasts
         -o, --order ORDER                Sort results by ORDER
                                          The only option right now is 'popular'. Default order is pubdate.
-        -d, --days DAYS                  Limit results to items published since DAYS days ago
-        -t, --type MEDIA_TYPE            Return items of MEDIA_TYPE only (audio,video)
-            --download-and-play ITEM_ID  Download item and play with PODDB_MEDIA_PLAYER
-            --key-mappings               Show key mappings for Vim navigation interface
-        -h, --help                       Show this message
-        -v, --version                    Show version number
+        -d, --days DAYS                  Limit results to episodes published since DAYS days ago
+        -t, --type MEDIA_TYPE            Return episodes of MEDIA_TYPE only (audio,video)
+
+## Browse and search for podcasts
+
+To see all the podcasts in the poddb database:
 
+    poddb -l
+    
+Type `poddb -l QUERY` to see if any podcasts matching the QUERY string are in
+the database. E.g.
 
-## Podcast list
+    poddb -l music 
 
-To see all the podcasts in the poddb database, type `poddb -l`. Type `poddb -l
-QUERY` to see if any podcasts matching the QUERY string are in the database. If
-you don't see a favorite feed of yours in the list, you can add the feed to the
-Poddb database with this command:
+will return all the podcasts in the Poddb database with the word "music" in the
+title or podcast description.
+
+Press `ENTER` on a podcast to see its episodes.  See **Navigate and download
+podcast episodes** below for instruction on how to view and download episodes.
+
+
+## Add podcasts to the database
+
+If you don't see a favorite feed of yours in the list returned by `poddb -l`,
+you can add the feed to the Poddb database with this command:
 
     poddb -a PODCAST_URL
 
-This command will also add the podcast to your favorites.
+E.g.,
+
+    poddb -a http://www.philosophybites.libsyn.com/rss
+
+The `-a` command will also add the podcast to your favorites.
+
+
+## Favorite podcasts
+
+When viewing a list of podcasts returned by `poddb -l`, you can add a podcast
+to your favorites by putting the cursor over it and pressing `f`. Press `f`
+again to remove the podcast from your favorite podcasts.  Favorite podcasts
+have a `@` sign in the left margin.
+
+Once you have a few favorite podcasts, you can list and navigate them with
+the command
+
+    poddb -F
+
+You can also aggregate all the most recent episodes from your favorite episodes by
+launching Poddb with the command
+
+    poddb -f
+
+Your favorite podcasts are stored in `~/.poddb/favorites` as a simple list of
+podcast ids. The ids are internal to Poddb's PostgreSQL database.
+
+## Search for podcast episodes 
+
+With Poddb, you search for podcast episodes from the command line. If there are
+matches, Poddb will launch the Vim navigation interface. If not, you'll just
+see a message saying no matches were found.
+
+A basic search like 
+
+    poddb music oud
+
+will return all podcast episodes that match the query words "music" and "oud."
 
-When you're viewing a list of podcasts, you can add a podcast to your favorites
-by putting the cursor over it and pressing `f`. Press `f` again to remove the
-podcast from your favorite podcasts.  Your favorite podcasts are stored in
-`~/.poddb/favorites` as a simple list of podcast ids.
+You can also limit the scope of the search by media type:
 
-Press `ENTER` on a podcast to see its items.
+    poddb -t video ruby
 
+will return all podcast episodes that match the words "food" and "recipe" that
+are video downloads. You can use `-t audio` to limit search results to audio
+downloads.
 
-## Item list
+Two other command flags that are useful are `-o` and `-d`. `-d n` lets you
+limit the scope of the search to episodes published in the last _n_ days. So
 
-If you see a list of items (i.e. downloadable podcast episodes), the following
-key commands apply:
+    poddb -d 7 libya 
 
-* `l` or `ENTER` show item detail
-* `d` mark item for download
-* `D` start downloading item and play with mplayer or `PODDB_MEDIA_PLAYER` 
-* `p` show all items for this podcast 
-* `CTRL-j` show next item
-* `CTRL-k` show previous item
+will return all podcast episodes that match the query "libya" published over
+the last week.
 
-If you mark items for downloading, Poddb will download them as soon as you quit
-the Vim interface with `:qa` or some similar command.
+To sort the search results by most popular episodes first, use the `-o popular`
+flag. So
+
+    poddb -d 30 -o popular tiny desk concert
+
+will show the most popular Tiny Desk Concert episodes in the last month
+
+Invoking Poddb with no query words will show you all the most recent 
+episodes from all the podcasts in the Poddb database. So to see the most
+popular downloads in the last week, you can use
+
+    poddb -d 7 -o popular
+
+
+
+## Navigate and download podcast episodes
+
+When you see a list of episodes, you can use the following key commands, in
+addition to Vim's standard cursor commands:
+
+* `l` or `ENTER` show episode detail
+* `d` mark episode for download
+* `D` start downloading episode immediately and play with `mplayer` or `PODDB_MEDIA_PLAYER` 
+* `p` show all episodes for this podcast 
+* `CTRL-j` show next episode
+* `CTRL-k` show previous episode
+
+If you press `p` to show all the episodes for the podcast, you can navigate back to the
+previous screen with `CTRL-o` and return forward again with `CTRL-i`. In other words, 
+feel free to use Vim's jump-list navigation commands. 
+
+When you press `l` or `ENTER`, more information about the episode will appear in a split
+window below the list.
+
+If you mark episodes for downloading, Poddb will place a `*` in their left
+margin and download them as soon as you quit the Vim interface with `:qa` or
+some similar command.
+
+Poddb uses `wget` to download episodes. The current version downloads all
+marked episodes serially. A future version may implement parallel downloading.
+
+Poddb downloads episodes into the current directory and saves them with
+filenames that follow the format,
+
+    {title of podcast}.{title of episode}.{poddb internal identifier}.{filetype extension}
+
+Examples:
+
+    The-Loh-Life.Wisconsin-Wasp-Nest-part-2.poddb42329.mp3
+    Philosophy-Bites.Michael-Sandel-on-Justice.poddb_711_56523.mp3
+    NPR-Tiny-Desk-Concerts-Podcast.Diego-Garcia.poddb_312_48461.m4v
 
 If you press `D`, Poddb will quit the Vim interface immediately and begin
-downloading the item that was under the cursor. After the download is complete,
-Poddb will start playing the item with `mplayer` or whatever command you
-specify using the `PODDB_MEDIA_PLAYER` environment variable.
+downloading the episode that was under the cursor. After the download is complete,
+Poddb will automatically start playing the episode with `mplayer`.
+
+If you don't want to use `mplayer` or don't have it installed. You can make
+Poddb launch a different media player by setting the `PODDB_MEDIA_PLAYER`
+environment variable and exporting it. For example, to make Poddb use `totem`: 
+
+    export PODDB_MEDIA_PLAYER=totem
+    poddb 
 
-If you see a `D` on the left margin of an item in the item list, that means
-that you already downloaded that podcast item into the current directory.
+Put the `export` command in your `.bash_profile` if you don't want to keep
+typing it.
 
-Poddb uses `wget` to download items.
+If you see a `D` on the left margin of an episode while you're looking at a
+list of episodes, that means that you've already downloaded that episode into
+the current directory.
 
 
 ## Bug reports and feature requests
@@ -126,6 +230,20 @@ Please submit them here:
 * <https://github.com/danchoi/poddb_client/issues>
 
 
+## About the app
+
+Poddb has two parts, a client and a server. The client is a hybrid
+Ruby/VimScript program packaged as a Ruby gem. The server is a Ruby
+[Sinatra][sinatra] app sitting in front of a [PostgreSQL][postgres] database.
+Podcast feeds are fetched with [curb][curb] and parsed with
+[nokogiri][nokogiri].
+
+[sinatra]:http://www.sinatrarb.com/
+[postgres]:http://www.google.com/search?aq=f&sourceid=chrome&ie=UTF-8&q=postgresql
+[curb]:http://curb.rubyforge.org/
+[nokogiri]:http://nokogiri.org/
+
+
 ## About the developer
 
 My name is Daniel Choi. I make software with Ruby, Rails, MySQL, PostgreSQL,
@@ -141,5 +259,3 @@ Software](http://kajasoftware.com).
 [twitter]:http://twitter.com/#!/danchoi
 
 
-
-

data/Rakefile

@@ -39,8 +39,9 @@ desc "build webpage"
 task :build_webpage do
   `cp README.markdown ../project-webpages/src/poddb_client.README.markdown`
   `cp coverage.markdown ../project-webpages/src/poddb_client.coverage.markdown`
+  `cp links.markdown ../project-webpages/src/poddb_client.links.markdown`
   Dir.chdir "../project-webpages" do
-    puts `ruby gen.rb poddb_client #{ViTunes::VERSION}`
+    puts `ruby gen.rb poddb_client #{PoddbClient::VERSION}`
     `open out/poddb_client.html`
   end
 end

data/lib/interactive.vim

@@ -221,7 +221,7 @@ endfunction
 
 function! s:help()
   " This just displays the README
-  let res = system(s:client_cmd." --key-mappings")
+  let res = system(s:client_cmd." --readme")
   echo res  
 endfunction
 

data/lib/poddb_client.rb

@@ -6,7 +6,13 @@ require 'net/http'
 
 class PoddbClient
 
-  # TODO: set for production
+  # checks
+  %w( curl wget ).each do |x|
+    if `which #{x}` == ''
+      abort("Missing `#{x}`. Please install it before you start poddb.")
+    end
+  end
+
   SERVER = ENV['PODDB_SERVER'] || "http://poddb.com"
 
   PODDB_DIR = "%s/.poddb" % ENV['HOME']
@@ -70,12 +76,15 @@ class PoddbClient
       opts.on("--download-and-play ITEM_ID", "Download item and play with PODDB_MEDIA_PLAYER") do |item_id|
         puts "Download and play #{item_id}"
       end
-      opts.on("--key-mappings", "Show key mappings for Vim navigation interface") do
-        puts "KEYMAPPINGS"
+      opts.on("--readme", "Show README") do
+        readme_file = File.expand_path("../../README.markdown", __FILE__)
+        system("less #{readme_file}")
         exit
       end
       opts.on_tail("-h", "--help", "Show this message") do
         puts opts
+        puts 
+        puts "For more detailed help, use `poddb --readme` or visit http://danielchoi.com/software/poddb.html"
         exit
       end
       opts.on_tail("-v", "--version", "Show version number") do

data/lib/poddb_client/downloading.rb

@@ -6,7 +6,7 @@ class PoddbClient
 
 
     def titleize(s, maxlength=20) 
-      s.gsub(/\W+/, '-')[0,maxlength].sub(/-$/, '')
+      s.gsub(/\W+/, '-')[0,maxlength].sub(/-$/, '').sub(/^-/, '')
     end
 
     def download(item_id)

data/lib/poddb_client/version.rb

@@ -1,3 +1,3 @@
 class PoddbClient
-  VERSION = '0.1.4'
+  VERSION = '0.1.5'
 end

data/links.markdown

@@ -0,0 +1,4 @@
+* [github repo](https://github.com/danchoi/poddb_client)
+* [rubygems page](https://rubygems.org/gems/poddb_client)
+* [commit history](https://github.com/danchoi/poddb_client/commits/master)
+* [issue tracker](https://github.com/danchoi/poddb_client/issues)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: poddb_client
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-15 00:00:00.000000000Z
+date: 2011-09-16 00:00:00.000000000Z
 dependencies: []
 description: Podcast aggregation from the command line
 email:
@@ -24,10 +24,12 @@ files:
 - README.markdown
 - Rakefile
 - bin/poddb
+- coverage.markdown
 - lib/interactive.vim
 - lib/poddb_client.rb
 - lib/poddb_client/downloading.rb
 - lib/poddb_client/version.rb
+- links.markdown
 - poddb_client.gemspec
 homepage: http://danielchoi.com/software/poddb.html
 licenses: []