asciidoctor-pdf 1.6.2 → 2.0.0.alpha.1

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.6.2, 2021-12-31
+v2.0.0.alpha.1, 2022-04-20
 // Settings:
 :experimental:
 :idprefix:
@@ -23,15 +23,14 @@ endif::[]
 :project-name: Asciidoctor PDF
 :project-handle: asciidoctor-pdf
 // Variables:
-:release-line: 1.6.x
-:release-version: 1.6.2
+:release-line: 2.0.x
+:release-version: 2.0.0.alpha.1
 // URIs:
 :url-asciidoctor: http://asciidoctor.org
 :url-gem: http://rubygems.org/gems/asciidoctor-pdf
 :url-project: https://github.com/asciidoctor/asciidoctor-pdf
 :url-project-repo: {url-project}
 :url-project-issues: {url-project-repo}/issues
-:url-project-list: http://discuss.asciidoctor.org
 :url-prawn: http://prawnpdf.org
 :url-prawn-gmagick: https://github.com/packetmonkey/prawn-gmagick
 :url-prawn-svg: https://github.com/mogest/prawn-svg
@@ -41,7 +40,7 @@ endif::[]
 
 ifdef::status[]
 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:{url-project-repo}/workflows/CI/badge.svg[Build Status (GitHub Actions),link={url-project-repo}/actions?query=workflow%3ACI+branch%3Amain]
 image:https://img.shields.io/gem/v/asciidoctor-pdf.svg[Latest Release, link={url-gem}]
 endif::[]
 
@@ -50,11 +49,11 @@ 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.
+NOTE: You're viewing the documentation for the (unreleased) {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]
+-
+{url-project-repo}/tree/v1.6.x#readme[1.6.x]
 
 toc::[]
 
@@ -91,7 +90,9 @@ But don't miss the <<Highlights>> to get a preview of what's possible.
 * Page numbering
 * Double-sided (aka prepress) printing mode (i.e., margins alternate on recto and verso pages)
 * Customizable running content (header and footer)
-* “Keep together” blocks (i.e., page breaks avoided in certain block content)
+* “Keep together” blocks (i.e., page breaks avoided in certain block content):
+** Explicitly delimited blocks other than open blocks
+** Open blocks with the "unbreakable" option `[%unbreakable]`
 * Orphaned section titles avoided
 * Autofit verbatim blocks (as permitted by base_font_size_min setting)
 * Table border settings honored
