use tables to show installation options for gems; revise installation instructions

3 files changed, 85 insertions, 34 deletions

diff --git a/docs/modules/ROOT/pages/install.adoc b/docs/modules/ROOT/pages/install.adoc
index d42507bc..632131ca 100644
--- a/docs/modules/ROOT/pages/install.adoc
+++ b/docs/modules/ROOT/pages/install.adoc
@@ -38,14 +38,26 @@ Once you make this change, all your Unicode headaches will be behind you.
 
 == Install Asciidoctor PDF
 
-You can install Asciidoctor PDF using the `gem install` command.
-We'll use this command to install the Asciidoctor PDF gem named *asciidoctor-pdf* that's published on RubyGems.org.
-Pass the name of the gem to the `gem install` command as follows:
+Asciidoctor PDF (gem: *asciidoctor-pdf*, command: `asciidoctor-pdf`) is published as a RubyGem to the rubygems.org software registry.
+You install Asciidoctor PDF from that registry using the RubyGem management tools provided by Ruby (`bundle` or `gem`).
+Alternately, you can {url-project-repo}/blob/main/CONTRIBUTING-CODE.adocl[build and install Asciidoctor PDF from source^].
 
- $ gem install asciidoctor-pdf
+Refer to the table below for instructions on how to install Asciidoctor PDF.
+If you use Bundler to manage your gems in a [.path]_Gemfile_, add the entry listed in the *Bundler* column.
+Otherwise, run the command in the *gem command* column.
 
