resolves #4154 document how to uninstall the Asciidoctor gem (PR #4187)

4 files changed, 65 insertions, 2 deletions

diff --git a/docs/modules/install/pages/index.adoc b/docs/modules/install/pages/index.adoc
index 68d9deda..62ac67a9 100644
--- a/docs/modules/install/pages/index.adoc
+++ b/docs/modules/install/pages/index.adoc
@@ -21,4 +21,4 @@ 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 Asciidoctor as you use to install it.
+You should use the same method to update and uninstall Asciidoctor as you use to install it.
diff --git a/docs/modules/install/pages/linux-packaging.adoc b/docs/modules/install/pages/linux-packaging.adoc
index 1033a622..472a2033 100644
--- a/docs/modules/install/pages/linux-packaging.adoc
+++ b/docs/modules/install/pages/linux-packaging.adoc
@@ -59,7 +59,7 @@ To install the gem on Arch-based distributions, open a terminal and type:
 include::partial$success.adoc[]
 
 [#upgrade]
-== Upgrading on Linux
+== Upgrade on Linux
 
 Some Linux distributions may not have the latest stable version of Asciidoctor packaged immediately after a release of a new gem.
 If you need to upgrade to the latest version immediately, use xref:ruby-packaging.adoc[gem install] instead of the package manager.
@@ -87,3 +87,30 @@ On Fedora and other RPM-based distributions, you can update the package using:
 On Alpine Linux, update the Asciidoctor package using:
 
  $ sudo apk add -u asciidoctor
+
+[#uninstall]
+== Uninstall on Linux
+
+To uninstall (i.e., remove) Asciidoctor using Linux packaging, you request your package manager to remove the Asciidoctor package.
+The package manager will take care of removing all the necessary application files.
+
+[#uninstall-apt]
+=== APT
+
+On Debian and Debian-based distributions, uninstall the Asciidoctor package using:
+
+ $ sudo apt-get remove -y asciidoctor
+
+[#uninstall-dnf]
+=== DNF
+
+On Fedora and other RPM-based distributions, you can uninstall the package using:
+
+ $ sudo dnf remove -y asciidoctor
+
+[#uninstall-apk]
+=== apk (Alpine Linux)
+
+On Alpine Linux, uninstall the Asciidoctor package using:
+
+ $ sudo apk del asciidoctor
diff --git a/docs/modules/install/pages/macos.adoc b/docs/modules/install/pages/macos.adoc
index 732e369c..0fd2c8f7 100644
--- a/docs/modules/install/pages/macos.adoc
+++ b/docs/modules/install/pages/macos.adoc
@@ -27,6 +27,12 @@ To upgrade the gem, open a terminal and type:
  $ brew update
  $ brew upgrade asciidoctor
 
+=== Uninstall
+
+To uninstall the gem, open a terminal and type:
+
+ $ brew uninstall asciidoctor
+
 == MacPorts
 
 You can also use {url-macports}[MacPorts^], another package manager for macOS, to install Asciidoctor.
@@ -45,3 +51,9 @@ To upgrade the gem, open a terminal and type:
 
  $ sudo port selfupdate
  $ sudo port upgrade asciidoctor
+
+=== Uninstall
+
+To uninstall the gem, open a terminal and type:
+
+ $ sudo port uninstall asciidoctor
diff --git a/docs/modules/install/pages/ruby-packaging.adoc b/docs/modules/install/pages/ruby-packaging.adoc
index cfe63ea1..1426ef5c 100644
--- a/docs/modules/install/pages/ruby-packaging.adoc
+++ b/docs/modules/install/pages/ruby-packaging.adoc
@@ -69,3 +69,27 @@ To remove the older version, use the following `gem` command:
 
  $ gem cleanup asciidoctor
 ====
+
+[#gem-uninstall]
+== Uninstall using gem uninstall
+
+You can uninstall Asciidoctor using the gem `uninstall` command:
+
+ $ gem uninstall -x asciidoctor
+
+The `-x` option silences the confirmation to remove the `asciidoctor` executable, instead removing it automatically.
+In other words, it enables a complete uninstall.
+
+If you have multiple versions of Asciidoctor installed, you will be prompted to specify which version you want to uninstall.
+
+[.output]
+....
+Select gem to uninstall:
+ 1. asciidoctor-2.0.15
+ 2. asciidoctor-2.0.16
+ 3. All versions
+>
+....
+
+You can uninstall a specific version, or all versions.
+Type one of the numbers at the prompt (`>`) and press kbd:[Enter].