@@ -103,27 +104,31 @@ 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 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)
-* Must use development version of prawn-table for autowidth to work on table head row
-* Must use development version of prawn for error to include font name when requested font style is missing
-* Must use Ruby >= 2.4 for natural cross references to work with non-ASCII titles
-* AsciiDoc table cell leaves padding below last block (due to lack of margin collapsing)
-* Prawn does not support double-wide box drawing glyphs correctly, so box drawings aren't aligned properly in verbatim blocks (see https://github.com/prawnpdf/prawn/issues/1002[prawn#1002]
-* Orphan / widow support is limited; a page break can occur between a section title and its section content, a table caption and the caption, etc.; use a manual page break to avoid
-* If a no-break hyphen is surrounded by formatted text on both sides (or is formatted individually), it will not prevent a line break
-* Images cannot float
+* Footnotes are always displayed as endnotes (at the end of chapter for books; at the end of document for all other doctypes).
+*Footnotes cannot be displayed at the bottom of the page because the PDF generator does not support content reflows* (see {url-project-issues}/85#issuecomment-577412975[#85] for reasoning).
+* 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]).
+* 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`, increase the width of the column using `cols`, or convert the cell to an AsciiDoc table cell and, preferably, use a block image (see {url-project-issues}/830).
+* Must use development version of prawn for error to include font name when requested font style is missing.
+* AsciiDoc table cell leaves padding below last block (due to lack of margin collapsing).
+* Prawn does not support double-wide box drawing glyphs correctly, so box drawings aren't aligned properly in verbatim blocks (see https://github.com/prawnpdf/prawn/issues/1002[prawn#1002]).
+* Orphan / widow support is limited; a page break can occur between a section title and its section content, a table caption and the caption, etc.; use a manual page break to avoid.
+* If a no-break hyphen is surrounded by formatted text on both sides (or is formatted individually), it will not prevent a line break.
+* Images cannot float.
+* You cannot use inline HTML (like a link or emphasized text) in a source block that also uses syntax highlighting.
+These two technologies just don't combine in the PDF generation process due to how the syntax highlighters work.
+* Verse blocks do not use a fixed-width font by default, but you can control this setting using the theme.
+* An inline image with a percentage width value in an autowidth table cell is resized relative to its intrinsic width.
+The space reserved for the image matches its intrinsic width.
+This matches the behavior of HTML.
 
 == Prerequisites
 
-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.
+All that's needed is Ruby 2.5 or better (or JRuby 9.2 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
+ $ ruby -e 'puts RUBY_VERSION'
 
 Make sure this command reports a Ruby version that's at least 2.5.
 If so, you may proceed.
@@ -167,6 +172,13 @@ Then, install the gem from RubyGems.org using the following command:
 
  $ gem install asciidoctor-pdf
 
+If you're using Ruby 3.1 or better, you must also install the matrix gem until Prawn 2.5.0 or better is released.
+
+ $ gem install matrix
+
+The matrix gem used to be bundled in the Ruby distribution, but was split out starting in Ruby 3.1.
+This requirement will be lifted once Prawn declares it as a runtime dependency.
+
 ==== Installation Troubleshooting
 
 If you get a permission error while installing the gem, such as the one below, it's likely you're attempting to install the gem directly into your system.
@@ -219,16 +231,16 @@ You then activate syntax highlighting for a given document by adding the `source
 :source-highlighter: rouge
 ----
 
