follow up to #1687 add asciidoctor/pdf/nopngmagick script to unregister Gmagick handler for PNG images only

1 files changed, 19 insertions, 14 deletions

diff --git a/README.adoc b/README.adoc
index a56c6566..5d491317 100644
--- a/README.adoc
+++ b/README.adoc
@@ -713,36 +713,41 @@ If you're using fonts in your SVG, and you want those fonts to be preserved, tho
 
 == Supporting Additional Image File Formats
 
-In order to embed an image into a PDF, Asciidoctor PDF must understand how to read it.
+In order to embed an image into a PDF, Asciidoctor PDF must understand how to decode it.
 To perform this work, Asciidoctor delegates to the underlying libraries.
-{url-prawn}[Prawn] provides support for reading JPG and PNG images.
-{url-prawn-svg}[prawn-svg] brings support for SVG images.
-Without any additional libraries, those are the only supported image file formats.
+{url-prawn}[Prawn] provides support for decoding JPG and PNG images.
+{url-prawn-svg}[prawn-svg] brings support for translating SVG images to PDF commands.
+Without any additional libraries, those are the only image file formats supported by Asciidoctor PDF.
 
-If you need support for additional image formats, such as GIF, TIFF, or interlaced PNG--and you don't want to convert those images to a supported format--you must install the {url-prawn-gmagick}[prawn-gmagick] (>= 0.0.9) Ruby gem.
-prawn-gmagick is an extension for Prawn based on {url-graphicsmagick}[GraphicsMagick] that adds support for all the image formats recognized by that library.
+If you need support for additional image formats, such as GIF, TIFF, WebP, or interlaced PNG--and you don't want to convert those images to a supported format like JPG--you must install the {url-prawn-gmagick}[prawn-gmagick] (>= 0.0.9) Ruby gem.
+prawn-gmagick is an extension for Prawn that delegates image decoding to {url-graphicsmagick}[GraphicsMagick] to add support for all image formats recognized by that library.
 
-prawn-gmagick has the additional benefit of *significantly* reducing the processing time, power, and memory necessary to generate a PDF that contains a lot of images, PNGs in particular.
-For large books, you might see the conversion time drop by as much as half.
+prawn-gmagick has the additional benefit of *significantly* reducing the processing time, power, and memory necessary to generate a PDF that contains a lot of PNG images.
+For large books (such as Pro Git), you might see the conversion time drop by as much as half.
 Decoding PNG images requires a lot of mathematical computation, a task Ruby is not particularly efficient at performing.
 That's why adding the prawn-gmagick gem to the converter makes such a substantial difference.
 
+As an alternative to using prawn-gmagick, you could optimize the images you pass into Asciidoctor PDF, either by scaling them down or converting them to an uncompressed format like JPG.
+
 The prawn-gmagick gem uses native extensions to compile against GraphicsMagick.
-This system prerequisite limits installation to Linux and OSX.
+This system prerequisite limits installation to C Ruby running on Linux and macOS.
 Please refer to the {url-prawn-gmagick}[README for prawn-gmagick] to learn how to install it.
 
  $ gem install prawn-gmagick
 
-Once this gem is installed, Asciidoctor automatically loads it, then delegates to it to handle all image embedding.
-In addition to support for additional image file formats, this gem also speeds up image processing considerably.
-We highly recommend using this gem if you're able to install it.
+When this gem is installed, Asciidoctor automatically detects and loads it, then delegates all image decoding to GraphicsMagick by way of the bridge it provides.
+We highly recommend using this gem with Asciidoctor PDF if you're able to install it.
 
 The one downside of delegating to GraphicsMagick is that it can mangle certain PNG images.
-If this happens, you can temporary tell Asciidoctor PDF not to use it by passing `asciidoctor/pdf/nogmagick` when calling Asciidoctor PDF.
+If this happens, you can instruct Asciidoctor PDF to not delegate to GraphicsMagick to load PNG images by requiring `asciidoctor/pdf/nopngmagick` when calling Asciidoctor PDF, as follows:
+
+ $ asciidoctor-pdf -r asciidoctor/pdf/nopngmagick doc.adoc
+
+You can also tell Asciidoctor PDF not to use prawn-gmagick at all by requiring `asciidoctor/pdf/nogmagick` when calling Asciidoctor PDF, as follows:
 
  $ asciidoctor-pdf -r asciidoctor/pdf/nogmagick doc.adoc
 
-Unfortunately, this means you no longer get support for additional image formats that Prawn cannot handle.
+Granted, bypassing prawn-gmagick means you no longer get support for additional image formats that Prawn cannot handle or the PNG acceleration.
 
 == Importing PDF Pages