use the term gem instead of RubyGem to refer to a gem; reword the installation overview

9 files changed, 27 insertions, 24 deletions

diff --git a/docs/modules/ROOT/pages/features.adoc b/docs/modules/ROOT/pages/features.adoc
index f2b9c143..9a5ac3f3 100644
--- a/docs/modules/ROOT/pages/features.adoc
+++ b/docs/modules/ROOT/pages/features.adoc
@@ -7,8 +7,8 @@
 
 Asciidoctor is written in Ruby, which means it must be run on a Ruby language runtime (including JRuby).
 But that's its only requirement.
-Asciidoctor is packaged and distributed as a {url-rubygems}/asciidoctor[RubyGem to the package repository at RubyGems.org^].
-The gem can be installed on *any operating system* Ruby supports using Ruby's package management tools (gem or bundle).
+Asciidoctor is packaged and distributed as a gem named {url-rubygems}/asciidoctor[asciidoctor^] to the package repository at {url-rubygems}[RubyGems.org^].
+The gem can be installed on *any operating system* that Ruby supports using Ruby's package management tools (gem or bundle).
 Asciidoctor itself has no dependencies.
 
 But what if you aren't familiar with Ruby or, for whatever reason, prefer not to install it?
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
index d431dcb4..814beb96 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -8,15 +8,15 @@ If you're looking for the documentation for the AsciiDoc language, see the xref:
 
 == What is Asciidoctor?
 
-Asciidoctor is a fast, open source, text processor for parsing AsciiDoc into a document model and converting it to output formats such as [.nowrap]#HTML 5#, [.nowrap]#DocBook 5#, man(ual) pages, PDF, and [.nowrap]#EPUB 3#.
+Asciidoctor is a fast, open source, text processor for parsing AsciiDoc into a document model, then converting it to output formats such as [.nowrap]#HTML 5#, [.nowrap]#DocBook 5#, man(ual) pages, PDF, and [.nowrap]#EPUB 3#.
 Asciidoctor is written in the Ruby programming language.
 
-//This Ruby library (or gem) is often referred to as the core Asciidoctor processor, or _Asciidoctor core_ for short.
-When we say Asciidoctor in this area of the documentation, we're referring to the core Asciidoctor Ruby processor, abbreviated as _Asciidoctor core_ (and sometimes _Asciidoctor Ruby_).
-We add the qualifier "`core`" because Asciidoctor is also the name of the suite of projects that provide runtimes, extensions, and tools for processing AsciiDoc.
+When we use the name "`Asciidoctor`" in this area of the documentation, we're referring to the core Asciidoctor Ruby processor, abbreviated as _Asciidoctor core_ or _Asciidoctor Ruby_.
+We add the qualifier "`core`" because Asciidoctor is also the name of the suite of projects that provides runtimes, extensions, and tools for processing AsciiDoc.
 
-To simplify installation, Asciidoctor is packaged and distributed to RubyGems.org as a {url-rubygems}/asciidoctor[RubyGem named asciidoctor^].
-The asciidoctor gem can be installed on all major operating systems using Ruby packaging tools (gem or bundle).
+To simplify installation, Asciidoctor is packaged as a gem named {url-rubygems}/asciidoctor[asciidoctor^] and published to the gem hosting service located at RubyGems.org.
+A https://guides.rubygems.org/what-is-a-gem/[gem^] is a packaged Ruby application or library (in this case, both).
+The *asciidoctor* gem can be installed directly from RubyGems.org on all major operating systems using Ruby packaging tools (gem or bundle).
 Asciidoctor is also distributed as a Docker image, as a package for numerous Linux distributions, and as a package for macOS (via Homebrew and MacPorts).
 
 Asciidoctor is open source software available under the terms of the MIT license and {url-org}[hosted on GitHub^].
