1 files changed, 68 insertions, 0 deletions
diff --git a/docs/modules/install/pages/ruby-packaging.adoc b/docs/modules/install/pages/ruby-packaging.adoc
new file mode 100644
index 00000000..8dbf98c8
--- /dev/null
+++ b/docs/modules/install/pages/ruby-packaging.adoc
@@ -0,0 +1,68 @@
+= Install Using Ruby Packaging
+
+[#gem-install]
+== gem install
+
+Before installing Asciidoctor using `gem install`, you should set up {url-rvm}[RVM^] to install Ruby in your home directory (i.e., user space).
+Then, you can safely use the `gem` command to install or update the Asciidoctor gem, or any other gem for that matter.
+When using RVM, gems are installed in a location isolated from the system.
+
+Once you've installed Ruby using RVM, and you have activated it using `rvm use {ruby-short}`, open a terminal and type:
+
+ $ gem install asciidoctor
+
+include::partial$success.adoc[]
+
+[#pre-release]
+=== Install a pre-release version
+
+To install a pre-release version of Asciidoctor (e.g., a release candidate), open a terminal and type:
+
+ $ gem install asciidoctor --pre
+
+== Bundler
+
+. Create a Gemfile in the root folder of your project (or the current directory)
+. Add the `asciidoctor` gem to your Gemfile as follows:
++
+[source,ruby,subs=attributes+]
+----
+source 'https://rubygems.org'
+gem 'asciidoctor'
+# or specify the version explicitly
+# gem 'asciidoctor', '{release-version}'
+----
+
+. Save the Gemfile
+. Open a terminal and install the gem using:
+
+ $ bundle
+
+To upgrade the gem, specify the new version in the Gemfile and run `bundle` again.
+Using `bundle update` (without specifying a gem) is *not* recommended as it will also update other gems, which may not be the desired result.
+
+[#gem-update]
+== Upgrade using gem update
+
+[CAUTION]
+====
+You're advised against using the `gem update` command to update a gem managed by the package manager.
+Doing so puts the system into an inconsistent state as the package manager can no longer track the files (which get installed under [.path]_/usr/local_).
+Simply put, system gems should only be updated by the package manager.
+
+If you want to use a version of Asciidoctor that is newer than what is installed by the package manager, you should use {url-rvm}[RVM^] to install Ruby in your home directory (i.e., user space).
+Then, you can safely use the `gem` command to install or update the Asciidoctor gem.
+When using RVM, gems are installed in a location isolated from the system.
+====
+
+You can upgrade Asciidoctor using the gem `update` command:
+
+ $ gem update asciidoctor
+
+[TIP]
+====
+If you accidentally use `gem install` instead of `gem update`, then you'll end up with both versions installed.
+To remove the older version, use the following `gem` command:
+
+ $ gem cleanup asciidoctor
+====