Flesh out "What's New in 1.0"

HISTORY.rdoc

@@ -21,9 +21,6 @@
 * {Fix tests that assume position in a <tt>Hash</tt>}[http://github.com/jnunemaker/twitter/commit/c9f7ed1d9106807aa6fb27d48a92f4b92d0594a7] (@duncan[http://twitter.com/#!/duncan])
 * {Enable SSL by default (add option to disable SSL)}[http://github.com/jnunemaker/twitter/commit/c4f8907d6595f93d63bc84d6575920a14774e656]
 * {Use HTTP DELETE method instead of HTTP POST for all destructive methods}[http://github.com/jnunemaker/twitter/commit/0bfbf6352de9bdda2b93ed053a358c0cb8e78e8f]
-* {Remove <tt>Base#replies</tt> (use <tt>Base#mentions</tt> instead)}[http://github.com/jnunemaker/twitter/commit/0bfbf6352de9bdda2b93ed053a358c0cb8e78e8f]
-* {Return full <tt>Trends</tt> object to include <tt>as_of</tt> method}[http://github.com/jnunemaker/twitter/commit/009f7d38013293a887c7460fce70fff4a826caaf]
-* {Return full <tt>Geo</tt> object to include <tt>query</tt> method}[http://github.com/jnunemaker/twitter/commit/46ca16fd296c60caff9533ed37bc6f3f1b8c0424]
 * {Change the method signature for <tt>Base#users</tt> and <tt>Base#friendships</tt> to accept an <tt>Array</tt> and an options <tt>Hash</tt>}[http://github.com/jnunemaker/twitter/commit/0bfbf6352de9bdda2b93ed053a358c0cb8e78e8f]
 * {Add <tt>Twitter.profile_image</tt> method}[http://github.com/jnunemaker/twitter/commit/e6645022aefdc11860fe88b45725a08bb24adf55] (@ratherchad[http://twitter.com/#!/ratherchad])
 * {Improve website style}[http://github.com/jnunemaker/twitter/commit/4cdf4e76b6d71d5d4760b46d1a894c00929c0ba3] (@rodrigo3n[http://twitter.com/#!/rodrigo3n])

README.rdoc

@@ -1,31 +1,80 @@
 = The Twitter Ruby Gem
 ==== A Ruby wrapper for the Twitter REST and Search APIs
 == What's New in 1.0
-This gem has been completely rewritten for version 1.0 thanks to {contributions from numerous 
-people}[http://github.com/jnunemaker/twitter/blob/master/HISTORY.rdoc]. This rewrite breaks 
-compatibility with version 0.9.12 and earlier versions of the gem. Most notably, the 
-<tt>Twitter::Base</tt>, <tt>Twitter:Geo</tt>, <tt>Twitter::LocalTrends</tt>, and <tt>Twitter::Trends</tt> classes have all been 
-combined in the <tt>Twitter::Client</tt> class. This gem will {display deprecation warnings and forward 
-method calls to the Client class}[http://github.com/jnunemaker/twitter/commit/192e5884f367750dbdca8471aa12385ed5b057ca]
-whenever possible. In a handful of cases, method names were changed to improve clarity, consistency, 
-or resolve namespace conflicts.
-
-The <tt>Twitter::Search</tt> class has remained largely the same, however it no longer accepts a query in
-its constructor. You can specify a query using the <tt>containing</tt> method, which is aliased to <tt>q</tt>.
+This gem has been completely rewritten for version 1.0 thanks to {contributions from numerous
+people}[http://github.com/jnunemaker/twitter/blob/master/HISTORY.rdoc]. This rewrite breaks
+compatibility with version 0.9.12 and earlier versions of the gem. Most notably, the
+<tt>Twitter::Base</tt>, <tt>Twitter:Geo</tt>, <tt>Twitter::LocalTrends</tt>, and
+<tt>Twitter::Trends</tt> classes {have all been
+combined}[http://github.com/jnunemaker/twitter/commit/eb53872249634ee1f0179982b091a1a0fd9c0973] in
+the <tt>Twitter::Client</tt> class. This gem will {display deprecation warnings and forward method
+calls to the Client class}[http://github.com/jnunemaker/twitter/commit/192e5884f367750dbdca8471aa12385ed5b057ca]
+whenever possible. In a handful of cases, method names were changed to resolve namespace conflicts.
 
   # Pre-1.0
-  Twitter::Search.new('query')
+  Twitter::Base.new.user('sferik').name
   # Post-1.0
-  Twitter::Search.new.q('query')
+  Twitter::Client.new.user('sferik').name
+
+The <tt>Twitter::Search</tt> class has remained largely the same, however it no longer accepts a
+query in its constructor. You can specify a query using the <tt>containing</tt> instance method,
+which is aliased to <tt>q</tt>.
+
+  # Pre-1.0
+  Twitter::Search.new('query').fetch.results.first.text
+  # Post-1.0
+  Twitter::Search.new.q('query').fetch.results.first.text
+
+The <tt>Twitter::OAuth</tt> class {has been removed}[http://github.com/jnunemaker/twitter/commit/d33b119cdfdaefb10db99e56d28dd69625816edf].
+This class was just a wrapper to get access tokens via the {<tt>oauth</tt>
+gem}[http://github.com/oauth/oauth-ruby]. Given that there are a variety of gems that do the same
+thing ({<tt>twitter-auth</tt>}[http://github.com/mbleigh/twitter-auth],
+{<tt>omniauth</tt>}[http://github.com/intridea/omniauth], and
+{<tt>devise</tt>}[http://github.com/plataformatec/devise], to name a few) we decided to decouple
+this functionality so you can use the authentication library of your choosing, or none at all. If
+you would like to continue using the {<tt>oauth</tt> gem}[http://github.com/oauth/oauth-ruby],
+simply require it and make the following changes:
+
+  # Pre-1.0
+  options = {:api_endpoint => 'https://api.twitter.com', :signing_endpoint => 'https://api.twitter.com', :sign_in => true}
+  oauth = Twitter::OAuth.new(YOUR_CONSUMER_TOKEN, YOUR_CONSUMER_SECRET, options)
+  signing_consumer = oauth.signing_consumer
+  request_token = signing_consumer.get_request_token({:oauth_callback => CALLBACK_URL})
+  redirect_to request_token.authorize_url
+  oauth_token, oauth_token_secret = oauth.authorize_from_request(request_token.token, request_token.secret, 'verifier') # Use 'pin' instead of 'verifier' for PIN authentication
+
+  # Post-1.0
+  options = {:site => 'https://api.twitter.com', :request_endpoint => 'https://api.twitter.com', :authorize_path => '/oauth/authenticate'}
+  signing_consumer = OAuth::Consumer.new(YOUR_CONSUMER_TOKEN, YOUR_CONSUMER_SECRET, options)
+  request_token = signing_consumer.get_request_token({:oauth_callback => CALLBACK_URL})
+  redirect_to request_token.authorize_url
+  access_token = OAuth::RequestToken.new(signing_consumer, request_token.token, request_token.secret).get_access_token(:oauth_verifier => 'verifier') # Use 'pin' instead of 'verifier' for PIN authentication
+  oauth_token, oauth_token_secret = access_token.token, access_token.secret
 
 The public APIs defined in version 1.0 of this gem will maintain backwards compatibility until
 the next major version, following the best practice of {Semantic Versioning}[http://semver.org/].
 You are free to continue using the 0.9 series of the gem, however it will not be maintained, so
 upgrading to 1.0 is strongly recommended.
 
+Here are a few more reasons to upgrade to 1.0:
+
+* Ruby 1.9 compatibility: All code and specs now work in the latest version of Ruby
+* Support for HTTP proxies: Access Twitter from from China, Iran, or inside your office firewall
+* Support for multiple HTTP adapters: NetHttp (default), Typhoeus, Patron, or ActionDispatch
+* Support for multiple request formats: JSON (default) or XML
+* More flexible: Parse JSON or XML with the engine or your choosing via MultiJSON[http://github.com/intridea/multi_json] and MultiXML[http://github.com/sferik/multi_xml]
+* More RESTful: Use HTTP DELETE (instead of POST) when calling destructive resources
+* More methods: Request any documented resource in the Twitter API
+* Send all requests over SSL: Faster[http://gist.github.com/652330] and more secure
+* Improved error handling: More easily retry after rate-limit errors or fail whales
+
 For more information, please see the full documentation and examples of the gem's usage below.
+== Help! I'm getting RuntimeError: "Did not recognize your engine specification. Please specify either a symbol or a class."
+If you're using the JSON request format (i.e., the default), you'll need to
+explicitly require a JSON library. We recommend {<tt>yajl-ruby</tt>}[http://github.com/brianmario/yajl-ruby].
+If you're using the XML request format, we recommend requiring {<tt>libxml-ruby</tt>}[http://github.com/dvdplm/libxml-ruby] for dramatically improved performance over REXML.
 == Documentation
-=== http://rdoc.info/github/jnunemaker/twitter
+=== http://rdoc.info/gems/twitter
 == Usage Examples
   require 'rubygems'
   require 'twitter'
@@ -56,7 +105,7 @@ For more information, please see the full documentation and examples of the gem'
   # And another
   puts search.fetch_next_page.results.first.text
 
-  # Calling some methods requires an authenticated client. To get your Twitter OAuth credentials,
+  # Calling certain methods requires authentication. To get your Twitter OAuth credentials,
   # register an app at http://dev.twitter.com/apps
   Twitter.configure do |config|
     config.consumer_key = YOUR_CONSUMER_KEY