README.md in librarian-0.0.4 vs README.md in librarian-0.0.5

@@ -12,39 +12,52 @@
 Librarian::Chef
 ---------------
 
 An adapter for Librarian applying to Chef cookbooks in a Chef Repository.
 
-Usage:
+## Install librarian:
 
-    # install librarian onto your system
     $ gem install librarian
 
-    $ cd ~/path/to/chef-repo
 
-    # make sure your cookbooks directory exists but is gitignored
+__Make sure your cookbooks directory is gitignored__
+
+    $ cd ~/path/to/chef-repo
     $ git rm -r cookbooks # if the directory is present
-    $ mkdir cookbooks
     $ echo cookbooks >> .gitignore
 
-    # put dependencies and their sources into Cheffile
+Note that librarian *takes over* your cookbooks directory
+  and manages it for you based on your Cheffile. Your
+  Cheffile becomes the authoritative source for what
+  cookbooks you have, rather than the directories in your
+  cookbooks directory.
+
+__Make a Cheffile__
+
+    $ librarian-chef init
+
+__Add dependencies and their sources to Cheffile__
+
     $ cat Cheffile
         site 'http://community.opscode.com/api/v1'
         cookbook 'ntp'
         cookbook 'timezone'
         cookbook 'rvm',
           :git => 'https://github.com/fnichol/chef-rvm',
           :ref => 'v0.7.1'
 
-    # install dependencies into ./cookbooks
+__install dependencies into ./cookbooks__
+
     $ librarian-chef install [--clean] [--verbose]
 
-    # check into version control your ./Cheffile.lock
+__Check your Cheffile.lock into version control__
+
     $ git add Cheffile.lock
     $ git commit -m "I want these particular versions of these particular cookbooks from these particular."
 
-    # update your cheffile with new/changed/removed constraints/sources/dependencies
+__Update your cheffile with new/changed/removed constraints/sources/dependencies__
+
     $ cat Cheffile
         site 'http://community.opscode.com/api/v1'
         cookbook 'ntp'
         cookbook 'timezone'
         cookbook 'rvm',
@@ -56,20 +69,23 @@
     $ git diff Cheffile.lock
     $ git add Cheffile
     $ git add Cheffile.lock
     $ git commit -m "I also want these additional cookbooks."
 
-    # update the version of a dependency
+__Update the version of a dependency__
+
     $ librarian-chef update ntp timezone monit [--verbose]
     $ git diff Cheffile.lock
     $ git add Cheffile.lock
     $ git commit -m "I want updated versions of these cookbooks."
 
-    # push your changes to the git repository
+__Push your changes to the git repository__
+
     $ git push origin master
 
-    # upload the cookbooks to your chef-server
+__Upload the cookbooks to your chef-server__
+
     $ knife cookbook upload --all
 
 You should `.gitignore` your `./cookbooks` directory.
 If you are manually tracking/vendoring outside cookbooks within the repository,
   put them in another directory such as `./cookbooks-sources` and use the `:path` source.
@@ -85,9 +101,14 @@
   cookbooks in your `Cheffile`, make sure *not* to include the paths to those additional
   cookbooks directories either in your chef-repo. Since your `chef-repo/site-cookbooks`
   directory is for overrides (monkey-patches) to external cookbooks, and since you should
   not have any `:path`-sourced cookbooks in your `Cheffile` sourced from that directory,
   you still need to include your `chef-repo/site-cookbooks` directory in the above list.
+
+What this integration does is when you use `knife`, it will enforce that your `Cheffile`
+  and `Cheffile.lock` are in sync. When you `knife cookbook upload`, it will be sure to
+  upload the same cookbook as is in your `Cheffile.lock`, regardless of what you've done
+  to your `chef-repo/cookbooks` directory.
 
 License
 -------
 
 Written by Jay Feldblum.