(maint) Add detailed docs on GEM_HOME and JRuby REPL's

Without this patch the developer documentation does not inform the
reader how to install Ruby gem dependencies when running in development
mode, and how this process is subtly different from installing Gems for
use with JRuby spec tests and for use with a packaged `puppetserver`
install.  This is a problem because developers may need to install
support libraries such as `pry` in an effort to get a REPL much the same
way the lein repl is used and it is not clear how to accomplish this
given the three scenarios of from packages (production), development,
and testing.

This patch addresses the problem by providing detailed information about
how to install gem dependencies when running puppetserver from source
and how the process differs from installing gem dependencies for testing
and for production packages.

The change also addresses a known issue when running the pry repl from
within the lein repl where by STDIN is not shared between the two and
JRuby REPLs cannot read user input.

This patch also changes all occurrences of `$ puppetserver gem install`
to `$ sudo puppetserver gem install` because the former does not work as
expected as described in SERVER-263.
On Wed, Dec 17, 2014 at 12:51 PM, Eli Young <notifications@github.com>
wrote:
>
> In documentation/gems.markdown
> <https://github.com/puppetlabs/puppet-server/pull/332#discussion-diff-22003058>
> :
>
> >  ## Installing And Removing Gems
> >
> >  We isolate the Ruby load paths that are accessible to Puppet Server's
> >  JRuby interpreter, so that it doesn't load any gems or other code that
> >  you have installed on your system Ruby. If you want Puppet Server to load additional gems, use the Puppet Server-specific `gem` command to install them. For example, to install the foobar gem, use:
> >
> > -`puppetserver gem install foobar`
> > +    $ sudo puppetserver gem install -- foobar --no-ri --no-rdoc
>
> Is the -- necessary here?
>
It is given --no-ri and --no-rdoc.  Some other option parser
(puppetserver's presumably) gobbles the options without it and then barfs.

I wanted to include it as an example and --no-ri --no-rdoc are commonly
used to speed up installation.

-Jeff