Fix for important missing step in macOS Installation Docs: Add the Homebrew gems directory to the PATH

[monfresh]

When you install Ruby with Homebrew, and you install a gem the regular
way, without any flags, it gets installed in
/usr/local/lib/ruby/gems/2.7.0/bin. If that directory is not in the
PATH, you will get "command not found" when trying to use that gem.

This is a common issue people run into when they type
gem install jekyll instead of gem install jekyll --user-install.
Do a search for "jekyll: command not found" in your favorite search
engine, in GitHub, Stack Overflow, etc.

Updating the documentation to also include the gems directory will
prevent this issue and will make people happier.

Ideally, if this were my project, I would replace pretty much this
entire document with 3 steps:

1. Link to a reliable, repeatable script that can set up a proper
   Ruby environment with a Ruby manager

2. Quit and restart Terminal

3. gem install jekyll

It should, and can be this easy.

Here are examples of scripts I have written:
https://github.com/monfresh/install-ruby-on-macos
https://github.com/monfresh/laptop/

Discourse is another example of a Ruby project that provides a script:
https://meta.discourse.org/t/beginners-guide-to-install-discourse-on-macos-for-development/15772

Summary

Context

[MichaelCurrin]

Thanks for the suggestions. Yes I agree something is missing from the docs.

Looking at just the Install Ruby section modified, the changes would be okay. But, theyvconflict with the flow with rest of the doc so more work is needed. See my notes below.

Note that the page sections are

## Install Ruby

## Install Jekyll

### Local install

### Global install

The decision on whether to use user gems or shared gems directory and PATH setup should be deferred to Install Jekyll section I think, not the Install Ruby section as the PR currently proposes.

The local section covers the --user-install flag.
Including how to add the .gem bin path to PATH. So that can stay as is.

If you were to add to PATH as /usr/local/lib... then the Global Install part at the end of the doc would better than at the Ruby section. Maybe a new Catalina+ section, or rename Mojave+ to be Catalina+.

For additional clarity, we can number the steps e.g. ## 1. Install Ruby. Or, at the very top, give an overview saying the doc covers Ruby and then Jekyll with heading links for each. That especially helps to skip past the rbenv section in the middle

[MichaelCurrin]

I think having the control and awareness over a few lines to run individually is better than having a script which does convenient but obscured steps. Including if a user wants to know what lines actually got run.

It is also simpler for the community to maintain the lines into this doc than an external script which handles a lot of automation and decision making which adds overheard for those no familiar with the script.

The doc is broken up into neat sections so you can use rbenv if you want, you can use bundler if your want etc. and you can change any given line and run it in your terminal. Instead of getting locked into a longer script that handles all the possible decisions or leaves some out

[monfresh]

Here's the problem:

1. Someone installs Ruby with Homebrew
2. They don't add the Homebrew gems location to their PATH
3. They try to install some other gems later on, like rails or whatever using just gem install rails, without the --user-install flag because you rarely see that in gem installation instructions.
4. They try to use the gem they just installed, but they can't because it's not in their PATH.

This happens with jekyll too. Many people install Ruby with Homebrew, but then they install Jekyll with gem install jekyll and when they try jekyll -v or jekyll new, it says it can't find it.

Setting the PATH is part of the Ruby installation process. If you install Ruby with Homebrew, your PATH needs to include the Homebrew gems location. If the Jekyll site is the first place people go to install Ruby, then by not telling them to update the PATH within the Homebrew installation section, we are preventing them from using other gems they might install later on.

It doesn't hurt to have both the Homebrew gems location and the $HOME/.gem/ruby/X.X.0/bin in your PATH at the same time, so why not add the instruction where people are already likely to follow it?

The instructions are already too long and complicated as it is IMO. I don't think people are going to keep reading down below in the Global install section, especially if it has a big red warning, which I don't understand why that is there. If you install Ruby properly, there aren't any permissions errors and you don't have to use sudo, even in Mojave. I have never had to use sudo to install any gems on any macOS over the past 8 years, as long as it had a proper Ruby development environment, and I've always used gem install without the --user-install flag.

In my opinion, I think there are too many options in the instructions. I think it's best to just pick one and keep it simple. If it were up to me, I would leave just the rbenv section (or chruby), and then tell people to use gem install jekyll. That's it.

[MichaelCurrin]

That makes sense. Adding the instructions as part of Ruby install section.

[MichaelCurrin]

As an improvement, how about making the code dynamic for Ruby version? So then it will work regardless of using 2.6 or 2.7 and handles updates.

I use this to dynamically lookup the path for my user's gems.

GEM_PATH="$(ruby -r rubygems -e 'puts Gem.user_dir')/bin"
PATH="$GEM_PATH:$PATH"

I haven't found an equivalent to get the /usr/... directory.

Alternatively, lookup the current ruby version and replace the minor version with .0 - as in /usr/local/lib/ruby/gems/$VERSION/bin

[DirtyF]

@jekyll: merge +docs