-Installing Asciidoctor PDF will install a number of other gems mentioned in these docs, including asciidoctor, prawn, prawn-svg, prawn-table, prawn-icon, and ttfunk.
-For the most part, the versions of these dependencies are locked to the version of Asciidoctor PDF.
+[%autowidth,cols=1h;1h;1l;1l]
+|===
+|Library |gem name |Bundler |gem command
+
+|Asciidoctor PDF
+|asciidoctor-pdf
+|gem 'asciidoctor-pdf'
+|gem install asciidoctor-pdf
+|===
+
+Installing Asciidoctor PDF will automatically install a number of additional gems mentioned in these docs, including asciidoctor, prawn, prawn-svg, prawn-table, prawn-icon, and ttfunk.
+The versions of these required dependencies are locked to the version of Asciidoctor PDF.
 
 [#prerelease]
 === Install a prerelease or development version
@@ -128,7 +140,7 @@ The name of the dependency and its gem name are listed along with the minimum su
 .Minimum supported version of optional dependencies
 [#table-minimum-version,cols=3;3;4]
 |===
-| Name / Gem | Minimum Version | Feature(s)
+| Library / gem name | Minimum Version | Feature(s)
 
 | *Asciidoctor Mathematical* +
 _asciidoctor-mathematical_
@@ -150,6 +162,11 @@ _pygments.rb_
 | 2.0.0
 | Syntax highlighting
 
+| *CodeRay* +
+_coderay_
+| 1.1.0
+| Syntax highlighting
+
 | *Prawn Gmagick* +
 _prawn-gmagick_
 | 0.0.9
diff --git a/docs/modules/ROOT/pages/optimize-pdf.adoc b/docs/modules/ROOT/pages/optimize-pdf.adoc
index ed3f96e9..74cfcfa2 100644
--- a/docs/modules/ROOT/pages/optimize-pdf.adoc
+++ b/docs/modules/ROOT/pages/optimize-pdf.adoc
@@ -20,16 +20,27 @@ You can enable this feature by setting the `compress` attribute on the document:
 For a more thorough optimization, you can use the <<rghost,integrated optimizer>> or <<hexapdf>>.
 
 [#rghost]
-== rghost
+== RGhost
 
-Asciidoctor PDF also provides a flag (and bin script) that uses Ghostscript (via rghost) to optimize and compress the generated PDF with minimal impact on its quality.
-You must have Ghostscript (command: `gs`) and the `rghost` gem installed to use it.
+Asciidoctor PDF also provides a flag (and bin script) that uses Ghostscript (via Ruby Ghostscript aka RGhost) to optimize and compress the generated PDF with minimal impact on its quality.
+You must have Ghostscript (command: `gs`) and RGhost (gem: *rghost*) installed to use it.
 
-=== Install rghost
+=== Install RGhost
 
-To install the rghost gem, open a terminal and type the following command.
+First, install the rghost gem.
+Refer to the table below for instructions on how to install RGhost.
+If you use Bundler to manage your gems in a [.path]_Gemfile_, add the entry listed in the *Bundler* column.
+Otherwise, run the command in the *gem command* column.
 
- $ gem install rghost
+[%autowidth,cols=1h;1h;1l;1l]
+|===
+|Library |gem name |Bundler |gem command
+
+|RGhost
+|rghost
+|gem 'rghost'
+|gem install rghost
+|===
 
 === Convert and optimize
 
@@ -88,20 +99,31 @@ IMPORTANT: The `asciidoctor-pdf-optimize` is not guaranteed to reduce the size o
 It may actually make the PDF larger.
 You should probably only consider using it if the file size of the original PDF is several megabytes.
 
-If you have difficulty getting the `rghost` gem installed, or you aren't getting the results you expect, you can try the optimizer provided by hexapdf instead.
+If you have difficulty getting the *rghost* gem installed, or you aren't getting the results you expect, you can try the optimizer provided by HexaPDF instead.
 
 [#hexapdf]
-== hexapdf
+== HexaPDF
 
-Another option to optimize the PDF is {url-hexapdf}[hexapdf^] (gem: hexapdf, command: hexapdf).
-Before introducing it, though, it's important to point out that its license is AGPL.
+Another option to optimize the PDF is {url-hexapdf}[HexaPDF^] (gem: *hexapdf*, command: `hexapdf`).
+Before introducing it into your stack, it's important to emphasize that its license is AGPL.
 If that's okay with you, read on to learn how to use it.
 
-=== Install hexapdf
+=== Install HexaPDF
+
+First, install the hexapdf gem.
+Refer to the table below for instructions on how to install HexaPDF.
+If you use Bundler to manage your gems in a [.path]_Gemfile_, add the entry listed in the *Bundler* column.
+Otherwise, run the command in the *gem command* column.
 
-First, install the hexapdf gem using the following command:
+[%autowidth,cols=1h;1h;1l;1l]
+|===
+|Library |gem name |Bundler |gem command
 
- $ gem install hexapdf
+|HexaPDF
+|hexapdf
+|gem 'hexapdf'
+|gem install hexapdf
+|===
 
 === Compress a PDF
 
diff --git a/docs/modules/ROOT/pages/syntax-highlighting.adoc b/docs/modules/ROOT/pages/syntax-highlighting.adoc
index 568f468c..b6542a1d 100644
--- a/docs/modules/ROOT/pages/syntax-highlighting.adoc
+++ b/docs/modules/ROOT/pages/syntax-highlighting.adoc
@@ -3,24 +3,36 @@
 [#install]
 == Install a syntax highlighter
 
-To add source highlighting to source blocks, you must have a suitable syntax highlighter installed.
+To add source highlighting to source blocks, you must have a suitable syntax highlighter available.
 Asciidoctor PDF performs source highlighting during conversion, which means you must use a build-time syntax highlighter.
 
 The build-time syntax highlighters that Asciidoctor PDF supports out of the box are Rouge, Pygments, and CodeRay.
 Rouge is the preferred syntax highlighter.
-
-To install Rouge, Pygments, or CodeRay, run the corresponding gem command shown below.
-
-.Rouge
- $ gem install rouge
-
-.Pygments
- $ gem install pygments.rb
-
-.CodeRay
- $ gem install coderay
-
-Alternately, you can declare the gem in your [.path]_Gemfile_ to manage it using Bundler.
+The use of CodeRay is no longer recommended.
+
+Refer to the table below for instructions on how to install one of these build-time syntax highlighters.
+If you use Bundler to manage your gems in a [.path]_Gemfile_, add the entry listed in the *Bundler* column.
+Otherwise, run the command in the *gem command* column.
+
+[%autowidth,cols=1h;1h;1l;1l]
+|===
+|Library |gem name |Bundler |gem command
+
+|Rouge
+|rouge
+|gem 'rouge'
+|gem install rouge
+
+|Pygments
+|pygments.rb
+|gem 'pygments.rb'
+|gem install pygments.rb
+
+|CodeRay
+|coderay
+|gem 'coderay'
+|gem install coderay
+|===
 
 [#activate]
 == Activate syntax highlighting