asciidoctor-pdf 1.5.2 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e90846d73d8139ce9e156f4010b8cd4220d9aa318897ec94dcac52ca2b027c61
-  data.tar.gz: b519c77487cb7c7b317244342dcb06b40241d511016f6289e3a31b8305798225
+  metadata.gz: 38535fd62633525b00cea5277158ac23dbbd1bf515ee577ff867d7a498149b19
+  data.tar.gz: 24b2f3f50bb62f71416ce783fdd173e7574680ca445e4cd724f265086b2e8978
 SHA512:
-  metadata.gz: 836351139245d4460ea72c91889276e86484b1f587681ada048ccfa8d0716b7bfb595f28de0862e24556faec53a1b412a5d5f65cf2236b7579523dfd785dd1a6
-  data.tar.gz: ae3ca4fbc60ab2f8b0eefab691c8c08dfc2e39f20a2950516a8f2c4d6f9a09420f3b702b063d160592d389d390834148ef14ad173b4b31a8432995b926c27b14
+  metadata.gz: cb5e3a7117b597b3cc2f31ee013adbbf2415d6fa36893b5375e6a2aabffcdff456c72ecce0800a1cff43a637259c1c94321338fc626bb936c38841ce87909015
+  data.tar.gz: 7a18ab5e3d91cd6c9e1a99d2bd6885beaf329a249144e82a37fbfecbd784aae3758760c9695a82ef44304c951892d76113aad6737c11f720f888a552f00e18ab

data/CHANGELOG.adoc

@@ -3,7 +3,74 @@
 :uri-repo: https://github.com/asciidoctor/asciidoctor-pdf
 
 This document provides a high-level view of the changes to the {project-name} by release.