diff --git a/docs/modules/extensions/pages/index.adoc b/docs/modules/extensions/pages/index.adoc
index e658fe48..c4dcd1f8 100644
--- a/docs/modules/extensions/pages/index.adoc
+++ b/docs/modules/extensions/pages/index.adoc
@@ -6,7 +6,7 @@ Asciidoctor provides an {url-api-gems}/asciidoctor/{release-version}/Asciidoctor
 As a result, extensions in Asciidoctor are easy to write, powerful, and simple to distribute.
 
 Asciidoctor also allows extensions to be written using the full power of a programming language (whether it be Ruby, Java, Groovy or JavaScript).
-You don't have to shave yaks to get the functionality you want, and you can distribute the extension using de facto standard packaging mechanisms like RubyGems or JARs.
+You don't have to shave yaks to get the functionality you want, and you can distribute the extension using de facto standard packaging mechanisms like gems or JARs.
 
 == Available extension points
 
diff --git a/docs/modules/install/pages/index.adoc b/docs/modules/install/pages/index.adoc
index 62ac67a9..6206bf40 100644
--- a/docs/modules/install/pages/index.adoc
+++ b/docs/modules/install/pages/index.adoc
@@ -1,7 +1,7 @@
 = Install and Update
 
-To simplify installation, Asciidoctor is packaged and published as a {url-rubygems}/asciidoctor[RubyGem to the package repository at RubyGems.org^].
-It's also distributed as a package for popular Linux distributions and macOS.
+To simplify installation, Asciidoctor is packaged as a gem and published to the gem hosting service at {url-rubygems}/asciidoctor[RubyGems.org^].
+Asciidoctor is also distributed as a managed package for popular Linux distributions and macOS.
 
 TIP: In addition to running on Ruby, Asciidoctor can be executed on a JVM using xref:asciidoctorj::index.adoc[AsciidoctorJ] or in any JavaScript environment (including the browser) using xref:asciidoctor.js::index.adoc[Asciidoctor.js].
 
@@ -15,10 +15,11 @@ Asciidoctor can be installed using:
 * the `gem install` command (recommended for Windows users), or
 * the Asciidoctor Docker image
 
+IMPORTANT: To update or uninstall Asciidoctor, you should use the same method you used to install it.
+
 Bundler is the preferred method of installation as it keeps the gems scoped to your project or workspace.
-However, it does not make the `asciidoctor` command globally available in your terminal.
+However, this method of installation does not make the `asciidoctor` command available globally in your terminal.
 That's when a package manager is more appropriate.
-The benefit of using your operating system's package manager to install the gem is that it adds the `asciidoctor` command to your PATH and it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine.
-On the other hand, if you're familiar with Docker, using the Asciidoctor Docker image gives you the best isolation from your system.
 
-You should use the same method to update and uninstall Asciidoctor as you use to install it.
+The benefit of using your operating system's package manager to install the gem is that it adds the `asciidoctor` command to your PATH and it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine.
+On the other hand, if you're familiar with Docker, using the Asciidoctor Docker image may give you the best isolation from your system.
diff --git a/docs/modules/install/pages/ruby-packaging.adoc b/docs/modules/install/pages/ruby-packaging.adoc
index d4a88b09..52c51e25 100644
--- a/docs/modules/install/pages/ruby-packaging.adoc
+++ b/docs/modules/install/pages/ruby-packaging.adoc
@@ -1,9 +1,11 @@
 = Install Using Ruby Packaging
 
-Using Ruby packaging entails using commands provided by Ruby (`gem` and `bundle`) to install RubyGems.
+Using Ruby packaging entails making use of commands provided by Ruby (`gem` and `bundle`) to install gems.
+A gem is a packaged Ruby application or library, often retrieved from {url-rubygems}[RubyGems.org^].
+
 The benefit of using Ruby packaging to install Asciidoctor is that it's universal.
-Provided you have configured Ruby correctly, Ruby packaging works the same way across Ruby runtimes and operating systems.
-This page explains how to use Ruby packaging to install Asciidoctor.
+Provided you have configured Ruby correctly, Ruby packaging works the same way across all Ruby runtimes and operating systems.
+This page explains how to use Ruby packaging to install Asciidoctor from the *asciidoctor* gem.
 
 WARNING: Unless you're running in a container (Docker, podman, OCI), _never_ install gems using `gem install` as the root user.
 Doing so will almost certainly interfere with, and possibly corrupt, the Ruby installation on your system.
