Auto merge of #5892 - arbonap:pa-gemfile-doc-changes, r=colby-swandale

Add more background explanations to bundle-install and gemfile docs

Thanks so much for the contribution!
To make reviewing this PR a bit easier, please fill out answers to the following questions.

### What was the end-user problem that led to this PR?

The problem was...
- I thought the `bundle-install` and `gemfile` docs could have more background explanations.

### What was your diagnosis of the problem?

My diagnosis was...
- Given more clarifying background information regarding some Ruby-specific domain knowledge, this can help those newer to the Ruby community. ♦️

### What is your fix for the problem, implemented in this PR?

My fix...
- I gave a general overview of various Ruby implementations, and explained what git submodules and gemspecs are.
### Why did you choose this fix out of the possible options?

I chose this fix because...
- @rubymorillo and @indirect gave me the go-ahead to give more background information about these topics 👍🏽
- please let me know what y'all think, I'm happy to incorporate edits

1 files changed, 31 insertions, 0 deletions

diff --git a/man/gemfile.5.ronn b/man/gemfile.5.ronn
index dead032ced..9baa7f8e3e 100644
--- a/man/gemfile.5.ronn
+++ b/man/gemfile.5.ronn
@@ -69,6 +69,22 @@ the Ruby version that the engine is compatible with.
 Each application _may_ specify a Ruby engine. If an engine is specified, an
 engine version _must_ also be specified.
 
+What exactly is an Engine?
+  - A Ruby engine is an implementation of the Ruby language.
+
+  - For background: the reference or original implementation of the Ruby
+    programming language is called
+    [Matz's Ruby Interpreter](https://en.wikipedia.org/wiki/Ruby_MRI), or  MRI
+    for short. This is named after Ruby creator Yukihiro Matsumoto,
+    also known as Matz. MRI is also known as CRuby, because it is written in C.
+    MRI is the most widely used Ruby engine.
+
+  - [Other implementations](https://www.ruby-lang.org/en/about/) of Ruby exist.
+    Some of the more well-known implementations include
+    [Rubinius](https://rubinius.com/), and [JRuby](http://jruby.org/).
+    Rubinius is an alternative implementation of Ruby written in Ruby.
+    JRuby is an implementation of Ruby on the JVM, short for Java Virtual Machine.
+
 ### ENGINE VERSION
 
 Each application _may_ specify a Ruby engine version. If an engine version is
@@ -287,7 +303,17 @@ Git repositories support a number of additional options.
   * `branch`, `tag`, and `ref`:
     You `MUST` only specify at most one of these options. The default
     is `:branch => "master"`
+  * For example:
+
+      git "https://github.com/rails/rails.git", :branch => "5-0-stable" do
+
+      git "https://github.com/rails/rails.git", :tag => "v5.0.0" do
+
+      git "https://github.com/rails/rails.git", :ref => "4aded" do
+
   * `submodules`:
+    For reference, a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
+    lets you have another git repository within a subfolder of your repository.
     Specify `:submodules => true` to cause bundler to expand any
     submodules included in the git repository
 
@@ -439,6 +465,11 @@ software is installed or some other conditions are met.
 
 ## GEMSPEC
 
+The [.gemspec](http://guides.rubygems.org/specification-reference/) file is where
+ you provide metadata about your gem to Rubygems. Some required Gemspec
+ attributes include the name, description, and homepage of your gem. This is
+ also where you specify the dependencies your gem needs to run.
+
 If you wish to use Bundler to help install dependencies for a gem while it is
 being developed, use the `gemspec` method to pull in the dependencies listed in
 the `.gemspec` file.