README.rdoc in rsolr-1.0.0.beta vs README.rdoc in rsolr-1.0.0.beta2

@@ -1,116 +1,127 @@
 =RSolr
 
+A simple, extensible Ruby client for Apache Solr.
+
 Notice: This document is only for the the 1.0 (pre-release) in the master branch. The last stable gem release documentation can be found here: http://github.com/mwmitchell/rsolr/tree/v0.12.1
 
-A simple, extensible Ruby client for Apache Solr.
+==Documentation
+The code docs can be viewed here : http://rdoc.info/projects/mwmitchell/rsolr
 
 == Installation:
-  gem sources -a http://gemcutter.org
   sudo gem install rsolr
 
 == Example:
   require 'rubygems'
   require 'rsolr'
   
   # Direct connection
-  solr = RSolr.connect 'http://solrserver.com'
+  solr = RSolr.connect :url => 'http://solrserver.com'
   
   # Connecting over a proxy server
-  solr = RSolr.connect 'http://solrserver.com', :proxy=>'http://user:[e-mail]:8080'
+  solr = RSolr.connect :url => 'http://solrserver.com', :proxy=>'http://user:[e-mail]:8080'
   
   # send a request to /select
-  response = solr.get 'select', :q=>'*:*'
+  response = solr.get 'select', :params => {:q => '*:*'}
   
-  # send a request to a custom request handler; /catalog
-  response = solr.get 'catalog', :q=>'*:*'
-  
+  # send a request to /catalog
+  response = solr.get 'catalog', :params => {:q => '*:*'}
+
 == Querying
-Use the #select method to send requests to the /select handler:
-  response = solr.get('select', {
+Use the #get / #post method to send search requests to the /select handler:
+  response = solr.get 'select', :params => {
     :q=>'washington',
     :start=>0,
     :rows=>10
-  })
+  }
 
-The params sent into the method are sent to Solr as-is. The one exception is if a value is an array. When an array is used, multiple parameters *with the same name* are generated for the Solr query. Example:
+The :params sent into the method are sent to Solr as-is. When an array is used, multiple parameters *with the same name* are generated for the Solr query. Example:
   
-  solr.get 'select', :q=>'roses', :fq=>['red', 'violet']
+  solr.get 'select', :params => {:q=>'roses', :fq=>['red', 'violet']}
 
 The above statement generates this Solr query:
   
   select?q=roses&fq=red&fq=violet
 
-There may be cases where the query string is too long for a GET request. RSolr solves this issue by providing a simple way to POST a query to Solr:
-  response = solr.post "select", nil, enormous_params_hash
+===Method Missing
+The RSolr::Client class also uses method_missing for setting the request handler/path:
+  
+  solr.paintings :params => {:q=>'roses', :fq=>['red', 'violet']}
+  
+This is sent to Solr as:
+  paintings?q=roses&fq=red&fq=violet
 
-nil is passed in as the query string data. The enormous_params_hash variable ends up serialized as a form-encoded query string, and the correct content-type headers are sent along to Solr.
 
-== Updating Solr
-Updating us done using native Ruby objects. Hashes are used for single documents and arrays are used for a collection of documents (hashes). These objects get turned into simple XML "messages". Raw XML strings can also be used.
+===Using POST for Search Queries
+There may be cases where the query string is too long for a GET request. RSolr solves this issue by converting hash objects into form-encoded strings:
+  response = solr.post "select", :data => enormous_params_hash
 
-Raw XML via  #update
-  solr.update '<commit/>'
-  solr.update '<optimize/>'
+The :data hash is serialized as a form-encoded query string, and the correct content-type headers are sent along to Solr.
 
+== Updating Solr
+Updating is done using native Ruby objects. Hashes are used for single documents and arrays are used for a collection of documents (hashes). These objects get turned into simple XML "messages". Raw XML strings can also be used.
+
 Single document via #add
   solr.add :id=>1, :price=>1.00
 
 Multiple documents via #add
   documents = [{:id=>1, :price=>1.00}, {:id=>2, :price=>10.50}]
   solr.add documents
 