diff --git a/docs/modules/stem/pages/mathematical.adoc b/docs/modules/stem/pages/mathematical.adoc
index c8087fc6..9acd241a 100644
--- a/docs/modules/stem/pages/mathematical.adoc
+++ b/docs/modules/stem/pages/mathematical.adoc
@@ -39,7 +39,7 @@ Nonetheless, if you need it and you're up for the challenge, that's where we're
 
 == Install
 
-Asciidoctor Mathematical is distributed as a RubyGem named https://rubygems.org/gems/asciidoctor-mathematical[asciidoctor-mathematical^].
+Asciidoctor Mathematical is distributed as a gem named https://rubygems.org/gems/asciidoctor-mathematical[asciidoctor-mathematical^].
 You can install it using the Ruby packaging tools (gem or bundle).
 
  $ gem install asciidoctor-mathematical
diff --git a/docs/modules/syntax-highlighting/pages/coderay.adoc b/docs/modules/syntax-highlighting/pages/coderay.adoc
index ebe1a81c..f59b492f 100644
--- a/docs/modules/syntax-highlighting/pages/coderay.adoc
+++ b/docs/modules/syntax-highlighting/pages/coderay.adoc
@@ -41,7 +41,7 @@
 
 == Install CodeRay
 
-To use CodeRay with Asciidoctor, you need the {url-coderay-gem}[coderay RubyGem^].
+To use CodeRay with Asciidoctor, you need the {url-coderay-gem}[coderay gem^].
 You can use one of the following methods to install CodeRay.
 
 Install using gem (all systems)::
@@ -58,7 +58,7 @@ Install using dnf (Fedora-based systems)::
 
 == Activate CodeRay
 
-Once you've installed the RubyGem, assign the `coderay` value to the `source-highlighter` attribute in the document header to activate it.
+Once you've installed the gem, assign the `coderay` value to the `source-highlighter` attribute in the document header to activate it.
 
 [source,asciidoc]
 ----
diff --git a/docs/modules/syntax-highlighting/pages/index.adoc b/docs/modules/syntax-highlighting/pages/index.adoc
index d27fd66f..87e81c80 100644
--- a/docs/modules/syntax-highlighting/pages/index.adoc
+++ b/docs/modules/syntax-highlighting/pages/index.adoc
@@ -55,7 +55,7 @@ You should try each syntax highlighter and find the one that works best for you.
 
 [%autowidth]
 |===
-|Type |Syntax Highlighter |Required RubyGem |Compatible Converters
+|Type |Syntax Highlighter |Required Gem |Compatible Converters
 
 h|Client-side
 
diff --git a/docs/modules/syntax-highlighting/pages/rouge.adoc b/docs/modules/syntax-highlighting/pages/rouge.adoc
index a9123f0a..3ddf4dab 100644
--- a/docs/modules/syntax-highlighting/pages/rouge.adoc
+++ b/docs/modules/syntax-highlighting/pages/rouge.adoc
@@ -7,7 +7,7 @@
 
 == Install Rouge
 
-To use Rouge with Asciidoctor, you need the {url-rouge-gem}[rouge RubyGem^].
+To use Rouge with Asciidoctor, you need the {url-rouge-gem}[rouge gem^].
 You can use one of the following methods to install Rouge.
 
 Install using `gem` (all systems)::
@@ -28,7 +28,7 @@ Install using `pacman` (Arch Linux-based systems)::
 
 == Assign rouge to source-highlighter
 
-Once you've installed the RubyGem, assign the `rouge` value to the `source-highlighter` attribute in the document header to activate it.
+Once you've installed the gem, assign the `rouge` value to the `source-highlighter` attribute in the document header to activate it.
 
 [source,asciidoc]
 ----