Installation edits

README.md

@@ -43,6 +43,7 @@ tools that do one thing well.
    * [2 Installation](#section_2)
       * [2.1 Upgrading an existing installation](#section_2.1)
       * [2.2 Homebrew on Mac OS X](#section_2.2)
+      * [2.3 Neckbeard Configuration](#section_2.3)
    * [3 Usage](#section_3)
       * [3.1 rbenv global](#section_3.1)
       * [3.2 rbenv local](#section_3.2)
@@ -78,58 +79,42 @@ rbenv is `~/.rbenv/shims` in your `$PATH`.
 
 ## <a name="section_2"></a> 2 Installation
 
-rbenv is a young project, so for now you must install it from source.
+**Compatibility note**: rbenv is _incompatible_ with rvm. Things will appear to work until you try to install a gem. The problem is that rvm actually overrides the `gem` command with a shell function! Please remove any references to rvm before using rbenv.
 
-**Compatibility note**: rbenv is _incompatible_ with rvm. Things will
+### Basic GitHub checkout
-  appear to work until you try to install a gem. The problem is that
+
-  rvm actually overrides the `gem` command with a shell function!
+This will get you going with the latest version of rbenv and make it easy to fork and contribute any changes back upstream.
-  Please remove any references to rvm before using rbenv.
 
 1. Check out rbenv into `~/.rbenv`.
 
         $ cd
         $ git clone git://github.com/sstephenson/rbenv.git .rbenv
 
-2. Add `~/.rbenv/bin` to your `$PATH` for access to the `rbenv`
+2. Add `~/.rbenv/bin` to your `$PATH` for access to the `rbenv` command-line utility.
-command-line utility.
 
         $ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bash_profile
 
-    zsh users should add this line to `.zshrc` instead:
+**ZSH note**: Modifiy your `~/.zshrc` file instead of `~/.bash_profile`.
 
-        $ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .zshrc
+3. Add rbenv init to your shell to enable shims and autocompletion.
-
-3. Add rbenv's shims directory to your `$PATH` and set up Bash
-autocompletion. (If you prefer not to load rbenv in your shell, you
-can manually add `$HOME/.rbenv/shims` to your path in step 2.)
 
         $ echo 'eval "$(rbenv init -)"' >> .bash_profile
 
-    zsh users should add this line to `.zshrc` instead:
+4. Restart your shell so the path changes take effect. You can now begin using rbenv.
-
-        $ echo 'eval "$(rbenv init -)"' >> .zshrc
-
-4. Restart your shell so the path changes take effect. You can now
-begin using rbenv.
 
         $ exec $SHELL
 
-5. Install Ruby versions into `~/.rbenv/versions`. For example, to
+5. Install Ruby versions into `~/.rbenv/versions`. For example, to install Ruby 1.9.2-p290, download and unpack the source, then run:
-install Ruby 1.9.2-p290, download and unpack the source, then run:
 
         $ ./configure --prefix=$HOME/.rbenv/versions/1.9.2-p290
         $ make
         $ make install
 
-    The [ruby-build](https://github.com/sstephenson/ruby-build)
+The [ruby-build](https://github.com/sstephenson/ruby-build) provides an `rbenv install` command that simplifies the process of installing new Ruby versions to:
-    provides an `rbenv install` command that simplifies the process of
-    installing new Ruby versions to:
 
         $ rbenv install 1.9.2-p290
 
-6. Rebuild the shim binaries. You should do this any time you install
+6. Rebuild the shim binaries. You should do this any time you install a new Ruby binary (for example, when installing a new Ruby version, or when installing a gem that provides a binary).
-a new Ruby binary (for example, when installing a new Ruby version, or
-when installing a gem that provides a binary).
 
         $ rbenv rehash
 
@@ -157,17 +142,30 @@ tag:
 
 ### <a name="section_2.2"></a> 2.2 Homebrew on Mac OS X
 
-You can also install rbenv using the
+You can also install rbenv using the [Homebrew](http://mxcl.github.com/homebrew/) package manager on Mac OS X.
-[Homebrew](http://mxcl.github.com/homebrew/) package manager on Mac OS
-X.
 
     $ brew update
     $ brew install rbenv
+    $ brew install ruby-build
 
-You'll need to add rbenv's shims directory to your path afterwards
+The same commands can be used for upgrading.
-(installation step 3 above). Follow the instructions above for
+
-installing Ruby versions. (The ruby-build package can be installed
+Afterwards you'll still need to add `eval "$(rbenv init -)"` to your profile as stated in the caveats. You'll only ever have to do this once.
-with Homebrew as well.)
+
+### <a name="section_2.3"></a> 2.3 Neckbeard Configuration
+
+Skip this section unless you must know what every line in your shell profile is doing.
+
+`rbenv init` is the only command that crosses the line of loading extra commands into your shell. Coming from rvm, some of you might be opposed to this idea.
+
+Heres what `rbenv init` actually does:
+
+1. Sets up your shims path. This is the only requirement for rbenv to functional properly. You can do this by hand by prepending `~/.rbenv/shims` to your `$PATH`.
+2. Installs autocompletion. This is entirely optional but pretty useful. Sourcing `~/.rbenv/completions/rbenv.bash` will set that up. There is also a `~/.rbenv/completions/rbenv.zsh` for ZSH users.
+3. Initial rehash. From time to time you'll need to rebuild you're shim files. Doing this on init makes sure everything is up to date. `rbenv rehash` can always be ran manually.
+4. Install sh dispatcher. This bit is also optional but allows rbenv and plugins to change variables in your current shell. This makes commands like `rbenv shell` possible. This doesn't do anything crazy like override `cd` or hack your shell prompt. But for some reason you may need `rbenv` to be a real script rather than a shell function.
+
+Run `rbenv init -` for yourself to see exactly whats its doing.
 
 ## <a name="section_3"></a> 3 Usage
 

doc/README.mdtoc

@@ -61,58 +61,42 @@ rbenv is `~/.rbenv/shims` in your `$PATH`.
 
 ## Installation ##
 
-rbenv is a young project, so for now you must install it from source.
+**Compatibility note**: rbenv is _incompatible_ with rvm. Things will appear to work until you try to install a gem. The problem is that rvm actually overrides the `gem` command with a shell function! Please remove any references to rvm before using rbenv.
 
-**Compatibility note**: rbenv is _incompatible_ with rvm. Things will
+### Basic GitHub checkout
-  appear to work until you try to install a gem. The problem is that
+
-  rvm actually overrides the `gem` command with a shell function!
+This will get you going with the latest version of rbenv and make it easy to fork and contribute any changes back upstream.
-  Please remove any references to rvm before using rbenv.
 
 1. Check out rbenv into `~/.rbenv`.
 
         $ cd
         $ git clone git://github.com/sstephenson/rbenv.git .rbenv
 
-2. Add `~/.rbenv/bin` to your `$PATH` for access to the `rbenv`
+2. Add `~/.rbenv/bin` to your `$PATH` for access to the `rbenv` command-line utility.
-command-line utility.
 
         $ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bash_profile
 
-    zsh users should add this line to `.zshrc` instead:
+**ZSH note**: Modifiy your `~/.zshrc` file instead of `~/.bash_profile`.
 
-        $ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .zshrc
+3. Add rbenv init to your shell to enable shims and autocompletion.
-
-3. Add rbenv's shims directory to your `$PATH` and set up Bash
-autocompletion. (If you prefer not to load rbenv in your shell, you
-can manually add `$HOME/.rbenv/shims` to your path in step 2.)
 
         $ echo 'eval "$(rbenv init -)"' >> .bash_profile
 
-    zsh users should add this line to `.zshrc` instead:
+4. Restart your shell so the path changes take effect. You can now begin using rbenv.
-
-        $ echo 'eval "$(rbenv init -)"' >> .zshrc
-
-4. Restart your shell so the path changes take effect. You can now
-begin using rbenv.
 
         $ exec $SHELL
 
-5. Install Ruby versions into `~/.rbenv/versions`. For example, to
+5. Install Ruby versions into `~/.rbenv/versions`. For example, to install Ruby 1.9.2-p290, download and unpack the source, then run:
-install Ruby 1.9.2-p290, download and unpack the source, then run:
 
         $ ./configure --prefix=$HOME/.rbenv/versions/1.9.2-p290
         $ make
         $ make install
 
-    The [ruby-build](https://github.com/sstephenson/ruby-build)
+The [ruby-build](https://github.com/sstephenson/ruby-build) provides an `rbenv install` command that simplifies the process of installing new Ruby versions to:
-    provides an `rbenv install` command that simplifies the process of
-    installing new Ruby versions to:
 
         $ rbenv install 1.9.2-p290
 
-6. Rebuild the shim binaries. You should do this any time you install
+6. Rebuild the shim binaries. You should do this any time you install a new Ruby binary (for example, when installing a new Ruby version, or when installing a gem that provides a binary).
-a new Ruby binary (for example, when installing a new Ruby version, or
-when installing a gem that provides a binary).
 
         $ rbenv rehash
 
@@ -140,17 +124,30 @@ tag:
 
 ### Homebrew on Mac OS X ###
 
-You can also install rbenv using the
+You can also install rbenv using the [Homebrew](http://mxcl.github.com/homebrew/) package manager on Mac OS X.
-[Homebrew](http://mxcl.github.com/homebrew/) package manager on Mac OS
-X.
 
     $ brew update
     $ brew install rbenv
+    $ brew install ruby-build
 
-You'll need to add rbenv's shims directory to your path afterwards
+The same commands can be used for upgrading.
-(installation step 3 above). Follow the instructions above for
+
-installing Ruby versions. (The ruby-build package can be installed
+Afterwards you'll still need to add `eval "$(rbenv init -)"` to your profile as stated in the caveats. You'll only ever have to do this once.
-with Homebrew as well.)
+
+### Neckbeard Configuration ###
+
+Skip this section unless you must know what every line in your shell profile is doing.
+
+`rbenv init` is the only command that crosses the line of loading extra commands into your shell. Coming from rvm, some of you might be opposed to this idea.
+
+Heres what `rbenv init` actually does:
+
+1. Sets up your shims path. This is the only requirement for rbenv to functional properly. You can do this by hand by prepending `~/.rbenv/shims` to your `$PATH`.
+2. Installs autocompletion. This is entirely optional but pretty useful. Sourcing `~/.rbenv/completions/rbenv.bash` will set that up. There is also a `~/.rbenv/completions/rbenv.zsh` for ZSH users.
+3. Initial rehash. From time to time you'll need to rebuild you're shim files. Doing this on init makes sure everything is up to date. `rbenv rehash` can always be ran manually.
+4. Install sh dispatcher. This bit is also optional but allows rbenv and plugins to change variables in your current shell. This makes commands like `rbenv shell` possible. This doesn't do anything crazy like override `cd` or hack your shell prompt. But for some reason you may need `rbenv` to be a real script rather than a shell function.
+
+Run `rbenv init -` for yourself to see exactly whats its doing.
 
 ## Usage ##