-For a detailed view of what has changed, refer to the {uri-repo}/commits/master[commit history] on GitHub.
+For a detailed view of what has changed, refer to the {uri-repo}/commits/v1.6.x[commit history] on GitHub.
+
+== 1.6.1 (2021-09-04) - @mojavelinux
+
+Enhancements::
+
+* align footnotes block to the bottom of the page it is placed on (#1833)
+
+Bug Fixes::
+
+* patch Prawn to preserve leading null character when running on Ruby 3; preserves inline anchors when text is split by page (#1963)
+
+== 1.6.0 (2021-05-10) - @mojavelinux
+
+Enhancements::
+
+* allow path of ghostscript command to be controlled using `GS` env var (#1791)
+
+Bug Fixes::
+
+* do not hyphenate a hyphen when hyphenation is enabled (#1562)
+
+Compliance::
+
+* add support for Ruby 3 and drop support for Ruby < 2.5 and JRuby < 9.2 (#1681)
+* upgrade to Prawn 2.4.0 (adds support for Ruby 3)
+* upgrade to prawn-svg 0.32 (adds support for Ruby 3 without a patch and for loading embedded images from a data URI)
+* upgrade to prawn-icon 3.0.x
+* release lock on ttfunk version (1.6 produces slightly different output from 1.5 for certain missing glyphs)
+* drop support for Asciidoctor < 2 (#1552)
+
+Build / Infrastructure::
+
+* run tests against pygments.rb 2.x in addition to pygments.rb 1.2.0
+
+== 1.5.4 (2021-01-09) - @mojavelinux
+
+Bug Fixes::
+
+* restore compatibility with Asciidoctor 2.0.12 when using Pygments (#1846)
+* fix numeric assertions in test suite (#1542)
+* keep caption with image when image is scaled down to fit page (#1803)
+* prevent inline image from rendering multiple times if fallback font is used for alt text (#1858)
+* disable cache tests if open-uri-cache gem is not available
+* disable hyphen tests if text-hyphen gem is not available
+* compensate for change in how character_spacing is applied in FontMetricCache#width_of after Prawn 2.2.2
+* allow inline image to be enclosed in link macro (alt text was breaking parsing)
+* use oembed API over HTTPS to get thumbnail for Vimeo video
+* use conum font family defined in theme for conum in verbatim block (#1611)
+* patch float precision constant so prawn-table does not fail to arrange cells that span columns (#1835)
+* resolve images in theme correctly when theme is loaded from classloader (JRuby only) (#1829)
+
+Compliance::
+
+* upgrade to prawn-svg 0.31 (adds support for loading embedded images from a data URI) (#1810)
+
+Build / Infrastructure::
+
+* migrate Linux CI jobs to GitHub Actions
+
+== 1.5.3 (2020-02-28) - @mojavelinux
+
+Bug Fixes::
+
+* do not hyphen a hyphen when hyphenation is enabled (#1562)
+* fix crash when applying text transform to heading cell in table body (#1575)
+* honor font style when looking for glyph in font
+* only suggest installing prawn-gmagick gem if not loaded (#1578)
 
 == 1.5.2 (2020-02-21) - @mojavelinux
 

data/{LICENSE.adoc → LICENSE}

@@ -1,6 +1,6 @@
-.The MIT License
-....
-Copyright (C) 2014-2020 OpenDevise Inc. and the Asciidoctor Project
+MIT License
+
+Copyright (C) 2014-present OpenDevise Inc. and the Asciidoctor Project
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,4 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
-....

data/NOTICE.adoc

@@ -1,7 +1,7 @@
 = Asciidoctor PDF
 OpenDevise Inc.; Asciidoctor Project
 
-Copyright (C) 2014-2020 OpenDevise Inc. and the Asciidoctor Project.
+Copyright (C) 2014-present OpenDevise Inc. and the Asciidoctor Project.
 
 Please visit the Asciidoctor project site for more information:
 
@@ -54,11 +54,9 @@ RomanNumeral class::
 
   - https://github.com/AndrewVos/roman-numerals
 
-PrawnCodeRayEncoder class::
-  The PrawnCodeRayEncoder class, which is used for syntax highlighting source code for use with Prawn, is borrowed from the Prawn project and modified for the purpose of this application.
-  The PrawnEncoder was written by Felipe Doria and is licensed under the GPLv3 license.
-
-  http://www.gnu.org/licenses/gpl-3.0.html 
+Asciidoctor::Prawn::CodeRayEncoder class::
+  The Asciidoctor::Prawn::CodeRayEncoder class, which is used for syntax highlighting source code for use with Prawn, is borrowed from the Prawn project and modified for the purpose of this application.
+  The PrawnEncoder was written by Felipe Doria and may be used under Matz's original licensing terms for Ruby, the GPLv2 license, or the GPLv3 license.
 
   - https://github.com/prawnpdf/prawn
 

data/README.adoc

@@ -1,6 +1,6 @@
 = Asciidoctor PDF: A native PDF converter for AsciiDoc
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
-v1.5.2, 2020-02-21
+v1.6.1, 2021-09-04
 // Settings:
 :experimental:
 :idprefix:
@@ -23,7 +23,8 @@ endif::[]
 :project-name: Asciidoctor PDF
 :project-handle: asciidoctor-pdf
 // Variables:
-:release-version: 1.5.2
+:release-line: 1.6.x
+:release-version: 1.6.1
 // URIs:
 :url-asciidoctor: http://asciidoctor.org
 :url-gem: http://rubygems.org/gems/asciidoctor-pdf
@@ -39,10 +40,9 @@ endif::[]
 :url-graphicsmagick: http://www.graphicsmagick.org
 
 ifdef::status[]
-image:https://img.shields.io/travis/asciidoctor/asciidoctor-pdf/master.svg[Build Status (Travis CI),link=https://travis-ci.org/asciidoctor/asciidoctor-pdf]
-image:https://github.com/asciidoctor/asciidoctor-pdf/workflows/CI/badge.svg[Build Status (GitHub Actions),link=https://github.com/asciidoctor/asciidoctor-pdf/actions?query=workflow%3ACI]
+image:https://img.shields.io/badge/zulip-join_chat-brightgreen.svg[project chat,link=https://asciidoctor.zulipchat.com/]
+image:{url-project-repo}/workflows/CI/badge.svg?branch=v{release-line}[Build Status (GitHub Actions),link={url-project-repo}/actions?query=workflow%3ACI+branch%3Av{release-line}]
 image:https://img.shields.io/gem/v/asciidoctor-pdf.svg[Latest Release, link={url-gem}]
-image:https://img.shields.io/badge/license-MIT-blue.svg[MIT License, link=#copyright]
 endif::[]
 
 Asciidoctor PDF is a native PDF converter for AsciiDoc.
@@ -50,6 +50,12 @@ It bypasses the requirement to generate an intermediary format such as DocBook,
 Instead, you can use this extension to convert your documents directly from AsciiDoc to PDF.
 Its aim is to take the pain out of creating PDF documents from AsciiDoc.
 
+NOTE: You're viewing the documentation for the {release-line} release line.
+If you're looking for the documentation for another release line, please refer to one of the following branches: +
+{url-project-repo}/tree/main#readme[2.0.x]
+&hybull;
+{url-project-repo}/tree/v1.5.x#readme[1.5.x]
+
 toc::[]
 
 == Overview
@@ -71,7 +77,7 @@ But don't miss the <<Highlights>> to get a preview of what's possible.
 
 * Direct AsciiDoc to PDF conversion
 * <<docs/theming-guide.adoc#,Configuration-driven theme (style and layout)>>
-* Custom (TTF) fonts
+* Custom fonts (TTF or OTF)
 * Full SVG support (thanks to https://github.com/mogest/prawn-svg[prawn-svg])
 * PDF document outline (i.e., bookmarks)
 * Title page
@@ -98,7 +104,7 @@ But don't miss the <<Highlights>> to get a preview of what's possible.
 == Known Limitations
 
 * Footnotes are always rendered as endnotes (at end of chapter for books; at end of document for all other doctypes)
-* Table cells that exceed height of a single page will be truncated (see https://github.com/prawnpdf/prawn-table/issues/41[prawn-table#41])
+* Table cells that exceed the height of a single page will be truncated (see https://github.com/prawnpdf/prawn-table/issues/41[prawn-table#41])
 * Inline images in table cells must fit within available space or Prawn::Errors::CannotFit error will be thrown
 * Columns cannot be assigned a 0% width (or a width less than the width of a single character); in the same vein, a column cannot be set to autowidth if width of all other columns meets or exceeds 100%; the result is that the converter with throw a Prawn::Errors::CannotFit error
 * An inline image in a table cell will not force the column wider if the width of the image exceeds the width of the column; either reduce the image width using `pdfwidth` or increase the width of the column using `cols`; another solution is to convert the cell to an AsciiDoc table cell (see https://github.com/asciidoctor/asciidoctor-pdf/issues/830)
@@ -113,15 +119,29 @@ But don't miss the <<Highlights>> to get a preview of what's possible.
 
 == Prerequisites
 
-All that's needed is Ruby 2.3 or better and a few Ruby gems (including at least Asciidoctor 1.5.3), which we explain how to install in the next section.
+All that's needed is Ruby (Ruby 2.5 or better) and a few Ruby gems (including at least Asciidoctor 2.0.0), which we explain how to install in the next section.
 
 To check if you have Ruby available, use the `ruby` command to query the version installed:
 
  $ ruby --version
 
-Make sure this command reports a Ruby version that's at least 2.3.
+Make sure this command reports a Ruby version that's at least 2.5.
 If so, you may proceed.
 
+If you want to <<Enable Stream Compression,optimize the pdf>> using rghost or hexapdf, you'll need to install the rghost gem:
+
+ $ gem install rghost
+
+or the hexapdf gem:
+
+ $ gem install hexapdf
+
+Similarly, if you want to use the hyphen option you will need to install the `text-hyphen` gem:
+
+ $ gem install text-hyphen
+
+You'll also need to <<Install a Syntax Highlighter (optional),install a syntax highlighter>> to use source highlighting.
+
 === System Encoding
 
 Asciidoctor assumes you're using UTF-8 encoding.
@@ -164,7 +184,7 @@ All files are managed in user space (aka your home or user directory).
 If something gets messed up, you can simply remove the [.path]_$HOME/.rvm_ folder and start over.
 
 To learn how to install RVM, follow the https://asciidoctor.org/docs/install-asciidoctor-macos/#rvm-procedure-recommended[RVM installation procedure] covered in the Asciidoctor documentation.
-Once you have installed RVM and used it to install Ruby, make sure to activate the Ruby managed by RVM using `rvm use default` or a specific Ruby version like `rvm use 2.6`.
+Once you have installed RVM and used it to install Ruby, make sure to activate the Ruby managed by RVM using `rvm use default` or a specific Ruby version like `rvm use 2.7`.
 (You'll need to do this each time you open a new terminal).
 
 After installing the gem, you can see where it was installed using the following command:
@@ -202,12 +222,12 @@ You then activate syntax highlighting for a given document by adding the `source
 ==== Upgrade Prawn and Extensions (optional)
 
 {project-name} uses Prawn to handle the PDF generation, which has a different release cycle.
-At times, there may are development features in Prawn and its extensions you need to use which haven't yet been released.
+At times, there may be development features in Prawn and its extensions you need to use which haven't yet been released.
 No problem.
 You can still gain access to these features by installing the unreleased gems directly from GitHub.
 
 To get started, first create a [.path]_Gemfile_ in the root of your project.
-In that file, declare the gem soruce, the {project-handle} gem, and the prawn gem and/or one of its extension gems.
+In that file, declare the gem source, the {project-handle} gem, and the prawn gem and/or one of its extension gems.
 In this example, we'll install both the prawn and prawn-table gems from GitHub.
 
 .Gemfile
@@ -262,7 +282,7 @@ It's time to convert the AsciiDoc document directly to PDF.
 
 IMPORTANT: You'll need the `rouge` gem installed to run this example since it uses the `source-highlighter` attribute with the value of `rouge`.
 
-Converting to PDF is a simple as running the `asciidoctor-pdf` script using Ruby and passing our AsciiDoc document as the first argument.
+Converting to PDF is as simple as running the `asciidoctor-pdf` script using Ruby and passing our AsciiDoc document as the first argument.
 
  $ asciidoctor-pdf basic-example.adoc
 
@@ -288,7 +308,7 @@ The pain of the DocBook toolchain should be melting away about now.
 == Themes
 
 The layout and styling of the PDF is driven by a YAML configuration file.
-To learn how the theming system works and how to create and apply custom themes, refer to the <<docs/theming-guide.adoc#,Asciidoctor PDF Theme Guide>>.
+To learn how the theming system works and how to create and apply custom themes, refer to the <<docs/theming-guide.adoc#,Asciidoctor PDF Theming Guide>>.
 You can use the built-in theme files, which you can find in the [.path]_data/themes_ directory, as examples.
 
 If you've enabled a source highlighter, you can control the style (aka theme) it applies to source blocks using the `coderay-style`, `pygments-style`, and `rouge-style` attributes, respectively.
@@ -297,7 +317,7 @@ For example, to configure Rouge to use the built-in monokai theme, run Asciidoct
  $ asciidoctor-pdf -a rouge-style=monokai basic-example.adoc
 
 It's possible to develop your own theme for Rouge.
-Refer to the <<docs/theming-guide.adoc#,Asciidoctor PDF Theme Guide>> for details.
+Refer to the <<docs/theming-guide.adoc#,Asciidoctor PDF Theming Guide>> for details.
 
 == Support for Non-Latin Languages
 
@@ -305,7 +325,7 @@ Asciidoctor can process the full range of characters in the UTF-8 character set.
 That means you can write your document in any language, save the file with UTF-8 encoding (_that's important!_), and expect Asciidoctor to convert the text properly.
 But you still need a font that provides the glyphs for those characters.
 
-When converting a document with Asciidoctor PDF, you may notice that some of the glyphs for certain languages, such as Chinese, are missing from the PDF.
+When converting a document with Asciidoctor PDF, you may notice that some glyphs for certain languages, such as Chinese, are missing from the PDF.
 PDF is a "`bring your own font`" kind of system.
 In other words, the font you provide must provide glyphs for all the characters used.
 There's no one font that supports all the world's languages (though some, like Noto Serif, certainly come close).
@@ -468,15 +488,10 @@ Otherwise, the SVG library will fail to process it.
 
 === Asciidoctor Diagram Integration
 
-As of Asciidoctor PDF 1.5.0.alpha.17 running on Asciidoctor 2 or better, Asciidoctor PDF provides better integration with Asciidoctor Diagram by setting the `data-uri` attribute by default.
+Asciidoctor PDF provides seamless integration with Asciidoctor Diagram by setting the `data-uri` attribute by default.
 When the `data-uri` attribute is set, Asciidoctor Diagram returns the absolute path to the generated image, which Asciidoctor PDF can then locate.
 (This makes sense since technically, Asciidoctor Diagram must embed the image in the document, similar in spirit to the `data-uri` feature for HTML).
-This means the input directory and the output directory (and thus the imagesoutdir) can differ and Asciidoctor PDF will still be able to locate the generate image.
-
-Prior to Asciidoctor PDF 1.5.0.alpha.17 (or prior to Asciidoctor 2), the way to solve this problem is to set the `imagesdir` attribute to an absolute path.
-That way, it won't matter where the generated image is written.
-Asciidoctor PDF will still be able to find it.
-Keep in mind that this strategy may introduce other side effects you'll have to work around.
+This means the input directory and the output directory (and thus the imagesoutdir) can differ and Asciidoctor PDF will still be able to locate the generated image.
 
 == Image Scaling
 
@@ -541,9 +556,9 @@ The pdfwidth attribute supports the following units:
 
 In all cases, the width is converted to pt.
 
-=== Specifying a default width
+=== Specifying a Default Width
 
-If you want to scale all block images that don't have a pdfwidth or scaledwidth attribute specified, assign a value to the image_width key in your theme.
+To scale all block images that don't define either a `pdfwidth` or `scaledwidth` attribute on the image macro, assign a value to the image-width key in your theme file.
 
 [source,yaml]
 ----
@@ -551,6 +566,10 @@ image:
   width: 100%
 ----
 
+The image-width key accepts the same values as the `pdfwidth` attribute.
+Thus, you can think of it as the fallback value for the `pdfwidth` attribute.
+If specified, this value takes precedence over the `width` attribute on the image macro.
+
 === Inline Image Sizing
 
 Inline images can be sized in much the same way as block images (using the pdfwidth, scaledwidth or width attributes), with the following exceptions:
@@ -571,7 +590,7 @@ If the image height exceeds the height of the page, the image will be scaled dow
 
 In addition to the width-related attributes previously covered, cover and background images can be sized relative to the page using the `fit` attribute of the image macro.
 The `fit` attribute works similarly to the `object-fit` property in CSS.
-It's value must be specified as a single keyword, chosen from the table below.
+Its value must be specified as a single keyword, chosen from the table below.
 The starting size of the image is determined by the explicit width, if specified, or the implicit width.
 The height is always derived from the width while respecting the implicit aspect ratio of the image.
 The available space for a background image (i.e., the canvas) is the page.
@@ -889,7 +908,7 @@ Here's an example of how to skip a passthrough block when converting to PDF:
 \endif::[]
 ----
 
-Here's an example of how to only enable a passthrough block when convertering to HTML5:
+Here's an example of how to only enable a passthrough block when converting to HTML5:
 
 [source,asciidoc]
 ----
@@ -1011,7 +1030,7 @@ This value is used as the heading of the preface and as the text of the entry in
 
 Asciidoctor PDF supports generating an index catalog that itemizes all index terms defined in the document, allowing the reader to navigate the document by keyword.
 
-To get Asciidoctor PDF to generate an index, simply add an level-1 section flagged with the `index` style near the end of your document.
+To get Asciidoctor PDF to generate an index, add a level-1 section flagged with the `index` style near the end of your document.
 The converter will automatically populate the catalog with the list of index terms in the document, organized by first letter.
 
 [source,asciidoc]
@@ -1028,39 +1047,74 @@ However, you could use an extension, such as a TreeProcessor, to automatically m
 
 == Optimizing the Generated PDF
 
-By default, Asciidoctor PDF does not optimize the output document or even compress the streams.
-The simplest way to reduce the size of the file is to enable stream compression (using the FlateDecode method).
+By default, Asciidoctor PDF does not optimize the PDF it generates or compress its streams.
+This section covers several approaches you can take to optimize your PDF.
+
+=== Enable Stream Compression
+
+The simplest way to reduce the size of the PDF file is to enable stream compression (using the FlateDecode method).
 You can enable this feature by setting the `compress` attribute on the document:
 
  $ asciidoctor-pdf -a compress document.adoc
 
-For more thorough optimzation, you can use either the built-in `asciidoctor-pdf-optimize` script or hexapdf.
+For a more thorough optimization, you can use the integrated optimizer or hexapdf.
 Read on to learn how.
 
-=== asciidoctor-pdf-optimize
+=== rghost
 
-{project-name} also provides a bin script that uses GhostScript to optimize and compress the generated PDF (with minimal impact on quality).
+{project-name} also provides a flag (and bin script) that uses GhostScript (via rghost) to optimize and compress the generated PDF (with minimal impact on quality).
 You must have Ghostscript (command: `gs`) and the `rghost` gem installed to use it.
 
-Here's an example usage:
+Here's an example usage that converts your document and optimizes it:
+
+ $ asciidoctor-pdf -a optimize basic-example.adoc
+
+The command will generate an optimized PDF 1.4 file.
+In addition to optimizing the PDF file, it also converts it from plain PDF to a PDF/X-1a.
+
+If this command fails because the `gs` command cannot be found, you'll need to set it using the `GS` environment variable.
+On Windows, this step is almost always required since the Ghostscript installer does not install the `gs` command into a standard location.
+Here's an example that shows how you can override the `gs` command path:
+
+ $ GS=/path/to/gs asciidoctor-pdf -a optimize basic-example.adoc
+
+You'll need to use the technique for assigning an environment variable that's relevant for your system.
+
+The one limitation of generating a PDF/X-1a file is that it does not allow non-ASCII characters in the document metadata fields (i.e., title, author, subject, etc).
+To workaround this limitation, you can force Ghostscript to generate a PDF 1.3 file using the `pdf-version` attribute:
+
+ $ asciidoctor-pdf -a optimize -a pdf-version=1.3 basic-example.adoc
+
+CAUTION: Downgrading the PDF version may break the PDF if it contains an image that uses color blending or transparency.
+Specifically, the text on the page can become rasterized, which causes links to stop working and prevents text from being selected.
+If you're in this situation, it might be best to try <<hexapdf>> instead.
+
+If you're looking for a smaller file size, you can try reducing the quality of the output file by passing a quality keyword to the `optimize` attribute (e.g., `--optimize=screen`).
+The `optimize` attribute accepts the following keywords: `default` (default, same if value is empty), `screen`, `ebook`, `printer`, and `prepress`.
+Refer to the https://www.ghostscript.com/doc/current/VectorDevices.htm#PSPDF_IN[Ghostscript documentation^] to learn what settings these presets affect.
+
+If you've already generated the PDF, and want to optimize it directly, you can use the bin script:
 
  $ asciidoctor-pdf-optimize basic-example.pdf
 
 The command will overwrite the PDF file with an optimized version.
+You can also try reducing the quality of the output file using the `--quality` flag (e.g., `--quality screen`).
+The `--quality` flag accepts the following keywords: `default` (default), `screen`, `ebook`, `printer`, and `prepress`.
 
-If a file is found with the extension `.pdfmark` and the same rootname as the input file, it is used to add metadata to the generated PDF document.
-This file is necessary to preserve the document metadata since Ghostscript will otherwise drop it.
-That's why {project-name} always creates this file in addition to the PDF.
+In both cases, if a file is found with the extension `.pdfmark` and the same rootname as the input file, it will be used to add metadata to the generated PDF document.
+This file is necessary when using versions of Ghostscript < 8.54, which did not automatically preserve this metadata.
+You can instruct the converter to automatically generate a pdfmark file by setting the `pdfmark` attribute (i.e., `-a pdfmark`)
+When using a more recent version of Ghostscript, you do not need to generate a `.pdfmark` file for this purpose.
 
 IMPORTANT: The `asciidoctor-pdf-optimize` is not guaranteed to reduce the size of the PDF file.
 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.
-You can also try reducing the quality of the output file using the `--quality` flag (e.g., `--quality screen`).
-The `--quality` flag accepts the following keywords: `default` (default), `screen`, `ebook`, `printer`, and `prepress`.
+
+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
 
-Another option to optimize the PDF is https://hexapdf.gettalong.org/[hexapdf] (gem: hexapdf, command: hexapdf).
+Another option to optimize the PDF is https://hexapdf.gettalong.org/[hexapdf^] (gem: hexapdf, command: hexapdf).
 Before introducing it, though, it's important to point out that its license is AGPL.
 If that's okay with you, read on to learn how to use it.
 
@@ -1070,17 +1124,56 @@ First, install the hexapdf gem using the following command:
 
 You can then use it to optimize your PDF as follows:
 
- $ hexapdf optimize --compress-pages --force basic-example.pdf basic-example-optimized.pdf
+ $ hexapdf optimize --compress-pages --force basic-example.pdf basic-example.pdf
 
 This command does not manipulate the images in any way.
 It merely compresses the objects in the PDF and prunes any unreachable references.
-But given how much waste Prawn leaves behind, this turns out to reduce the file size significantly.
+But given how much waste Prawn leaves behind, this turns out to reduce the file size substantially.
+
+You can hook this command directly into the converter by providing your own implementation of the `Optimizer` class.
+Start by creating a Ruby file named [.path]_optimizer-hexapdf.rb_, then populate it with the following code:
+
+.optimizer-hexapdf.rb
+[source,ruby]
+----
+require 'hexapdf/cli'
+
+class Asciidoctor::PDF::Optimizer
+  def initialize(*)
+    app = HexaPDF::CLI::Application.new
+    app.instance_variable_set :@force, true
+    @optimize = app.main_command.commands['optimize']
+  end
+
+  def optimize_file path
+    options = @optimize.instance_variable_get :@out_options
+    options.compress_pages = true
+    #options.object_streams = :preserve
+    #options.xref_streams = :preserve
+    #options.streams = :preserve # or :uncompress
+    @optimize.execute path, path
+    nil
+  rescue
+    # retry without page compression, which can sometimes fail
+    options.compress_pages = false
+    @optimize.execute path, path
+    nil
+  end
+end
+----
+
+To activate your custom optimizer, load this file when invoking the `asciidoctor-pdf` using the `-r` flag and set the `optimize` attribute as well using the `-a` flag.
+
+ $ asciidoctor-pdf -r ./optimizer-hexapdf.rb -a optimize basic-example.adoc
+
+Now you can convert and optimize all in one go.
 
-To see more options, run:
+To see more options that `hexapdf optimize` offers, run:
 
  $ hexapdf help optimize
 
-For example, to make the source of the PDF a bit more readable, set the stream-related options to `preserve`.
+For example, to make the source of the PDF a bit more readable (though less optimized), set the stream-related options to `preserve` (e.g.,, `--streams preserve` from the CLI or `options.streams = :preserve` from the API).
+You can also disable page compressioin (e.g., `--no-compress-pages` from the CLI or `options.compress_pages = false` from the API).
 
 hexapdf also allows you to add password protection to your PDF, if that's something you're interested in doing.
 
@@ -1101,8 +1194,8 @@ To help develop {project-name}, or to simply use the development version, refer
 
 == Copyright
 
-Copyright (C) 2014-2020 OpenDevise Inc. and the Asciidoctor Project.
+Copyright (C) 2014-present OpenDevise Inc. and the Asciidoctor Project.
 Free use of this software is granted under the terms of the MIT License.
 
-For the full text of the license, see the <<LICENSE.adoc#,LICENSE>> file.
+For the full text of the license, see the link:LICENSE[] file.
 Refer to the <<NOTICE.adoc#,NOTICE>> file for information about third-party Open Source software in use.