-==== Upgrade Prawn and Extensions (optional)
+[#use-dev-versions]
+==== Upgrade prawn
 
-{project-name} uses Prawn to handle the PDF generation, which has a different release cycle.
-At times, there may be development features in Prawn and its extensions you need to use which haven't yet been released.
+{project-name} uses Prawn to handle the PDF generation.
+At times, there may be development features or fixes you need in Prawn or one of its extensions that's still unreleased.
 No problem.
-You can still gain access to these features by installing the unreleased gems directly from GitHub.
+You can 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 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.
+In that file, declare the gem source, the {project-handle} gem, and the prawn gem (plus any other development gems you want to use).
 
 .Gemfile
 [source,ruby]
@@ -236,8 +248,7 @@ In this example, we'll install both the prawn and prawn-table gems from GitHub.
 source 'https://rubygems.org'
 
 gem 'asciidoctor-pdf'
-gem 'prawn', github: 'prawnpdf/prawn'
-gem 'prawn-table', github: 'prawnpdf/prawn-table'
+gem 'prawn', github: 'prawnpdf/prawn', branch: 'HEAD'
 ----
 
 You can then install the gems into your project using the `bundle` command:
@@ -347,11 +358,18 @@ You can get such a theme by installing the `asciidoctor-pdf-cjk-kai_gen_gothic`
 The https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic[asciidoctor-pdf-cjk-kai_gen_gothic] project provides themes optimized for CJK languages based on the kai_gen_gothic font.
 See the https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic[asciidoctor-pdf-cjk-kai_gen_gothic] project README for detailed setup instructions.
 
+WARNING: The theme provided by the `asciidoctor-pdf-cjk-kai_gen_gothic` gem is no longer compatiable with the stable release of Asciidoctor PDF.
+However, you can still use it to create a <<Create a Custom CJK Theme,custom CJK theme>>.
+
 Once you have that gem installed (and the fonts), you need to tell Asciidoctor PDF to use one of the themes.
 If you're converting a document that is primarily written in Japanese, you'd run Asciidoctor PDF as follows:
 
  asciidoctor-pdf -r asciidoctor-pdf-cjk-kai_gen_gothic -a pdf-theme=KaiGenGothicJP document.adoc
 
+If that command fails, you may have better luck creating your own CJK theme.
+
+=== Create a Custom CJK Theme
+
 You also have to option of creating your own theme gem that uses fonts of your choice.
 For example, if you want to use the `asciidoctor-pdf-cjk-kai_gen_gothic` gem to fetch fonts, but then use them in your own theme, here's how you'd do it.
 
@@ -363,27 +381,23 @@ For example, if you want to use the `asciidoctor-pdf-cjk-kai_gen_gothic` gem to
 
  $ asciidoctor-pdf-cjk-kai_gen_gothic-install
 
-. Create a theme that extends the default theme:
+. Create a theme file named [.path]_cjk-theme.yml_ that extends the default theme to override the fonts:
 +
 [source,yml]
 ----
 extends: default
 font:
   catalog:
-    KaiGen Gothic JP:
-      normal: KaiGenGothicJP-Regular.ttf
-      bold: KaiGenGothicJP-Bold.ttf
-      italic: KaiGenGothicJP-Regular-Italic.ttf
-      bold_italic: KaiGenGothicJP-Bold-Italic.ttf
-    M+ 1mn:
-      normal: GEM_FONTS_DIR/mplus1mn-regular-subset.ttf
-      bold: GEM_FONTS_DIR/mplus1mn-bold-subset.ttf
-      italic: GEM_FONTS_DIR/mplus1mn-italic-subset.ttf
-      bold_italic: GEM_FONTS_DIR/mplus1mn-bold_italic-subset.ttf
+    merge: true
+    KaiGen Gothic CN:
+      normal: KaiGenGothicCN-Regular.ttf
+      bold: KaiGenGothicCN-Bold.ttf
+      italic: KaiGenGothicCN-Regular-Italic.ttf
+      bold_italic: KaiGenGothicCN-Bold-Italic.ttf
   fallbacks:
-  - KaiGen Gothic JP
+  - KaiGen Gothic CN
 base:
-  font-family: KaiGen Gothic JP
+  font-family: KaiGen Gothic CN
 heading:
   font-family: $base-font-family
 abstract:
@@ -396,9 +410,10 @@ sidebar:
 
 . Load your theme when running Asciidoctor PDF:
 
- $ asciidoctor-pdf -a scripts=cjk -a pdf-theme=./jp-theme.yml -a pdf-fontsdir=`ruby -r asciidoctor-pdf-cjk-kai_gen_gothic -e "print File.expand_path '../fonts', (Gem.datadir 'asciidoctor-pdf-cjk-kai_gen_gothic')"` document.adoc
+ $ asciidoctor-pdf -a scripts=cjk -a pdf-theme=./cjk-theme.yml -a pdf-fontsdir=GEM_FONTS_DIR,`ruby -r asciidoctor-pdf-cjk-kai_gen_gothic -e "print File.expand_path '../fonts', (Gem.datadir 'asciidoctor-pdf-cjk-kai_gen_gothic')"` document.adoc
 
 The `-a pdf-fontsdir` option is important to tell Asciidoctor PDF where to find your custom fonts.
+(Note that the inclusion of GEM_FONTS_DIR in the value is only required when using Asciidoctor PDF 1.5).
 
 Rather than using the installer from the `asciidoctor-pdf-cjk-kai_gen_gothic` gem, you can download fonts whatever way you choose.
 When using your own fonts, be sure to consult the <<docs/theming-guide.adoc#preparing-a-custom-font,Preparing a Custom Font>> section of the theming guide to find recommended modifications.
@@ -759,11 +774,51 @@ It should be a direct descendant of the document or a section.
 That's because what it imports are entire pages.
 If it's used inside a delimited block or table cell, the behavior is unspecified.
 
-== Crafting Interdocument Xrefs
+== Interdocument Xrefs
+
+An xref to another AsciiDoc document (i.e., an interdocument xref) will either become a link to the PDF file generated from that source document or an internal link to an anchor within the current document.
+Which one it becomes depends on whether the target has been included into the current document.
+These section describes these two scenarios.
+
+=== Referencing Another Document
+
+If the target PDF is generated from an AsciiDoc file, you can make a reference to that PDF using the xref macro.
+
+Let's assume the current document is [.path]_a.adoc_ and the PDF you want to reference is generated from [.path]_b.adoc_.
+Here's how you can make a reference from the PDF generated from [.path]_a.adoc_ to the PDF generated from [.path]_b.adoc_.
+
+[source,asciidoc]
+----
+A link to xref:b.adoc[b].
+----
+
+This xref macro is translated to a link that refers to [.path]_b.pdf_.
+
+If there's an anchor you want to target in [.path]_b.pdf_, for example _chapter-b_, you can describe it using a URL fragment just like you would with any URL.
+
+[source,asciidoc]
+----
+A link to xref:b.adoc#chapter-b[b].
+----
+
+WARNING: Linking to a named anchor isn't supported by all PDF viewers.
+Some viewers (like Firefox) only support relative links when the PDF is accessed through a web server.
+To verify it's working, test the PDF in Firefox and served through a local web server.
+
+PDF supports a variety of PDF link open parameters you can control using the URL fragment.
+For example, you can configure the PDF to open on a specific page using the special fragment `page=<N>`, where `<N>` is the 1-based page number.
+
+[source,asciidoc]
+----
+A link to page 2 of xref:b.adoc#page=2[b].
+----
+
+You can find a list of all the special fragment parameters in the https://www.adobe.com/content/dam/acom/en/devnet/acrobat/pdfs/pdf_open_parameters.pdf#G4.1500549[PDF Open Parameters^] reference.
+
+=== Converting Interdocument Xrefs to Internal Xrefs
 
-This converter produces a single PDF file, which means content from multiple source documents get colocated into the same output file.
-That means references between documents must necessarily become internal references.
-These interdocument cross references (i.e., xrefs) will only successfully make that transition if you structure your document in accordance with the rules.
+If you're using this converter to generate a single PDF file from multiple source documents (combined using the include directive), references between those included documents must become internal references.
+Interdocument cross references (i.e., xrefs) will only successfully make that transition if you structure your document in accordance with the rules.
 
 Those rules are as follows:
 
@@ -848,43 +903,48 @@ In other words, it encodes the complete information about the reference so the c
 
 Unlike the built-in HTML converter, Asciidoctor PDF does not provide native support for STEM blocks and inline macros (i.e., asciimath and latexmath).
 That's because Asciidoctor core doesn't process the STEM content itself.
-It just passes it through to the converter.
-In the HTML output, Asciidoctor relies on the JavaScript-based MathJax library to parse and render the equations in the browser when the page is loaded.
-The HTML converter simply wraps the equations in special markup so MathJax can find them.
+It simply passes it through to the converter.
+When converting to HTML, Asciidoctor relies on the JavaScript-based MathJax library to parse and render the STEM expressions in the browser when the page is loaded.
+The HTML converter wraps the expressions in special markup so MathJax can find and process them.
 
-In order to insert a rendered equation into the PDF, the toolchain has to parse the equations and convert them to a format the PDF writer (Prawn) can understand.
+In order to insert a rendered expression into the PDF, the toolchain must parse the expressions and convert them to a format the PDF writer (Prawn) can understand.
 That typically means converting to an image.
 
-The recommended solution is an extension named Asciidoctor Mathematical, which we'll cover in this document.
+One solution that provides this capability is an extension named Asciidoctor Mathematical, which we'll cover in the next section.
 
+////
 Another solution, which is still under development, uses Mathoid to convert STEM equations to images.
 Mathoid is a library that invokes MathJax using a headless browser, so it supports both asciimath and latexmath equations.
 That prototype can be found in the https://github.com/asciidoctor/asciidoctor-extensions-lab#extension-catalog[Asciidoctor extensions lab].
+////
 
 === Asciidoctor Mathematical
 
-{url-asciidoctor-mathematical}[Asciidoctor Mathematical] is an extension for Asciidoctor that provides alternate processing of STEM blocks and inline macros (currently only latexmath).
-After the document has been parsed, the extension locates all the latexmath blocks and inline macros, converts the equations to images using Mathematical, then replaces them with image nodes.
+{url-asciidoctor-mathematical}[Asciidoctor Mathematical] is an extension for Asciidoctor that provides alternate processing of STEM blocks and inline macros.
+After the document has been parsed, the extension locates each asciimath, latexmath, and stem block and inline macro, converts the expression to an image, and replaces the expression with an image.
+It uses Mathematical to render the LaTeX notation as an image.
+If the expression is AsciiMath, it first uses AsciiMath gem to convert to LaTeX.
 Conversion then proceeds as normal.
 
 Asciidoctor Mathematical is a Ruby gem that uses native extensions.
-It has a few system prerequisites which limit installation to Linux and OSX.
+It has a few system prerequisites which limit installation to Linux and macOS.
 Please refer to the {url-asciidoctor-mathematical}#installation[installation section] in the Asciidoctor Mathematical README to learn how to install it.
 
-Once Asciidoctor Mathematical is installed, you just need to enable it when invoking Asciidoctor PDF using the `-r` flag:
+Once Asciidoctor Mathematical is installed, you can enable it when invoking Asciidoctor PDF using the `-r` flag:
 
  $ asciidoctor-pdf -r asciidoctor-mathematical sample.adoc
 
-If you're invoking Asciidoctor via the API, all you need to do is require the gem before invoking Asciidoctor:
+If you're invoking Asciidoctor via the API, you need to require the gem before invoking Asciidoctor:
 
 [source,ruby]
 ----
 require 'asciidoctor-mathematical'
+require 'asciidoctor-pdf'
 
-Asciidoctor.convert_file 'sample.adoc', safe: :safe
+Asciidoctor.convert_file 'sample.adoc', backend: 'pdf', safe: :safe
 ----
 
-To get the best quality equations, and the maximize speed of conversion, we recommend configuring Asciidoctor Mathematical to convert equations to SVG.
+To get the best quality output and maximize speed of conversion, we recommend configuring Asciidoctor Mathematical to convert equations to SVG.
 You control this setting using the `mathematical-format` AsciiDoc attribute:
 
  $ asciidoctor-pdf -r asciidoctor-mathematical -a mathematical-format=svg sample.adoc
@@ -1015,13 +1075,17 @@ When the title page is enabled, the table of contents (aka TOC) also gets is own
 
 The table of contents (TOC) is not included by default.
 The TOC is only included if the `toc` attribute is set on the document.
+The value of this attribute determines the placement.
+If a value is not specified, the placement defaults to `auto`, which is directly after the document title.
 
-The placement of the table of contents is fixed, and thus the value of the `toc` attribute is effectively ignored in this backend.
 For documents that have the book doctype, the TOC is inserted using discrete pages between the title page and the first page of content.
-For all other doctypes (unless the `title-page` attribute is set), the TOC is inserted in the flow of text in between the document title and the first block of content.
+For all other doctypes (unless the `title-page` attribute is set), the TOC is inserted in the flow of text.
+If a placement is not specifie, that location is between the document title and the first block of content.
 
 While the table of contents is not included by default, the PDF outline is always included.
 The `toclevels` attribute controls the depth of both the TOC and the PDF outline (regardless of whether the TOC is enabled).
+The depth of the outline can be controlled independently using the `outlinelevels` attribute.
+Both attributes can also be set on individual sections to override the depth for a given section and its children.
 
 NOTE: If a document that has the book doctype includes a preface, an entry for the preface is only included in the TOC if the `preface-title` is assigned a value (e.g., `preface-title=Preface`).
 This value is used as the heading of the preface and as the text of the entry in the TOC.
@@ -1030,7 +1094,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, add a 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 annotated 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]
@@ -1039,17 +1103,68 @@ The converter will automatically populate the catalog with the list of index ter
 = Index
 ----
 
