Touch up README for comprehension and clarity (#2051)

README.md

@@ -1,34 +1,37 @@
 # ruby-build
 
-ruby-build is a command-line utility that makes it easy to install virtually any
+ruby-build is a command-line tool that simplifies installation of any Ruby version from source on Unix-like systems.
-version of Ruby, from source.
 
-It is available as a plugin for [rbenv][] that
+It is available as a plugin for [rbenv][] as the `rbenv install` command, or as a standalone program as the `ruby-build` command.
-provides the `rbenv install` command, or as a standalone program.
 
 ## Installation
 
+### Homebrew package manager
 ```sh
-# Using Homebrew on macOS
+brew install ruby-build
-$ brew install ruby-build
-
-# As an rbenv plugin
-$ mkdir -p "$(rbenv root)"/plugins
-$ git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build
-
-# As a standalone program
-$ git clone https://github.com/rbenv/ruby-build.git
-$ PREFIX=/usr/local ./ruby-build/install.sh
 ```
 
-### Upgrading
+Upgrade with:
-
 ```sh
-# Via Homebrew
+brew update && brew upgrade ruby-build
-$ brew update && brew upgrade ruby-build
+```
 
-# As an rbenv plugin
+### Clone as rbenv plugin using git
-$ git -C "$(rbenv root)"/plugins/ruby-build pull
+```sh
+git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build
+```
+
+Upgrade with:
+```sh
+git -C "$(rbenv root)"/plugins/ruby-build pull
+```
+
+### Install manually as a standalone program
+
+First, download a tarball from https://github.com/rbenv/ruby-build/releases/latest. Then:
+```sh
+tar -xzf ruby-build-*.tar.gz
+PREFIX=/usr/local ./ruby-build-*/install.sh
 ```
 
 ## Usage
@@ -45,20 +48,25 @@ $ ruby-build --definitions             # lists all available versions of Ruby
 $ ruby-build 2.2.0 ~/local/ruby-2.2.0  # installs Ruby 2.2.0 to ~/local/ruby-2.2.0
 ```
 
-ruby-build does not check for system dependencies before downloading and
+> **Warning**  
-attempting to compile the Ruby source. Please ensure that [all requisite
+> ruby-build mostly does not verify that system dependencies are present before downloading and attempting to compile Ruby from source. Please ensure that [all requisite libraries][build-env] such as build tools and development headers are already present on your system.
-libraries][build-env] are available on your system.
+
+Basically, what ruby-build does when installing a Ruby version is this:
+- Downloads an official tarball of Ruby source code;
+- Extracts the archive into a temporary directory on your system;
+- Executes `./configure --prefix=/path/to/destination` in the source code;
+- Runs `make install` to compile Ruby;
+- Verifies that the installed Ruby is functional.
+
+Depending on the context, ruby-build does a little bit more than the above: for example, it will try to link Ruby to the appropriate OpenSSL version, even if that means downloading and compiling OpenSSL itself; it will discover and link to Homebrew-installed instances of some libraries like libyaml and readline, etc.
 
 ### Advanced Usage
 
 #### Custom Build Definitions
 
-If you wish to develop and install a version of Ruby that is not yet supported
+To install a version of Ruby that is not recognized by ruby-build, you can specify the path to a custom build definition file in place of a Ruby version number.
-by ruby-build, you may specify the path to a custom “build definition file” in
-place of a Ruby version number.
 
-Use the [default build definitions][definitions] as a template for your custom
+Check out [default build definitions][definitions] as examples on how to write definition files.
-definitions.
 
 #### Custom Build Configuration
 
@@ -90,9 +98,7 @@ The build process may be configured through the following environment variables:
 
 #### Applying Patches
 
-Both `rbenv install` and `ruby-build` support the `--patch` (`-p`) flag to apply
+Both `rbenv install` and `ruby-build` commands support the `-p/--patch` flag to apply a patch to the Ruby source code before building. Patches are read from standard input:
-a patch to the Ruby (/JRuby/Rubinius/TruffleRuby) source code before building.
-Patches are read from `STDIN`:
 
 ```sh
 # applying a single patch
@@ -107,12 +113,9 @@ $ cat fix1.patch fix2.patch | rbenv install --patch 1.9.3-p429
 
 #### Checksum Verification
 
-If you have the `shasum`, `openssl`, or `sha256sum` tool installed, ruby-build will
+All Ruby definition files bundled with ruby-build include checksums for packages, meaning that all externally downloaded packages are automatically checked for integrity after fetching.
-automatically verify the SHA2 checksum of each downloaded package before
-installing it.
 
-Checksums are optional and specified as anchors on the package URL in each
+See the next section for more information on how to author checksums.
-definition. All definitions bundled with ruby-build include checksums.
 
 #### Package Mirrors
 
@@ -161,7 +164,7 @@ If you can't find an answer on the wiki, open an issue on the [issue tracker][].
 Be sure to include the full build log for build failures.
 
 
-  [rbenv]: https://github.com/rbenv/rbenv
+  [rbenv]: https://github.com/rbenv/rbenv#readme
   [definitions]: https://github.com/rbenv/ruby-build/tree/master/share/ruby-build
   [wiki]: https://github.com/rbenv/ruby-build/wiki
   [build-env]: https://github.com/rbenv/ruby-build/wiki#suggested-build-environment