Write a Ruby environment setup guide

[mojavelinux]

Installation is always a challenge, especially for users unfamiliar with an environment. Since many of the setup guides ask the user to have Ruby installed and to install one or more gems, we need a page that we can point the reader to when things aren't going as expected.

This page should cover the following:

1. How to install Ruby
2. How to prepare the Ruby environment for gem installation
3. How to install a gem
4. How to verify that a gem was installed

Once the reader gets through these tasks on their system, they should have no problem installing and running a Ruby application.

We should consider the following environments:

• Fedora
• Debian / Ubuntu
• OS X (see http://asciidoctor.org/docs/install-asciidoctor-macosx/)
• Windows
• Cygwin

Part of this guide should cover RVM as an alternative choice for setting up Ruby on *nix systems (including Cygwin) and when it's use is appropriate.

To cite an example of one of the challenges readers are running into, on Cygwin, gems install into $HOME/.gem with binstubs in $HOME/bin. However, $HOME/bin is not on the user's PATH by default. Thus, after installing the gem, the command (such as asciidoctor) cannot be immediately used. This causes confusion (and despair) for the user.

For background on this issue, see asciidoctor/asciidoctor-pdf#208 and http://discuss.asciidoctor.org/Gem-paths-craziness-on-cygwin-td3425.html.

[mojavelinux]

Here's a decent guide on how to setup RVM on Ubuntu (ignore the rails part).

https://www.digitalocean.com/community/tutorials/how-to-install-ruby-on-rails-on-ubuntu-14-04-using-rvm

[mojavelinux]

I can't overemphasize how strongly I recommend RVM. When you are using Ruby for development (and otherwise in user space), you should not be interacting with the system Ruby. The system Ruby is for system things. If you are using "sudo" to install gems, you are mucking with the system Ruby and venturing into dangerous territory. This guide should make that point and make it very strongly.

[mojavelinux]

Ruby install instructions for Alpine Linux:

=== Install with `apk`

To install Ruby on Alpine Linux:

. Open a terminal
. Type the +apk+ command using sudo

 $ sudo apk add ruby

The benefit of installing the gem via `apk` is that the package manager will also install Ruby and RubyGems if not already on your machine.

Captured from the following PR: #254.

[mojavelinux]

Related to #884.