Adding graphs explaining binstubs

Added a paragraph that explains what binstubs is and how it works, per feedback from @arbonap.

1 files changed, 11 insertions, 0 deletions

diff --git a/man/bundle-binstubs.ronn b/man/bundle-binstubs.ronn
index 98dcce66e0..11be49c72e 100644
--- a/man/bundle-binstubs.ronn
+++ b/man/bundle-binstubs.ronn
@@ -7,6 +7,17 @@ bundle-binstubs(1) -- Install the binstubs of the listed gems
 
 ## DESCRIPTION
 
+Binstubs are scripts that wrap aroung executables. Bundler creates a 
+small Ruby file (a binstub) that loads Bundler, runs the command, 
+and puts it into `bin/`. Binstubs are a shortcut—or alternative—
+to always using `bundle exec`, with the additional benefit of linking 
+the binstub inside of an application to the exact version of the gem the
+application needs.
+
+For example, if you run `bundle binstubs rspec-core`, Bundler will create 
+the file `bin/rspec`. That file will contain just enough code to load Bundler, 
+tell it to load the bundled gems, and then run rspec.
+
 This command generates binstubs for executables in `GEM_NAME`.
 Binstubs are put into `bin`, or the `--path` directory if one has been set.
 Calling binstubs with [GEM [GEM]] will create binstubs for all given gems.