-You can use any text you want for the title of the section.
+You can use any text you want for the title of this section.
 The only restriction is that no index terms may be defined below this section.
 
 NOTE: Although the catalog is generated automatically, you have to mark the index terms manually.
 However, you could use an extension, such as a TreeProcessor, to automatically mark index terms.
 
+=== How Index Terms are Grouped and Sorted
+
+By default, the converter groups index terms by the first letter of the primary term (e.g., A), which we call the category.
+These categories are displayed in alphabetically order in the index.
+Within the category, the converter sorts the terms alphabetically.
+
+The exception to this rule is if the primary term does not start with a letter.
+In this case, the converter group the term (along with its secondary and tertiary terms) in a special category named @.
+The @ category is displayed before all other categories in the index.
+
+If you want to modify this behavior, you must extend the index catalog and apply your own grouping and sorting rules.
+
+For example, let's say that all your functions begin with the prefix `fn`, but you want to group and sort them by the function name that follows.
+Here's rudimentary code you can use to do that:
+
+.index-customizer.rb
+[source,ruby]
+----
+require 'asciidoctor-pdf'
+
+module Asciidoctor::PDF
+  IndexCatalog.prepend (::Module.new do
+    def store_primary_term name, dest = nil
+      store_dest dest if dest
+      category = (name.delete_prefix 'fn').upcase.chr
+      (init_category category).store_term name, dest
+    end
+  end)
+
+  IndexTermGroup.prepend (::Module.new do
+    def <=> other
+      this = @name.delete_prefix 'fn'
+      that = other.name.delete_prefix 'fn'
+      (val = this.casecmp that) == 0 ? this <=> that : val
+    end
+  end)
+end
+----
+
+You load this code when calling Asciidoctor PDF as follows:
+
+ $ asciidoctor-pdf -r ./index-customizer.rb doc.adoc
+
+Now the index terms will be grouped and sorted according to your custom rules.
+
 == Optimizing the Generated PDF
 
 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.
 
