From 16b68e72f17a0d307304287f76ac045136b03d26 Mon Sep 17 00:00:00 2001
From: Fabio Rehm <fgrehm@gmail.com>
Date: Sat, 7 Dec 2013 12:36:03 -0200
Subject: [PATCH] Improve buckets docs

---
 docs/benchmarks.md         |  4 ++--
 docs/buckets/apt-cacher.md | 17 +++++++++--------
 docs/buckets/apt.md        |  9 ++++++---
 docs/buckets/chef.md       |  8 +++++---
 docs/buckets/composer.md   |  8 +++++---
 docs/buckets/npm.md        | 10 ++++++----
 docs/buckets/pacman.md     |  6 ++++--
 docs/buckets/rubygems.md   | 14 ++++++++------
 docs/buckets/rvm.md        | 14 ++++++++------
 docs/buckets/yum.md        | 10 ++++++----
 docs/buckets/zypper.md     | 10 ++++++----
 docs/index.md              |  2 +-
 docs/usage.md              | 21 +++++++++++++++++----
 13 files changed, 83 insertions(+), 50 deletions(-)

diff --git a/docs/benchmarks.md b/docs/benchmarks.md
index c0fa86d..03b9e82 100644
--- a/docs/benchmarks.md
+++ b/docs/benchmarks.md
@@ -3,8 +3,8 @@
 During the early days of this plugin, [@fgrehm](https://github.com/fgrehm) wrote
 a [blog post](http://fabiorehm.com/blog/2013/05/24/stop-wasting-bandwidth-with-vagrant-cachier#show_me_the_numbers)
 with some benchmarks on the time that was cut down by using the plugin. If you
-are interested on the numbers only, the projects tested were one of vagrant-lxc's
-Ubuntu [dev box](https://github.com/fgrehm/vagrant-lxc/wiki/Development#using-virtualbox-for-development),
+are interested on the numbers only, the VMs tested were one of vagrant-lxc's
+Ubuntu [dev boxes](https://github.com/fgrehm/vagrant-lxc/wiki/Development#using-virtualbox-for-development),
 [rails-dev-box](https://github.com/rails/rails-dev-box), his own [rails-base-box](https://github.com/fgrehm/rails-base-box)
 and Discourse's [dev box](https://github.com/discourse/discourse/blob/master/Vagrantfile)
 
diff --git a/docs/buckets/apt-cacher.md b/docs/buckets/apt-cacher.md
index 440b2e4..23ce21a 100644
--- a/docs/buckets/apt-cacher.md
+++ b/docs/buckets/apt-cacher.md
@@ -1,5 +1,11 @@
 # APT-CACHER
 
+Used by Debian-like Linux distros, will get configured under guest's `/var/cache/apt-cacher-ng`
+and only works with NFS-shared folders since `vboxsf` is enforcing `vagrant`-user and `apt-cacher`
+is running under `apt-cacher-ng` user.
+
+To manually enable it:
+
 ```ruby
 Vagrant.configure("2") do |config|
   config.vm.box = 'some-debian-box'
@@ -7,10 +13,9 @@ Vagrant.configure("2") do |config|
 end
 ```
 
-This is useful, if you are using containers inside your VMs, e.g VirtualBox -> LXC.
-This would allow you to reuse packages without sharing folder inside VirtualBox. Only
-works with NFS-shared folders (since `vboxsf` is enforcing `vagrant`-user and `apt-cacher`
-is running under `apt-cacher-ng` user)
+One use case for this bucket is if you are using containers inside your VMs, e.g
+VirtualBox -> LXC. This would allow you to reuse packages without sharing folder
+inside VirtualBox:
 
     # install apt-cacher on (Host)-VM
     $ sudo apt-get install apt-cacher-ng
@@ -23,7 +28,3 @@ is running under `apt-cacher-ng` user)
 
     # check, if working by tailing log on (Host)-VM, while installing packages on (Guest)-VMs
     $ tail -f /var/log/apt-cacher-ng/apt-cacher.log
-
-
-Used by Debian-like Linux distros, will get configured under guest's `/var/cache/apt-cacher-ng`.
-
diff --git a/docs/buckets/apt.md b/docs/buckets/apt.md
index 780892b..dba1220 100644
--- a/docs/buckets/apt.md
+++ b/docs/buckets/apt.md
@@ -1,5 +1,9 @@
 # APT
 
+Used by Debian-like Linux distros, will get configured under guest's `/var/cache/apt/archives`.
+
+To manually enable it:
+
 ```ruby
 Vagrant.configure("2") do |config|
   config.vm.box = 'some-debian-box'
@@ -7,8 +11,7 @@ Vagrant.configure("2") do |config|
 end
 ```
 
-Used by Debian-like Linux distros, will get configured under guest's `/var/cache/apt/archives`.
-
 _Please note that to avoid re-downloading packages, you should avoid `apt-get clean`
 as much as possible in order to make a better use of the cache, even if you are
-packaging a box_
+packaging a box since the downloaded packages are actually stored on the host
+machine._
diff --git a/docs/buckets/chef.md b/docs/buckets/chef.md
index 2ead6e9..20dd354 100644
--- a/docs/buckets/chef.md
+++ b/docs/buckets/chef.md
@@ -1,11 +1,13 @@
 # Chef
 
+When a Chef provisioner is detected, this bucket caches the default
+`file_cache_path` directory, `/var/chef/cache`. Requires Vagrant 1.2.4+.
+
+To manually enable it:
+
 ```ruby
 Vagrant.configure("2") do |config|
   config.vm.box = 'some-box-using-chef-provisioner'
   config.cache.enable :chef
 end
 ```
-
-When a Chef provisioner is detected, this bucket caches the default
-`file_cache_path` directory, `/var/chef/cache`. Requires Vagrant 1.2.4+.
diff --git a/docs/buckets/composer.md b/docs/buckets/composer.md
index 33f229d..2aafedb 100644
--- a/docs/buckets/composer.md
+++ b/docs/buckets/composer.md
@@ -1,11 +1,13 @@
 # [Composer](http://getcomposer.org/)
 
+Compatible with probably any type of linux guest distro, will cache guests'
+`$HOME/.composer` if PHP is detected.
+
+To manually enable it:
+
 ```ruby
 Vagrant.configure("2") do |config|
   config.vm.box = 'some-box-with-php-installed'
   config.cache.enable :composer
 end
 ```
-
-Compatible with probably any type of linux guest distro, will cache guests'
-`$HOME/.composer` if PHP is detected.
diff --git a/docs/buckets/npm.md b/docs/buckets/npm.md
index fadca00..d7f3200 100644
--- a/docs/buckets/npm.md
+++ b/docs/buckets/npm.md
@@ -1,5 +1,11 @@
 # [npm](https://npmjs.org/)
 
+Compatible with probably any type of linux guest distro, will hook into npm's
+cache directory under the result of running `npm config get cache` as
+the default SSH user (usually `vagrant`) on your guest.
+
+To manually enable it:
+
 ```ruby
 Vagrant.configure("2") do |config|
   config.vm.box = 'some-box-with-nodejs-installed'
@@ -7,10 +13,6 @@ Vagrant.configure("2") do |config|
 end
 ```
 
-Compatible with probably any type of linux guest distro, will hook into npm's
-cache directory under the result of running `npm config get cache` as
-the default SSH user (usually `vagrant`) on your guest.
-
 If you use [nvm](https://github.com/creationix/nvm) / [n](https://github.com/visionmedia/n)
 on the guest machine, make sure it is already installed before enabling
 the bucket, otherwise you won't benefit from this plugin.
diff --git a/docs/buckets/pacman.md b/docs/buckets/pacman.md
index 6393d63..360a86c 100644
--- a/docs/buckets/pacman.md
+++ b/docs/buckets/pacman.md
@@ -1,10 +1,12 @@
 # Pacman
 
+Used by Arch Linux, will get configured under guest's `/var/cache/pacman/pkg`.
+
+To manually enable it:
+
 ```ruby
 Vagrant.configure("2") do |config|
   config.vm.box = 'some-arch-linux-box'
   config.cache.enable :pacman
 end
 ```
-
-Used by Arch Linux, will get configured under guest's `/var/cache/pacman/pkg`.
diff --git a/docs/buckets/rubygems.md b/docs/buckets/rubygems.md
index 7f58cb4..ffdf8cc 100644
--- a/docs/buckets/rubygems.md
+++ b/docs/buckets/rubygems.md
@@ -1,14 +1,16 @@
 # RubyGems
 
+Compatible with probably with any type of guest distro, will hook into the `cache`
+folder under the result of running `gem env gemdir` as the default SSH user (usualy
+`vagrant`) on your guest. If you use rbenv / rvm on the guest machine, make sure
+it is already installed before enabling the bucket, otherwise you won't benefit
+from this plugin.
+
+To manually enable it:
+
 ```ruby
 Vagrant.configure("2") do |config|
   config.vm.box = 'some-box-with-ruby-installed'
   config.cache.enable :gem
 end
 ```
-
-Compatible with probably with any type of guest distro, will hook into the `cache`
-folder under the result of running `gem env gemdir` as the default SSH user (usualy
-`vagrant`) on your guest. If you use rbenv / rvm on the guest machine, make sure
-it is already installed before enabling the bucket, otherwise you won't benefit
-from this plugin.
diff --git a/docs/buckets/rvm.md b/docs/buckets/rvm.md
index e244309..a216323 100644
--- a/docs/buckets/rvm.md
+++ b/docs/buckets/rvm.md
@@ -1,14 +1,16 @@
 # [rvm](https://rvm.io/)
 
+Compatible with probably with any type of linux guest distro, will hook into the
+`cache` folder under the result of running rvm info as the default SSH user (usualy
+`vagrant`) on your guest. If you use rvm on the guest machine, make sure it is
+already installed before enabling the bucket, otherwise you won't benefit from
+this plugin.
+
+To manually enable it:
+
 ```ruby
 Vagrant.configure("2") do |config|
   config.vm.box = 'some-box-with-rvm-installed'
   config.cache.enable :gem
 end
 ```
-
-Compatible with probably with any type of linux guest distro, will hook into the
-`cache` folder under the result of running rvm info as the default SSH user (usualy
-`vagrant`) on your guest. If you use rvm on the guest machine, make sure it is
-already installed before enabling the bucket, otherwise you won't benefit from
-this plugin.
diff --git a/docs/buckets/yum.md b/docs/buckets/yum.md
index 4b3182b..8788d2b 100644
--- a/docs/buckets/yum.md
+++ b/docs/buckets/yum.md
@@ -1,12 +1,14 @@
 # Yum
 
+Used by CentOS guests, will get configured under guest's `/var/cache/yum`. It will
+also [make sure](lib/vagrant-cachier/bucket/yum.rb#L20) that `keepcache` is set to
+`1` on guest's `/etc/yum.conf`.
+
+To manually enable it:
+
 ```ruby
 Vagrant.configure("2") do |config|
   config.vm.box = 'some-centos-box'
   config.cache.enable :yum
 end
 ```
-
-Used by CentOS guests, will get configured under guest's `/var/cache/yum`. It will
-also [make sure](lib/vagrant-cachier/bucket/yum.rb#L20) that `keepcache` is set to
-`1` on guest's `/etc/yum.conf`.
diff --git a/docs/buckets/zypper.md b/docs/buckets/zypper.md
index 7c8131f..2cea5c5 100644
--- a/docs/buckets/zypper.md
+++ b/docs/buckets/zypper.md
@@ -1,12 +1,14 @@
 # Zypper
 
+Used by SuSE guests, will get configured under guest's `/var/cache/zypp/packages`. It will
+also [make sure](lib/vagrant-cachier/bucket/zypper.rb#L20) that `keep-packages` is enabled
+for all repositories.
+
+To manually enable it:
+
 ```ruby
 Vagrant.configure("2") do |config|
   config.vm.box = 'some-suse-box'
   config.cache.enable :zypper
 end
 ```
-
-Used by SuSE guests, will get configured under guest's `/var/cache/zypp/packages`. It will
-also [make sure](lib/vagrant-cachier/bucket/zypper.rb#L20) that `keep-packages` is enabled
-for all repositories.
diff --git a/docs/index.md b/docs/index.md
index ddedf92..189e48e 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -17,7 +17,7 @@ vagrant plugin install vagrant-cachier
 
 ## Quick start
 
-The easiest way to set things up is just to enable [cache buckets auto detection](config/auto-detection)
+The easiest way to set things up is just to enable [cache buckets auto detection](usage)
 from within your `Vagrantfile`:
 
 ```ruby
diff --git a/docs/usage.md b/docs/usage.md
index d90db94..214cb81 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -1,8 +1,6 @@
 # Usage
 
-## Configurations
-
-### Auto detect supported cache buckets
+## Auto detect supported cache buckets
 
 This is the easiest way to get started with plugin. By adding the code below to
 your `Vagrantfile` you can enable automatic detection of supported cache _buckets_:
@@ -17,7 +15,22 @@ end
 This will make vagrant-cachier do its best to find out what is supported on the
 guest machine and will set buckets accordingly.
 
-### Cache scope
+## Enable buckets as needed
+
+If for whatever reason you need to have a fined grained control over what buckets
+are configured, you can do so by "cherry picking" them on your `Vagrantfile`:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.cache.enable :apt
+  config.cache.enable :gem
+end
+```
+
+_Please refer to the "Available Buckets" menu above to find out which buckets
+are supported._
+
+## Cache scope
 
 By default downloaded packages will get stored on a folder scoped to base boxes
 under your `$HOME/.vagrant.d/cache`. The idea is to leverage the cache by allowing