-When adding, you can also supply "add" xml element attributes and/or a block for manipulating other "add" related elements (docs and fields) when using the #add method:
+The optional :add_attributes hash can also be used to set Solr "add" document attributes:
+  solr.add documents, :add_attributes => {:commitWithin => 10}
+
+Raw XML via  #update
+  solr.update :data => '<commit/>'
+  solr.update :data => '<optimize/>'
+
+When adding, you can also supply "add" xml element attributes and/or a block for manipulating other "add" related elements (docs and fields) by calling the +xml+ method directly:
   
   doc = {:id=>1, :price=>1.00}
-  add_attributes = {:allowDups=>false, :commitWithin=>10.0}
-  solr.add(doc, add_attributes) do |doc|
+  add_attributes = {:allowDups=>false, :commitWithin=>10}
+  add_xml = solr.xml.add(doc, add_attributes) do |doc|
     # boost each document
     doc.attrs[:boost] = 1.5
     # boost the price field:
     doc.field_by_name(:price).attrs[:boost] = 2.0
   end
 
+Now the "add_xml" object can be sent to Solr like:
+  solr.update :data => add_xml
+  
+===Deleting
 Delete by id
   solr.delete_by_id 1
 or an array of ids
   solr.delete_by_id [1, 2, 3, 4]
 
 Delete by query:
   solr.delete_by_query 'price:1.00'
 Delete by array of queries
   solr.delete_by_query ['price:1.00', 'price:10.00']
 
-Commit & optimize shortcuts
-  solr.commit
-  solr.optimize
+===Commit / Optimize
+  solr.commit, :commit_attributes => {}
+  solr.optimize, :optimize_attributes => {}
 
 == Response Formats
 The default response format is Ruby. When the :wt param is set to :ruby, the response is eval'd resulting in a Hash. You can get a raw response by setting the :wt to "ruby" - notice, the string -- not a symbol. RSolr will eval the Ruby string ONLY if the :wt value is :ruby. All other response formats are available as expected, :wt=>'xml' etc..
 
 ===Evaluated Ruby (default)
-  solr.get 'select', :wt=>:ruby # notice :ruby is a Symbol
+  solr.get 'select', :params => {:wt => :ruby} # notice :ruby is a Symbol
 ===Raw Ruby
-  solr.get 'select', :wt=>'ruby' # notice 'ruby' is a String
+  solr.get 'select', :params => {:wt => 'ruby'} # notice 'ruby' is a String
 
 ===XML:
-  solr.get 'select', :wt=>:xml
+  solr.get 'select', :params => {:wt => :xml}
 ===JSON:
-  solr.get 'select', :wt=>:json
+  solr.get 'select', :params => {:wt => :json}
 
-You can access the original request context (path, params, url etc.) by calling the #request method:
-  result = solr.get 'select', :q=>'*:*'
-  result.request[:uri]
-  result.request[:params]
-  etc..
+==Http Request Methods: +get+, +post+, and +head+ 
+RSolr can send GET, POST and HEAD requests to Solr:
+  response = solr.head "admin"
 
-Similarly, the object returned has a response object. This contains any headers that Solr returned, along with the raw response body:
-  result = solr.get 'select', :q=>'*:*'
-  result.response[:headers]
-  result.response[:status]
-  result.response[:body]
-
 ==Related Resources & Projects
 * {RSolr Google Group}[http://groups.google.com/group/rsolr] -- The RSolr discussion group
 * {rsolr-ext}[http://github.com/mwmitchell/rsolr-ext] -- An extension kit for RSolr
 * {rsolr-direct}[http://github.com/mwmitchell/rsolr-direct] -- JRuby direct connection for RSolr
 * {rsolr-nokogiri}[http://github.com/mwmitchell/rsolr-nokogiri] -- Gives RSolr Nokogiri for XML generation.
@@ -137,10 +148,11 @@
 * Commit, do not mess with rakefile, version, or history.
   (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
 ==Contributors
+* Colin Steele
 * Lorenzo Riccucci
 * Mike Perham
 * Mat Brown
 * Shairon Toledo
 * Matthew Rudy
@@ -153,6 +165,6 @@
 
 Matt Mitchell <mailto:[e-mail]>
 
 ==Copyright
 
-Copyright (c) 2008-2010 mwmitchell. See LICENSE for details.
+Copyright (c) 2008-2010 Matt Mitchell. See LICENSE for details.
\ No newline at end of file