README.rdoc in fcoury-octopi-0.0.6 vs README.rdoc in fcoury-octopi-0.0.7

@@ -2,23 +2,36 @@
 
 Octopi is a Ruby interface to GitHub API v2 (http://develop.github.com). It's under early but active development and already works.
 
 == Authenticated Usage
 
-The following examples requires a valid user authenticated with GitHub using login and API token. This information can be found on our profile (the link is inside the "badge" that is displayed on the upper right corner when you're logged in).
+=== Seamless authentication using .gitconfig defaults
 
-Once you found your login and token you can run authenticated commands using:
+If you have your <tt>~/.gitconfig</tt> file in place, and you have a [github] section (if you don't, take a look at this GitHub Guides entry: http://github.com/guides/tell-git-your-user-name-and-email-address), you can use seamless authentication using this method:
 
+  authenticated do |g|
+    repo = g.repository("api-labrat")
+    (...)
+  end
+  
+=== Explicit authentication
+
+Sometimes, you may not want to get authentication data from <tt>~/.gitconfig</tt>. You want to use GitHub API authenticated as a third party. For this use case, you have a couple of options too.
+
+<b>1. Providing login and token inline:</b>
+
   authenticated_with "mylogin", "mytoken" do |g|
     repo = g.repository("api-labrat")
     issue = repo.open_issue :title => "Sample issue", 
       :body => "This issue was opened using GitHub API and Octopi"
     puts issue.number
   end
   
-You can also create a YAML file with your information, with the following format:
+<b>2. Providing a YAML file with authentication information:</b>
 
+Use the following format:
+
   #
   # Octopi GitHub API configuration file
   #
 
   # GitHub user login and token
@@ -30,24 +43,16 @@
   #   false - no tracing, same as if the param is ommited
   #   true  - will output each POST or GET operation to the stdout
   #   curl  - same as true, but in addition will output the curl equivalent of each command (for debugging)
   trace: curl
   
-And change the way you connect to:
+This changes the way you connect to:
 
   authenticated_with :config => "github.yml" do |g|
     (...)
   end
-
-This way you can benefit from better debugging when something goes wrong. If you choose curl tracing, the curl command equivalent to each command sent to GitHub will be output to the stdout, like this example:
-
-  => Trace on: curl
-  POST: /issues/open/webbynode/api-labrat params: body=This issue was opened using GitHub API and Octopi, title=Sample issue
-  ===== curl version
-  curl -F 'body=This issue was opened using GitHub API and Octopi' -F 'login=mylogin' -F 'token=mytoken' -F 'title=Sample issue' http://github.com/api/v2/issues/open/webbynode/api-labrat
-  ==================
-
+  
 == Anonymous Usage
 
 This reflects the usage of the API to retrieve information, on a read-only mode where the user doesn't have to be authenticated.
 
 === Users API
@@ -102,15 +107,56 @@
 Single commit information:
 
   puts "Diff:"
   first_commit.details.modified.each {|m| puts "#{m['filename']} DIFF: #{m['diff']}" }
 
+== Tracing
+
+=== Levels
+
+You can can use tracing to enable better debugging output when something goes wrong. There are 3 tracing levels: 
+
+* false (default) - no tracing
+* true - will output each GET and POST calls, along with URL and params
+* curl - same as true, but additionally outputs the curl command to replicate the issue
+
+If you choose curl tracing, the curl command equivalent to each command sent to GitHub will be output to the stdout, like this example:
+
+  => Trace on: curl
+  POST: /issues/open/webbynode/api-labrat params: body=This issue was opened using GitHub API and Octopi, title=Sample issue
+  ===== curl version
+  curl -F 'body=This issue was opened using GitHub API and Octopi' -F 'login=mylogin' -F 'token=mytoken' -F 'title=Sample issue' http://github.com/api/v2/issues/open/webbynode/api-labrat
+  ==================
+  
+=== Enabling
+
+Tracing can be enabled in different ways, depending on the API feature you're using:
+
+<b>Anonymous (this will be improved later):</b>
+
+  ANONYMOUS_API.trace_level = "trace-level"
+  
+<b>Seamless authenticated</b>
+
+  authenticated :trace => "trace-level" do |g|; ...; end
+  
+<b>Explicitly authenticated</b>
+
+Current version of explicit authentication requires a :config param to a YAML file to allow tracing. For enabling tracing on a YAML file refer to the config.yml example presented on the Explicit authentication section.
+
 == Author
 
 * Felipe Coury - http://felipecoury.com
 * HasMany.info blog - http://hasmany.info
 
-== Copyright
+== Contributors
 
-DISCLAIMER: The name of this library is pronounced <i>octo-pie</i> but no Octocats were harmed during its creation. It's not really an Octo Pie, but a contraction of the words Octocat and API.
+In alphabetical order:
+
+* Brandon Calloway - http://github.com/bcalloway
+* runpaint - http://github.com/runpaint
+
+Thanks guys!
+
+== Copyright
 
 Copyright (c) 2009 Felipe Coury. See LICENSE for details.