+IMPORTANT: If you're creating a PDF for Amazon's Kindle Direct Publishing (KDP), GitLab repository preview, or other online publishers, you'll likely need to optimize the file before uploading.
+In their words, you must tidy up the reference tree and https://kdp.amazon.com/en_US/help/topic/G201953020#check[flatten all transparencies^] (mostly likely referring to images).
+If you don't do this step, the platform may reject your upload or fail to display it properly.
+(For KDP, `-a optimize` works best.
+For GitLab repository preview, either `-a optimize` or `hexapdf optimize` will do the trick.)
+
 === Enable Stream Compression
 
 The simplest way to reduce the size of the PDF file is to enable stream compression (using the FlateDecode method).
@@ -1114,7 +1229,7 @@ If you have difficulty getting the `rghost` gem installed, or you aren't getting
 
 === 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.
 
@@ -1177,6 +1292,31 @@ You can also disable page compressioin (e.g., `--no-compress-pages` from the CLI
 
 hexapdf also allows you to add password protection to your PDF, if that's something you're interested in doing.
 
+=== Rasterizing the PDF
+
+Instead of optimizing the objects in the vector PDF, you may want to rasterize the PDF instead.
+Rasterizing the PDF prevents any of the text or other objects from being selected, similar to a scanned document.
+
+Asciidoctor PDF doesn't provide built-in support for rasterizing the generated PDF.
+However, you can use Ghostscript to flatten all the text in the PDF, thus preventing it from being selected.
+
+ $ gs -dBATCH -dNOPAUSE -sDEVICE=pdfwrite -dNoOutputFonts -r300 -o output.pdf input.pdf
+
+You can adjust the value of the `-r` option (the density) to get a higher or lower quality result.
+
+Alternately, you can use the `convert` command from ImageMagick to convert each page in the PDF to an image.
+
+ $ convert -density 300 -quality 100 input.pdf output.pdf
+
+Yet another option is to combine Ghostscript and ImageMagick to produce a PDF with pages converted to images.
+
+ $ gs -dBATCH -dNOPAUSE -sDEVICE=png16m -o /tmp/tmp-%02d.png -r300 input.pdf
+   convert /tmp/tmp-*.png output.pdf
+   rm -f /tmp/tmp-*.png
+
+Using Ghostscript to handle the rasterization produces a much smaller output file.
+The drawback of using Ghostscript in this way is that it has to use intermediate files.
+
 ifndef::env-site[]
 == Contributing
 

data/asciidoctor-pdf.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |s|
   s.homepage = 'https://asciidoctor.org/docs/asciidoctor-pdf'
   s.license = 'MIT'
   # NOTE required ruby version is informational only; it's not enforced since it can't be overridden and can cause builds to break
-  #s.required_ruby_version = '>= 2.5.0'
+  #s.required_ruby_version = '>= 2.7.0'
   s.metadata = {
     'bug_tracker_uri' => 'https://github.com/asciidoctor/asciidoctor-pdf/issues',
     'changelog_uri' => 'https://github.com/asciidoctor/asciidoctor-pdf/blob/main/CHANGELOG.adoc',
@@ -35,20 +35,16 @@ Gem::Specification.new do |s|
 
   s.add_runtime_dependency 'asciidoctor', '~> 2.0'
   s.add_runtime_dependency 'prawn', '~> 2.4.0'
-  # NOTE must use prawn-table from head (defined in Gemfile) for full functionality
+  s.add_runtime_dependency 'matrix', '~> 0.4' # required until prawn >= 2.5.0 is released
   s.add_runtime_dependency 'prawn-table', '~> 0.2.0'
   s.add_runtime_dependency 'prawn-templates', '~> 0.1.0'
   s.add_runtime_dependency 'prawn-svg', '~> 0.32.0'
   s.add_runtime_dependency 'prawn-icon', '~> 3.0.0'
-  s.add_runtime_dependency 'safe_yaml', '~> 1.0.0'
   s.add_runtime_dependency 'concurrent-ruby', '~> 1.1'
   s.add_runtime_dependency 'treetop', '~> 1.6.0'
 
   s.add_development_dependency 'rake', '~> 13.0.0'
-  s.add_development_dependency 'rspec', '~> 3.10.0'
+  s.add_development_dependency 'rspec', '~> 3.11.0'
   s.add_development_dependency 'pdf-inspector', '~> 1.3.0'
-  # Asciidoctor PDF supports Rouge >= 2 (verified in CI build using 2.0.0)
-  s.add_development_dependency 'rouge', '~> 3.0'
-  s.add_development_dependency 'coderay', '~> 1.1.0'
   s.add_development_dependency 'chunky_png', '~> 1.4.0'
 end

data/data/fonts/ABOUT-mplus1mn-subset

@@ -15,7 +15,7 @@ The following changes were made using fontforge to produce mplus1mn-*-ascii.ttf
  ** Latin Extended-A (U+0100–U+017f)
  ** Greek Alphabet (U+0391–U+03c9)
  ** Cyrillic (U+0400–U+04ff)
- ** Assorted Symbols (U+20ac)
+ ** Assorted Symbols (U+20ac, U+2713–U+2714)
  ** Enclosed Numbers (U+2460–U+2473, U+2776–U+277f, U+24eb–U+24f4) (mplus1mn-regular only)
  ** Box Drawing Symbols (U+2500–U+257f)
  ** .notdef glyph

data/data/fonts/ABOUT-mplus1p-subset

@@ -13,10 +13,10 @@ The following changes were made using fontforge to produce mplus1p-regular-fallb
  ** Cyrillic (U+0400–U+04ff)
  ** Vietnamese (U+01a0–U01b0, U+1ea0–U1ef9)
  ** CJK (U+4e00–U+9fff, U+3000–U+303f) (mostly Japanese, limited selection based on what M+ supports)
- ** Mathematical Operators (U+2200–U+22ff)
+ ** Mathematical Operators (U+2200–U+22ff, U+2116)
  ** General Punctuation (U+2000–U203a)
  ** Geometric Shapes (U+25a0–U25ff)
- ** Assorted Symbols (U+20ac, U+2122, U+21d0–U+21d5, U+2190–U+2195, U+2610–U+2611, U+2713)
+ ** Assorted Symbols (U+20ac, U+2122, U+21d0–U+21d5, U+2190–U+2195, U+2610–U+2611, U+2713–U+2714)
  ** .notdef glyph
 * Added BOM (U+feff), hair space (U+200a), zero-width space (U+200b) and line feed (U+000a) characters (from blank)
 * Manually added non-breaking hyphen (U+2011) from hyphen (U+002d)

data/data/fonts/ABOUT-notosans-subset

@@ -0,0 +1,26 @@
+Noto Sans fonts are generated from the google-noto-sans-fonts-20161022 Fedora RPM package (commit 86b2e553c3e3e4d6614dadd1fa0a7a6dafd74552).
+
+The following changes were made using fontforge to produce the notosans-*-subset.ttf fonts:
+
+* Mapped single arrows <- (U+2190) and -> (U+2192) to double arrows <= (U+21d0) and => (U+21d2)
+* Manually added non-breaking hyphen (U+2011) from hyphen (U+002d)
+* Moved arrows (U+21d0, U+21d2, U+2190, U+2192) up in line to align with middle of X
+* Subsetted to include:
+ ** Non-visible Characters (U+feff, U+00a0)
+ ** Basic Latin (U+0020–U+007e)
+ ** Latin-1 Supplement (U+00a0–U+00fd)
+ ** Latin Extended-A (U+0100–U+017f)
+ ** Greek (U+0370–U+03ff)
+ ** Cyrillic (U+0400–U+04ff)
+ ** Vietnamese (U+01a0–U01b0, U+1ea0–U1ef9)
+ ** Mathematical Operators (U+2200–U+22ff, U+2116)
+ ** General Punctuation (U+2000–U203a)
+ ** Geometric Shapes (U+25a0–U25ff)
+ ** Assorted Symbols (U+20ac, U+2122, U+21d0, U+21d2, U+2190, U+2192)
+ ** .notdef glyph
+* Imported ballot boxes from Font Awesome (U+2610, U+2611) (Noto Serif Regular only)
+* Added line feed character (U+000a)
+* Generated old-style kern table (neither Apple or OpenType) (required to make kerning work in Prawn) (flags: 0x90)
+* Removed Truetype instructions (information not used by Prawn)
+* Generated with PS Glyph Names option enabled (didn't use 0x04 flag)
+* Generate flags used, in total: 0x90 + 0x08

data/data/fonts/ABOUT-notoserif-subset

@@ -13,7 +13,7 @@ The following changes were made using fontforge to produce the notoserif-*-subse
  ** Greek (U+0370–U+03ff)
  ** Cyrillic (U+0400–U+04ff)
  ** Vietnamese (U+01a0–U01b0, U+1ea0–U1ef9)
- ** Mathematical Operators (U+2200–U+22ff)
+ ** Mathematical Operators (U+2200–U+22ff, U+2116)
  ** General Punctuation (U+2000–U203a)
  ** Geometric Shapes (U+25a0–U25ff)
  ** Assorted Symbols (U+20ac, U+2122, U+21d0, U+21d2, U+2190, U+2192)