asciidoctor-pdf 1.6.2 → 2.0.0.alpha.1

data/docs/theming-guide.adoc

@@ -7,7 +7,6 @@ Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
 :experimental:
 ifndef::env-github[:icons: font]
 ifdef::env-github[]
-:outfilesuffix: .adoc
 :!toc-title:
 :caution-caption: :fire:
 :important-caption: :exclamation:
@@ -18,8 +17,8 @@ endif::[]
 :window: _blank
 // Aliases:
 :conum-guard-yaml: #
-ifndef::icons[:conum-guard-yaml: # #]
 ifdef::backend-pdf[:conum-guard-yaml: # #]
+:url-repo-root: https://github.com/asciidoctor/asciidoctor-pdf/tree/main
 :url-fontforge: https://fontforge.github.io/en-US/
 :url-fontforge-scripting: https://fontforge.github.io/en-US/documentation/scripting/
 :url-prawn: http://prawnpdf.org
@@ -28,19 +27,18 @@ ifdef::backend-pdf[:conum-guard-yaml: # #]
 Topics remaining to document:
 * line height and line height length (and what that all means)
 * title page layout / title page images (logo & background)
-* document that unicode escape sequences can be used inside double-quoted strings
 ////
 
 [.lead]
-The theming system in Asciidoctor PDF is used to control the layout and styling of the PDF file Asciidoctor PDF generates from AsciiDoc.
-This document describes how the theming system works, how to define a custom theme in YAML and how to activate the theme when running Asciidoctor PDF.
+The theming system is used to control the style of a PDF file generated by Asciidoctor PDF from AsciiDoc.
+This document describes how the theming system works, how to define a custom theme in YAML, and how to activate the theme when running Asciidoctor PDF.
 
 TIP: The quickest way to create your own theme is to <<Extends,extend the default theme>>.
-This not only gives you a set of foundation styles to build on, it also provides a collection of <<Bundled Fonts,bundled fonts>>.
-If you want to replace the bundled fonts with your own, you must declare the name and location of each font in the <<Custom Fonts,font catalog>>.
-To reuse the bundled fonts, you can either extend the default theme and/or redeclare the bundled fonts in the font catalog.
+This gives you a set of foundation styles to build on and provides a collection of <<Bundled Fonts,bundled fonts>> (which you don't have to redeclare).
+If you want to use your own fonts, you must declare the name and location of each font in the <<Custom Fonts,font catalog>>.
+If you want to combine your own fonts with the bundled fonts, you can either extend the font catalog (by setting `merge: true`) or <<Extending the Font Catalog,redeclare the bundled fonts>> alongside your own.
 
-WARNING: If you don't declare your own fonts (or extend the default theme), only the built-in (AFM) fonts provided by the PDF reader will be available.
+WARNING: If the theme doesn't specify any fonts (nor are they being inherited), only the built-in (AFM) fonts provided by the PDF reader will be available.
 Using AFM fonts can result in missing functionality and warnings.
 See the <<Built-In (AFM) Fonts>> section to learn more about these limitations.
 
@@ -52,6 +50,10 @@ The Asciidoctor PDF theme language is described using the http://en.wikipedia.or
 Therefore, if you have a background in web design, the terminology should be immediately familiar to you.
 *Note, however, that the theming system isn't actually CSS.*
 
+The theme can generally influence PDF settings, page numbering, font properties, background and borders, character selections, spacings, and running content.
+It has limited influence over the layout of elements on the page.
+If your theming requirements demand more than what this theming system can accomodate, you can <<extending-the-converter,extend the converter>> to gain more control over the layout and style.
+
 The theme file must be named _<name>-theme.yml_, where `<name>` is the name of the theme.
 _We recommend *not* using the names *base* or *default* so you don't confuse it with one of the built-in themes._
 
@@ -69,14 +71,14 @@ Some of these properties have different names from those found in CSS.
 
 * An underscore (`_`) may be used in place of a hyphen (`-`) in all property names (so you may use `font_family` or `font-family`).
 * An underscore (`_`) may be used in place of a hyphen (`-`) in all variable names (so you may use `$base_font_family` or `$base-font-family`).
-* Instead of separate properties for font weight and font style, the theme language combines these settings in the `font-style` property (allowed values: `normal`, `bold`, `italic` and `bold_italic`).
+* Instead of separate properties for font weight and font style, the theme language combines these settings in the `font-style` property (allowed values: `normal`, `bold`, `italic`, and `bold_italic`).
 * The `align` property in the theme language is roughly equivalent to the `text-align` property in CSS.
 * The `font-color` property in the theme language is equivalent to the `color` property in CSS.
 ====
 
 A theme is described in a YAML-based data format and stored in a dedicated theme file.
 YAML is a human-friendly data format that resembles CSS and helps to describe the theme.
-The theme language adds some extra features to YAML, such as variables, basic math, measurements and color values.
+The theme language adds some extra features to YAML, such as variables, basic math, measurements, and color values.
 These enhancements will be explained in detail in later sections.
 
 === Basic Theme
@@ -86,6 +88,7 @@ Here's an example of a basic theme file that extends the base theme:
 .basic-theme.yml
 [source,yaml]
 ----
+extends: base
 page:
   layout: portrait
   margin: [0.75in, 1in, 0.75in, 1in]
@@ -96,16 +99,14 @@ base:
   font-size: 12
   line-height-length: 17
   line-height: $base-line-height-length / $base-font-size
-vertical-spacing: $base-line-height-length
 heading:
   font-color: #262626
   font-size: 17
   font-style: bold
   line-height: 1.2
-  margin-bottom: $vertical-spacing
 link:
   font-color: #002FA7
-outline-list:
+list:
   indent: $base-font-size * 1.5
 footer:
   height: $base-line-height-length * 2.5
@@ -118,7 +119,7 @@ footer:
       content: $footer-recto-right-content
 ----
 
-When creating a new theme, you only have to define the keys you want to override from the base theme, which is loaded prior to loading your custom theme.
+When creating a new theme, you only have to define the keys you want to override from the extended theme, which is loaded prior to loading your custom theme.
 All the available keys are documented in <<Keys>>.
 The converter uses the information from the theme map to help construct the PDF.
 
@@ -134,14 +135,17 @@ base:
 ----
 
 You can also point the extends key at another custom theme to extend from it.
-If you don't want to extend any theme, including the base theme, assign the value `~` to the `extends` key (i.e., `extends: ~`).
+If you don't want to extend any theme, including the base theme, omit the `extends` key or assign the value `~` to the `extends` key (i.e., `extends: ~`).
+
+If the same theme appears multiple times in the theme hierarchy, it will only be loaded once by default.
+You can force the theme to be loaded, even if it has already been loaded, by adding the `!important` keyword at the end of the value offset by a space.
 
-WARNING: If you start a new theme from scratch, we strongly recommend defining TrueType fonts and specifying them in the `base` and `literal` categories.
+WARNING: If you start a new theme from scratch, we strongly recommend defining TrueType fonts and specifying them in the `base` and `codespan` categories.
 Otherwise, Asciidoctor PDF will use built-in AFM fonts, which can result in missing functionality and warnings.
 
 [TIP]
 ====
-Instead of creating a theme from scratch, another option is to download the https://github.com/asciidoctor/asciidoctor-pdf/blob/main/data/themes/default-theme.yml[default-theme.yml] file from the source repository.
+Instead of creating a theme from scratch, another option is to download the {url-repo-root}/data/themes/default-theme.yml[default-theme.yml] file from the source repository.
 Save the file using a unique name (e.g., _custom-theme.yml_) and start hacking on it.
 
 Alternatively, you can snag the file from your local installation using the following command:
@@ -235,7 +239,7 @@ The following keys are inherited:
 * font-style
 * text-transform
 * line-height (currently some exceptions)
-* margin-bottom (if not specified, defaults to $vertical-spacing)
+* margin-bottom
 
 .Heading Inheritance
 ****
@@ -322,7 +326,7 @@ base:
 === Math Expressions & Functions
 
 The theme language supports basic math operations to support calculated values.
-Like programming languages, multiply and divide take precedence over add and subtract.
+Like programming languages, the multiply and divide operators take precedence over the add and subtract operators.
 
 The following table lists the supported operations and the corresponding operator for each.
 
@@ -414,7 +418,7 @@ The following units are supported:
 |pt (default)
 |===
 
-. A percentage with the % unit is calculated relative to the width or height of the content area.
+1. A percentage with the % unit is calculated relative to the width or height of the content area.
 Viewport-relative percentages (vw or vh units) are calculated as a percentage of the page width or height, respectively.
 Currently, percentage units can only be used for placing elements on the title page or for setting the width of a block image.
 
@@ -486,15 +490,8 @@ The following transforms are recognized:
 
 [CAUTION#transform-unicode-letters]
 ====
-Since Ruby 2.4, Ruby has built-in support for transforming the case of any letter defined by Unicode.
-
-If you're using Ruby < 2.4, and the text you want to transform contains characters beyond the Basic Latin character set (e.g., an accented character), you must install either the `activesupport` or the `unicode` gem in order for those characters to be transformed.
-
- $ gem install activesupport
-
-or
-
- $ gem install unicode
+Ruby 2.5 and better has built-in support for transforming the case of any letter defined by Unicode.
+You no longer need the `activesupport` or `unicode` gem to transform characters beyond the Basic Latin character set (e.g., accented characters).
 ====
 
 === Colors
@@ -600,6 +597,7 @@ The `transparent` keyword can be used for the background or border color, but no
 An image is specified either as a bare image path or as an inline image macro as found in the AsciiDoc syntax.
 Images in the theme file are currently resolved relative to the value of the `pdf-themesdir` attribute.
 (If `pdf-theme` is a path that ends in `.yml`, and `pdf-themesdir` is not set, then the images are resolved relative to the directory of the path specified by `pdf-theme`).
+If you want to use an image in your theme that's relative to the document you're converting, you can prefix the target with the `\{docdir}` attribute reference.
 
 The following image types (and corresponding file extensions) are supported:
 
@@ -608,7 +606,7 @@ The following image types (and corresponding file extensions) are supported:
 * SVG (.svg)
 
 CAUTION: The GIF format (.gif) and BMP format (.bmp) are not supported unless you're using prawn-gmagick.
-See https://github.com/asciidoctor/asciidoctor-pdf#supporting-additional-image-file-formats[support for additional image file formats] for details.
+See {url-repo-root}/README.adoc#supporting-additional-image-file-formats[support for additional image file formats] for details.
 
 Here's how an image is specified in the theme file as a bare image path:
 
@@ -627,6 +625,13 @@ title-page:
 ----
 
 In either case, the image is resolved relative to the value of the `pdf-themesdir` attribute, as previously described.
+If you want to instead reference an image relative to the document you're converting, then prefix the target with the `\{docdir}` attribute reference.
+
+[source,yaml]
+----
+title-page:
+  background-image: image:{docdir}/images/title-cover.png[]
+----
 
 Like in the AsciiDoc syntax, wrapping the value in the image macro allows you to specify other settings, such as `pdfwidth`, `fit`, and/or `align`.
 For example:
@@ -664,7 +669,7 @@ Additionally, normal substitutions are applied to the value of content keys for
 
 == Fonts
 
-You can select from <<built-in-afm-fonts,built-in PDF fonts>>, <<bundled-fonts,fonts bundled with Asciidoctor PDF>> or <<custom-fonts,custom fonts>> loaded from TrueType font (TTF) files.
+You can select from <<built-in-afm-fonts,built-in PDF fonts>>, <<bundled-fonts,fonts bundled with Asciidoctor PDF>> or <<custom-fonts,custom fonts>> loaded from TrueType (TTF) or OpenType (OTF) font files.
 If you want to use custom fonts, you must first declare them in your theme file.
 
 IMPORTANT: Asciidoctor has no challenge working with Unicode.
@@ -711,7 +716,7 @@ Even though the built-in fonts require the content to be encoded in WINANSI, _yo
 Asciidoctor PDF encodes the content into WINANSI when building the PDF.
 
 WARNING: Built-in (AFM) fonts do not use the <<fallback-fonts,fallback fonts>>.
-In order for the fallback font to kick in, you must use a TrueType font as the primary font.
+In order for the fallback font to kick in, you must use a TrueType font anywhere you want the fallback font to be used (e.g., the base font family, the code font family, etc).
 
 .WINANSI Encoding Behavior
 ****
@@ -744,7 +749,7 @@ http://www.google.com/get/noto/#/family/noto-serif[Noto Serif]::
 A serif font that can be styled as normal, italic, bold or bold_italic.
 
 http://mplus-fonts.osdn.jp/mplus-outline-fonts/design/index-en.html#mplus_1mn[M+ 1mn]::
-A monospaced font that maps different thicknesses to the styles normal, italic, bold and bold_italic.
+A monospaced font that maps different thicknesses to the styles normal, italic, bold, and bold_italic.
 Also provides the circuled numbers used in callouts.
 
 http://mplus-fonts.osdn.jp/mplus-outline-fonts/design/index-en.html#mplus_1p[M+ 1p Fallback]::
@@ -752,35 +757,39 @@ A sans-serif font that provides a very complete set of Unicode glyphs.
 Cannot be styled as italic, bold or bold_italic.
 Used as the fallback font in the `default-with-fallback-font` theme.
 
-TIP: The default themes in Asciidoctor PDF < 2 do not include the `GEM_FONTS_DIR` prefix in the path of the bundled font files.
-Therefore, if you want to specify the location of custom fonts using the `pdf-fontsdir` attribute, yet still be able to use the bundled fonts, you need to qualify the path of the bundled fonts using the `GEM_FONTS_DIR` token.
-To do so, you can either a) redeclare the bundle fonts in your theme and prefix the path with the segment `GEM_FONTS_DIR` (e.g., `GEM_FONTS_DIR/mplus1p-regular-fallback.ttf`, or b) include `GEM_FONTS_DIR` in the value of the `pdf-fontsdir` attribute separated by the location of your custom fonts using a semi-colon (e.g., `"path/to/your/fonts;GEM_FONTS_DIR"`).
+TIP: The default themes refer to the bundled fonts using the `GEM_FONTS_DIR` prefix.
+That means you can extend a default theme and not have to worry about how the bundled fonts get resolved.
+If you redeclare the bundled fonts in your custom theme, be sure to prefix the path with the `GEM_FONTS_DIR` token.
+An alternative approach is to include `GEM_FONT_DIR` in the value of the `pdf-fontsdir` attribute separated by the location of your custom fonts using a comma (e.g., `path/to/your/fonts,GEM_FONTS_DIR`) or a semi-colon (e.g., `path/to/your/fonts;GEM_FONTS_DIR`).
 
 === Custom Fonts
 
-The limited character set of WINANSI, or the bland look of the built-in fonts, may motivate you to load your own font.
+The limited character set of WINANSI, or the plain look of the built-in or bundled fonts, may motivate you to incorporate your own fonts.
 Custom fonts can enhance the look of your PDF theme substantially.
 
+IMPORTANT: In order for a third-party font to work properly with Prawn (and hence Asciidoctor PDF), several modifications are required.
+See <<Preparing a Custom Font>> to learn how to prepare your font for use with Asciidoctor PDF.
+
+==== Selecting Your Font
+
 To start, find the TTF file collection for the font you want to use.
-A collection typically consists of all four font styles:
+A collection typically consists of four font styles:
 
 * normal
 * italic
 * bold
 * bold_italic
 
-You'll need all four variants to support AsciiDoc content properly.
-Otherwise, the converter will likely crash.
-If you don't have one of the variants, you can simply reuse the normal variant in its place.
-_Asciidoctor PDF cannot italicize a font dynamically like a browser can, so the italic styles are required._
+You'll need all four variants to support AsciiDoc content properly (unless the font only has a single variant).
+If you do not register the font correctly, the converter may crash or revert to the fallback font, depending on how the theme is configured.
+If one of the variants is missing from your collection, you can simply reuse the normal / single variant in its place.
 
-In order for a third-party font to work properly with Prawn (and hence Asciidoctor PDF), several modifications are required.
-See <<Preparing a Custom Font>> to learn how to prepare your font for use with Asciidoctor PDF.
+WARNING: Asciidoctor PDF cannot italicize a font dynamically like a browser can, so the italic styles are required to italicize text.
 
-Once you've obtained the TTF files, put them in the directory inside your project where you want to store the fonts.
+Once you've obtained the TTF (or OTF) files, put them in the directory inside your project where you want to store the fonts.
 It's recommended that you name them consistently so it's easier to type the names in the theme file.
 
-Let's assume the name of the font is https://github.com/google/roboto/tree/master/out/RobotoTTF[Roboto].
+Let's assume the name of the font is https://github.com/googlefonts/roboto/releases[Roboto].
 Rename the files as follows:
 
 * roboto-normal.ttf (_originally Roboto-Regular.ttf_)
@@ -788,22 +797,64 @@ Rename the files as follows:
 * roboto-bold.ttf (_originally Roboto-Bold.ttf_)
 * roboto-bold_italic.ttf (_originally Roboto-BoldItalic.ttf_)
 
-Next, declare the font under the `font-catalog` key at the top of your theme file, giving it a unique key (e.g., `Roboto`).
+==== Declaring Your Font
 
-[source,yaml]
+Next, declare the font under the `font-catalog` key at the top of your theme file.
+Assign each font a unique key (e.g., `Roboto`) and specify the path to each of the four font styles under that key.
+
+[source,yaml,subs=attributes+]
 ----
 font:
   catalog:
+    merge: false {conum-guard-yaml} <1>
     Roboto:
       normal: roboto-normal.ttf
       italic: roboto-italic.ttf
       bold: roboto-bold.ttf
       bold_italic: roboto-bold_italic.ttf
 ----
+<1> Set value to true to merge catalog with theme you're extending.
 
-CAUTION: You must declare all four variants.
+If you use this form, you must declare all four variants.
 If you're missing the font file for one of the variants, configure it to use the same font file as the normal variant.
 
+If your font only has a single variant, assign the font path to the font key directly.
+
+[source,yaml,subs=attributes+]
+----
+font:
+  catalog:
+    merge: false {conum-guard-yaml} <1>
+    VLGothic: vlgothic.ttf
+----
+<1> Set value to true to merge catalog with theme you're extending.
+
+Font paths can be absolute or relative.
+Absolute paths are used as is.
+Relative font paths are resolved from the <<Configuring the Font Search Path,font search path>>.
+You can also use the `GEM_FONTS_DIR` keyword to refer to the location of the bundled fonts.
+
+You can add any number of fonts to the catalog.
+Each font must be assigned a unique key, as shown here:
+
+[source,yaml,subs=attributes+]
+----
+font:
+  catalog:
+    merge: false {conum-guard-yaml} <1>
+    Roboto:
+      normal: roboto-normal.ttf
+      italic: roboto-italic.ttf
+      bold: roboto-bold.ttf
+      bold_italic: roboto-bold_italic.ttf
+    Roboto Light:
+      normal: roboto-light-normal.ttf
+      italic: roboto-light-italic.ttf
+      bold: roboto-light-bold.ttf
+      bold_italic: roboto-light-bold_italic.ttf
+----
+<1> Set value to true to merge catalog with theme you're extending.
+
 You can use the key that you assign to the font in the font catalog anywhere the `font-family` property is accepted in the theme file.
 For example, to use the Roboto font for all headings (section titles and discrete headings), use:
 
@@ -811,17 +862,35 @@ For example, to use the Roboto font for all headings (section titles and discret
 ----
 heading:
   font-family: Roboto
+  font-style: bold
 ----
 
+The font name and font style are used to locate an entry in the font catalog.
+
+.About Fonts in SVGs
+****
+Fonts defined for text in SVGs will be mapped to the font catalog from your theme.
+So if you have an SVG that requires a specific font, you'll need to declare that font in the font catalog in your theme.
+
+We recommend that you match the font key in your theme file to the name of the font seen by the operating system.
+This will allow you to use the same font names (aka families) in both your graphics program and Asciidoctor PDF, thus making them portable.
+****
+
+==== Configuring the Font Search Path
+
 When you execute Asciidoctor PDF, specify the directory where the fonts reside using the `pdf-fontsdir` attribute:
 
  $ asciidoctor-pdf -a pdf-theme=basic-theme.yml -a pdf-fontsdir=path/to/fonts document.adoc
 
-You can specify multiple directories by separating the entries with a semi-colon and enclosing the value in double quotes:
+You can specify multiple directories by separating the paths with either a comma (`,`):
+
+ $ asciidoctor-pdf -a pdf-theme=basic-theme.yml -a pdf-fontsdir=path/to/fonts,path/to/more-fonts document.adoc
+
+or a semi-colon (`;`) (which requires enclosing the combined value in double quotes to escape the delimiter from the shell):
 
  $ asciidoctor-pdf -a pdf-theme=basic-theme.yml -a pdf-fontsdir="path/to/fonts;path/to/more-fonts" document.adoc
 
-To include the bundled fonts in the search, use the `GEM_FONTS_DIR` token:
+To include the location of the bundled fonts in the search, include the `GEM_FONTS_DIR` token in the list:
 
  $ asciidoctor-pdf -a pdf-theme=basic-theme.yml -a pdf-fontsdir="path/to/fonts;GEM_FONTS_DIR" document.adoc
 
@@ -829,36 +898,16 @@ When running Asciidoctor PDF on the JVM (perhaps using AsciidoctorJ PDF), you ca
 
  $ asciidoctorj -b pdf -a pdf-theme=basic-theme.yml -a pdf-fontsdir="uri:classloader:/path/to/fonts;GEM_FONTS_DIR" document.adoc
 
-TIP: When Asciidoctor PDF creates the PDF, it only embeds the glyphs from the font that are needed to render the characters present in the document.
+==== Subsetting Your Font
+
+When Asciidoctor PDF creates the PDF, it only embeds the glyphs from the font that are needed to render the characters present in the document.
 Effectively, it subsets the font.
 While that saves space taken up by the generated PDF, you may still be storing the full font in your source repository.
+
 To minimize the size of the source font, you can use {url-fontforge}[FontForge] to subset the font ahead of time.
 Subsetting a font means remove glyphs you don't plan to use.
 Doing so is not a requirement, simply a personal preference.
 
-You can add any number of fonts to the catalog.
-Each font must be assigned a unique key, as shown here:
-
-[source,yaml]
-----
-font:
-  catalog:
-    Roboto:
-      normal: roboto-normal.ttf
-      italic: roboto-italic.ttf
-      bold: roboto-bold.ttf
-      bold_italic: roboto-bold_italic.ttf
-    Roboto Light:
-      normal: roboto-light-normal.ttf
-      italic: roboto-light-italic.ttf
-      bold: roboto-light-bold.ttf
-      bold_italic: roboto-light-bold_italic.ttf
-----
-
-Text in SVGs will use the font catalog from your theme.
-We recommend that you match the font key in your theme file to the name of the font seen by the operating system.
-This will allow you to use the same font names (aka families) in both your graphics program and Asciidoctor PDF, thus making them portable.
-
 === Fallback Fonts
 
 If a TrueType font is missing a character needed to render the document, such as a special symbol or emoji, you can have Asciidoctor PDF look for the character in a fallback font.
@@ -868,7 +917,7 @@ If the character isn't found in the fallback font, it will mostly likely be repl
 
 IMPORTANT: When defining the fallback font, you *must specify all four variants* (normal, bold, italic, bold_italic), even if you use the same font file for each.
 
-IMPORTANT: The fallback font only gets used when the primary font is a TrueType font (i.e., TTF, DFont, TTC).
+IMPORTANT: The fallback font only gets used when the primary font is a TrueType or OpenType font (i.e., TTF, DFont, TTC, OTF).
 Any glyph missing from an AFM font is simply replaced with the "`not`" glyph (`&#172;`).
 
 CAUTION: The `default` theme does not use a fallback font.
@@ -892,15 +941,20 @@ font:
       italic: roboto-italic.ttf
       bold: roboto-bold.ttf
       bold_italic: roboto-bold_italic.ttf
-    DroidSansFallback:
-      normal: droid-sans-fallback.ttf
-      italic: droid-sans-fallback.ttf
-      bold: droid-sans-fallback.ttf
-      bold_italic: droid-sans-fallback.ttf
+    DroidSansFallback: droid-sans-fallback.ttf
+----
+
+Notice that we only declare the fallback font file once using a literal value.
+This ensures the font is defined for all four variants so it will be used regardless of which font style is active when it's called on.
+This assignment is equivalent to the following:
+
+[source,yaml]
+----
+DroidSansFallback:
+  '*': droid-sans-fallback.ttf
 ----
 
-Notice that we define all four variants for the fallback font, even though we're use the same font file for each variant.
-This ensures the fallback font will be used regardless of which font style is active when it gets called on.
+The benefit of this syntax is that it allows you to use a separate font file for just one of the variants (e.g., bold).
 
 Next, add the key name to the `fallbacks` key under the `font-catalog` key.
 The `fallbacks` key accepts an array of values, meaning you can specify more than one fallback font.
@@ -915,11 +969,7 @@ font:
       italic: roboto-italic.ttf
       bold: roboto-bold.ttf
       bold_italic: roboto-bold_italic.ttf
-    DroidSansFallback:
-      normal: droid-sans-fallback.ttf
-      italic: droid-sans-fallback.ttf
-      bold: droid-sans-fallback.ttf
-      bold_italic: droid-sans-fallback.ttf
+    DroidSansFallback: droid-sans-fallback.ttf
   fallbacks:
   - DroidSansFallback
 ----
@@ -936,7 +986,7 @@ base:
 
 That's it!
 Now you're covered.
-If your custom TTF font is missing a glyph, Asciidoctor PDF will look in your fallback font.
+If your custom font is missing a glyph, Asciidoctor PDF will look in your fallback font.
 You don't need to reference the fallback font anywhere else in your theme file.
 
 Here's another example that shows how to use an alternative emoji font (Symbola):
@@ -964,11 +1014,11 @@ This nested structure is for organizational purposes only.
 All keys are flatted when the theme is loaded (e.g., `align` nested under `base` becomes `base-align`).
 
 The converter uses the values of these keys to control how most elements are arranged and styled in the PDF.
-The default values listed in this section get inherited from the https://github.com/asciidoctor/asciidoctor-pdf/blob/main/data/themes/base-theme.yml[base theme].
+The default values listed in this section get inherited from the {url-repo-root}/data/themes/base-theme.yml[base theme].
 
-IMPORTANT: The https://github.com/asciidoctor/asciidoctor-pdf/blob/main/data/themes/default-theme.yml[default theme] has a different set of values which are not shown in this guide.
+IMPORTANT: The {url-repo-root}/data/themes/default-theme.yml[default theme] has a different set of values which are not shown in this guide.
 
-When creating a theme, all keys are optional.
+When creating a theme that extends the base theme, all keys are optional.
 Required keys are provided by the base theme.
 Therefore, you only have to declare keys that you want to override.
 
@@ -992,12 +1042,7 @@ If the filename is absolute, it's used as is.
 If the filename begins with `./`, it's resolved as a theme file relative to the current theme file.
 Otherwise, the filename is resolved as a theme file in the normal way (relative to the value of the `pdf-themesdir` attribute).
 
-CAUTION: If you define the <<Custom fonts,font catalog>> in a theme that extends from `default`, you either have to redeclare any built-in font that on which the combined theme depends, or you need to set `merge: true` above your font definitions.
-You can find the built-in definitions in default theme.
-You'll then need to include `GEM_FONTS_DIR` in the value of the `pdf-fontsdir` attribute so that the converter can find and register them.
-To avoid having to do this, make sure you set the font family for any element that declares a font family in the default theme.
-
-Currently, the base theme is always loaded first.
+Currently, the theme starts out empty.
 Then, the files referenced by the extends key are loaded in order.
 Finally, the keys in the current file are loaded.
 Each time a theme is loaded, the keys are overlaid onto the keys from the previous theme.
@@ -1007,13 +1052,93 @@ Each time a theme is loaded, the keys are overlaid onto the keys from the previo
 |Key |Value Type |Example
 
 |extends
-|String or Array
+|String or Array +
 (default: [])
 |extends:
 - default
 - ./brand-theme.yml
 |===
 
+=== Font
+
+The font key is where you declare custom fonts (`catalog` key) and configure the fallback fonts (`fallbacks` key).
+
+The data format of the `catalog` key is a map.
+Each key is the name of the font that you can use to refer to the font elsewhere in the theme.
+The value is either a font path (which is used for all font styles) or another map that specifies a font path to each of the four font styles.
+You can also configure the `catalog` to merge entries from an inherited font catalog.
+See <<Extending the Font Catalog>>.
+
+The data format of the `fallbacks` key is an array.
+The values of the array are the font names declared in the `catalog` (or a name inherited from another theme).
+These fallbacks are used, in the order listed, when a glyph cannot be found in the primary font for a given element.
+
+[cols="1,2,5l"]
+|===
+|Key |Value Type |Example
+
+|catalog
+|Map
+|font:
+  catalog:
+    Noto Serif:
+      normal: GEM_FONTS_DIR/notoserif-regular-subset.ttf
+      bold: GEM_FONTS_DIR/notoserif-bold-subset.ttf
+      italic: GEM_FONTS_DIR/notoserif-italic-subset.ttf
+      bold_italic: GEM_FONTS_DIR/notoserif-bold_italic-subset.ttf
+
+|fallbacks
+|Array
+|font:
+  fallbacks:
+  - M+ 1p Fallback
+  - Noto Emoji
+|===
+
+==== Extending the Font Catalog
+
+If you define a <<Custom fonts,font catalog>> in a theme that extends from `default`, and you want to continue to use the bundled fonts in your theme, you either have to redeclare the bundled fonts:
+
+.Redeclaring the bundle fonts in a custom theme
+[source,yaml]
+----
+extends: default
+font:
+  catalog:
+    Noto Serif:
+      normal: GEM_FONTS_DIR/notoserif-regular-subset.ttf
+      bold: GEM_FONTS_DIR/notoserif-bold-subset.ttf
+      italic: GEM_FONTS_DIR/notoserif-italic-subset.ttf
+      bold_italic: GEM_FONTS_DIR/notoserif-bold_italic-subset.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
+    Your Font:
+      normal: /path/to/your/font.ttf
+heading:
+  font-family: Your Font
+----
+
+or you need to set `merge: true` above your font definitions:
+
+.Merging with the inherited font catalog
+[source,yaml]
+----
+extends: default
+font:
+  catalog:
+    merge: true
+    Your Font:
+      normal: /path/to/your/font.ttf
+heading:
+  font-family: Your Font
+----
+
+If you're referring to a bundled font, you'll need to prefix the path with `GEM_FONTS_DIR` (or add it to the value of the `pdf-fontsdir` attribute) so the converter can find and register it.
+You can find the bundle font definitions in default theme.
+
 [#keys-role]
 === Role
 
@@ -1022,7 +1147,7 @@ The name of the role is the first subkey level.
 The role name may contain a hyphen, but *a role name cannot contain an underscore*.
 The keys under the role are the theming properties.
 
-IMPORTANT: Custom roles only apply to inline phrases.
+IMPORTANT: Custom roles only apply to inline phrases and paragraphs.
 
 Here's an example of a role for making text red:
 
@@ -1057,9 +1182,11 @@ This role can be used as follows:
 ----
 
 The converter provides several predefined roles, which can can all be redefined.
+The `lead` defines the font properties for a lead paragraph, whether the role is assign implicitly or explicitly.
 The `big` and `small` roles map the font size to the $base-font-size-large and $base-font-size-small values, respectively.
 The `underline` and `line-through` roles add the underline and strikethrough decorations, respectively.
 The `subtitle` role is used to configure the font properties of the subtitle of a section title.
+The `unresolved` role is applied to the text of an unresolved reference (currently footnotes only).
 The color roles (e.g., `blue`), which you may be familiar with from the HTML converter, are not mapped by default.
 You'll need to define these color roles in your theme if you'd like to make use of them when converting to PDF.
 
@@ -1148,16 +1275,42 @@ You'll need to define these color roles in your theme if you'd like to make use
 
 |text-decoration-width
 |<<values,Number>> +
-(default: 1)
+(default: $base-text-decoration-width)
 |role:
   underline:
     text-decoration-width: 0.5
 |===
 
+[#keys-cover]
+=== Cover
+
+The keys in this category control the front and back cover images.
+Currently, the only supported feature is setting the image per side.
+
+[cols="3,4,5l"]
+|===
+|Key |Value Type |Example
+
+3+|[#key-prefix-cover]*Key Prefix:* <<key-prefix-cover,cover>>
+
+|<face>-image^[1]^
+|path, image macro^[2]^ +
+(default: _not set_)
+|cover:
+  front:
+    image: image:cover.pdf[page=2]
+|===
+1. `<face>` can be `front` or `back`.
+2. The value may be an image file or a PDF file.
+A relative path will be resolved relative to the value of the `pdf-themesdir` attribute.
+An image files is handled just like a background image.
+If a PDF file is specified, the first page is used unless another page is specified by the `page` attribute.
+The page from the PDF file will be imported as is.
+
 [#keys-page]
 === Page
 
-The keys in this category control the size, margins and background of each page (i.e., canvas).
+The keys in this category control the size, margins, and background of each page (i.e., canvas).
 We recommended that you define this category before all other categories.
 
 NOTE: The background of the title page can be styled independently of other pages.
@@ -1237,30 +1390,35 @@ See <<Title Page>> for details.
 |page:
   size: Letter
 
-|numbering-start-at^[5]^
-|title {vbar} toc {vbar} body {vbar} Integer +
+3+|[#key-prefix-page-numbering]*Key Prefix:* <<key-prefix-page-numbering,numbering>>
+
+|start-at^[5]^
+|cover {vbar} title {vbar} toc {vbar} after-toc {vbar} body {vbar} Integer +
 (default: body)
 |page:
-  numbering-start-at: toc
+  numbering:
+    start-at: toc
 |===
 
-. To disable the background color for the page, set the value to white (i.e., FFFFFF).
+1. To disable the background color for the page, set the value to white (i.e., FFFFFF).
 The color keyword `transparent` is not recognized in this context.
-. By default, page background and foreground images are automatically scaled to fit the bounds of the page (i.e., `fit=contain`) and centered (i.e., `position=center`).
+2. By default, page background and foreground images are automatically scaled to fit the bounds of the page (i.e., `fit=contain`) and centered (i.e., `position=center`).
 The size of the image can be controlled using any of the sizing attributes on the image macro (i.e., fit, pdfwidth, scaledwidth, or width) when `fit=none`.
 The position of the image can be controlled using the `position` attribute.
 If the recto (right-hand, odd-numbered pages) or verso (left-hand, even-numbered pages) background image is specified, it will be used only for that side (not available for the foreground image).
 If you define the keys using the flatten structure (e.g., `page-background-image-recto`), you can also set the default page background image (`page-background-image`), which will then be used as a fallback if a background image isn't specified for a given side.
 To disable the image, use the value `none`.
-. Target may be an absolute path or a path relative to the value of the `pdf-themesdir` attribute.
-. The margins for `recto` (right-hand, odd-numbered) and `verso` (left-hand, even-numbered) pages are calculated automatically from the margin-inner and margin-outer values.
+3. Target may be an absolute path or a path relative to the value of the `pdf-themesdir` attribute.
+4. The margins for `recto` (right-hand, odd-numbered) and `verso` (left-hand, even-numbered) pages are calculated automatically from the margin-inner and margin-outer values.
 These margins and used when the value `prepress` is assigned to the `media` document attribute.
 If no cover is specified, the recto margin is not applied to the title page.
-To apply the recto margin to the title page, but not include a cover, assign the value `~` to the `front-cover-image` attribute.
-. Only works if the document uses a title page (i.e., doctype is book or `title-page` attribute is set)
+To apply the recto margin to the title page, but not include a cover, assign the value `~` to the `front-cover-image` and `back-cover-image` attributes.
+5. The `cover` value is only recognized if the documet has a front cover page (i.e., `front-cover-image`).
+The `title`, `toc`, and `after-toc` values are only recognized if the title page is enabled (i.e., doctype is book or `title-page` attribute is set)
 The `toc` value only applies if the toc is in the default location (before the first page of the body).
-If the toc macro is used to position the toc, the start-at behavior is the same as if the toc is not enabled.
+If value is `toc`, and the toc macro is used to position the toc, the start-at behavior is the same as if the toc is not enabled.
 If value is an integer, page numbering will start at the specified page of the body (i.e., 1 is first page, 2 is second page, etc.)
+If value is `after-toc`, the page numbering will start after the toc, no matter where it's placed in the document.
 
 [#keys-base]
 === Base
@@ -1375,27 +1533,33 @@ NOTE: While it's common to define additional keys in this category (e.g., `base-
   text-decoration-width: 0.5
 |===
 
-. The `text-transform` key cannot be set globally.
+1. The `text-transform` key cannot be set globally.
 Therefore, this key should not be used.
 The value of `none` is implicit and is documented here for completeness.
-. `line-height-length` is a utility property that's internal to the theme.
+2. `line-height-length` is a utility property that's internal to the theme.
 It's used as an intermediate property for computing the `base-line-height` from the base font size and the desired line height size.
 For instance, if you set `base-line-height-length`, you can use `$base-line-height-length / $base-font-size` to set the value of `base-line-height`.
 You don't have to go about it this way in your own theme.
 
-[#keys-vertical-spacing]
-=== Vertical Spacing
+[#keys-quotes]
+=== Quotes
 
-The keys in this category control the general spacing between elements where a more specific setting is not designated.
+The keys in this category define the characters to use for typographic quotation marks (i.e., quotes).
 
 [cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|vertical-spacing
-|<<values,Number>> +
-(default: 12)
-|vertical-spacing: 10
+3+|[#key-prefix-quotes]*Key Prefix:* <<key-prefix-quotes,quotes>>
+
+|quotes
+|<<quoted-string,Quoted string[double-open, double-close, single-open, single-close]>> +
+(default: ['\&#8220;', '\&#8221;', '\&#8216;', '\&#8217;'])
+|quotes:
+- '&#x00ab;'
+- '&#x00bb;'
+- '&#x2039;'
+- '&#x203a;'
 |===
 
 [#keys-link]
@@ -1409,6 +1573,18 @@ The keys in this category are used to style hyperlink text.
 
 3+|[#key-prefix-link]*Key Prefix:* <<key-prefix-link,link>>
 
+|background-color
+|<<colors,Color>> +
+(default: _not set_)
+|link:
+  background-color: #efefef
+
+|border-offset
+|<<values,Number>> +
+(default: 0)
+|link:
+  border-offset: 2
+
 |font-color
 |<<colors,Color>> +
 (default: #0000ee)
@@ -1447,13 +1623,13 @@ The keys in this category are used to style hyperlink text.
 
 |text-decoration-width
 |<<values,Number>> +
-(default: 1)
+(default: $base-text-decoration-width)
 |link:
   text-decoration-width: 0.5
 |===
 
-[#keys-literal]
-=== (Inline) Literal
+[#keys-codespan]
+=== Codespan
 
 The keys in this category are used for inline monospaced text in prose and table cells.
 
@@ -1461,73 +1637,77 @@ The keys in this category are used for inline monospaced text in prose and table
 |===
 |Key |Value Type |Example
 
-3+|[#key-prefix-literal]*Key Prefix:* <<key-prefix-literal,literal>>
+3+|[#key-prefix-codespan]*Key Prefix:* <<key-prefix-codespan,codespan>>
 
 |background-color
 |<<colors,Color>> +
 (default: _not set_)
-|literal:
+|codespan:
   background-color: #f5f5f5
 
 |border-color^[1]^
 |<<colors,Color>> +
 (default: _not set_)
-|literal:
+|codespan:
   border-color: #cccccc
 
 |border-offset^[2]^
 |<<values,Number>> +
 (default: 0)
-|literal:
+|codespan:
   border-offset: 2
 
 |border-radius
 |<<values,Number>> +
 (default: _not set_)
-|literal:
+|codespan:
   border-radius: 3
 
 |border-width
 |<<values,Number>> +
 (default: $base-border-width)
-|literal:
+|codespan:
   border-width: 0.5
 
 |font-color
 |<<colors,Color>> +
 (default: _inherit_)
-|literal:
+|codespan:
   font-color: #b12146
 
 |font-family
 |<<fonts,Font family name>> +
 (default: Courier)
-|literal:
+|codespan:
   font-family: M+ 1mn
 
-|font-size
+|font-size^[3]^
 |<<values,Number>> +
 (default: _inherit_)
-|literal:
-  font-size: 12
+|codespan:
+  font-size: 1.15em
 
 |font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
-|literal:
+|codespan:
   font-style: bold
 |===
 
-. The border is only used if a border color is specified and the border width is not explicitly set to 0.
-The border only works properly if the literal phrase does not have nested formatting.
+1. The border is only used if a border color is specified and the border width is not explicitly set to 0.
+The border only works properly if the code phrase does not have nested formatting.
 Otherwise, the border will be inherited, producing a less than desirable result.
-. The border offset is the amount that the background and border swells around the text.
+2. The border offset is the amount that the background and border swells around the text.
 It does not affect the distance between the formatted phrase and the phrases that surround it.
+3. You're strongly encouraged to set the value of the font-size property to a relative font size using the `em` units (e.g., `0.9em`).
+A code span with a fixed font size will not be scaled when the font size of the parent element (e.g., table, caption, etc) is specified.
+However, by using a relative value, the font size will be computed relative to the size of the text that surrounds it, giving you effectively the same result.
 
 [#keys-heading]
 === Heading
 
-The keys in this category control the style of most headings, including part titles, chapter titles, sections titles, the table of contents title and discrete headings.
+The keys in this category control the style of most headings, including part titles, chapter titles, sections titles, the table of contents title, and discrete headings.
+The <<key-prefix-heading-level,heading-h1 key>> controls the font properties of the document title (aka doctitle) when the doctype is article and the title page is not enabled (i.e., the title-page document attribute is not set).
 
 [cols="3,4,5l"]
 |===
@@ -1586,7 +1766,7 @@ The keys in this category control the style of most headings, including part tit
 
 |text-decoration-width
 |<<values,Number>> +
-(default: 1)
+(default: $base-text-decoration-width)
 |heading:
   text-decoration-width: 0.5
 
@@ -1606,19 +1786,19 @@ The keys in this category control the style of most headings, including part tit
 |<<measurement-units,Measurement>> +
 (default: 4)
 |heading:
-  margin-top: $vertical-spacing * 0.2
+  margin-top: 6
 
 |margin-page-top
 |<<measurement-units,Measurement>> +
 (default: 0)
 |heading:
-  margin-page-top: $vertical-spacing
+  margin-page-top: 12
 
 |margin-bottom
 |<<measurement-units,Measurement>> +
 (default: 12)
 |heading:
-  margin-bottom: 9.6
+  margin-bottom: 6
 
 |min-height-after
 |<<measurement-units,Measurement>> +
@@ -1695,13 +1875,13 @@ The keys in this category control the style of most headings, including part tit
 |<<measurement-units,Measurement>> +
 (default: $heading-margin-top)
 |heading:
-  h2-margin-top: $vertical-spacing * 0.5
+  h2-margin-top: 6
 
 |margin-page-top
 |<<measurement-units,Measurement>> +
 (default: $heading-margin-page-top)
 |heading:
-  h2-margin-page-top: $vertical-spacing
+  h2-margin-page-top: 12
 
 |margin-bottom
 |<<measurement-units,Measurement>> +
@@ -1710,8 +1890,10 @@ The keys in this category control the style of most headings, including part tit
   h2-margin-bottom: 10
 |===
 
-. `<n>` is a number ranging from 1 to 6, representing each of the six heading levels.
-. A font size is assigned to each heading level by the base theme.
+1. `<n>` is a number ranging from 1 to 6, representing each of the six heading levels.
+h1 is used for part titles (book doctype) or the doctitle (article doctype when the title-page document attribute is not set).
+h2 is used for chapter titles (book doctype only).
+2. A font size is assigned to each heading level by the base theme.
 If you want the font size of a specific level to be inherited, you must assign the value `null` (or `~` for short).
 
 [#keys-section]
@@ -1731,7 +1913,8 @@ The keys in this category control the style of a section body.
 |section:
   indent: [0.5in, 0]
 |===
-. A single value gets applied to both the left and right side (e.g., `0.5in`).
+1. Applies to the section body only, excluding section titles and discrete headings.
+A single value gets applied to both the left and right side (e.g., `0.5in`).
 A two-value array configures the left and right side independently (e.g., `[0.5in, 0]`).
 
 [#keys-title-page]
@@ -1744,8 +1927,10 @@ If you want to enable the title page when using a different doctype (such as the
 
 NOTE: Subtitle partitioning of the doctitle is only enabled when the title page is also enabled.
 
-TIP: The title page can be disabled for the book doctype by setting the `notitle` attribute in the AsciiDoc document header (i.e., `:notitle:`).
-(For other doctypes, just don't set the `title-page` attribute).
+TIP: For documents that declare the book doctype, the title page can be omitted by setting the `notitle` attribute in the AsciiDoc document header (i.e., `:notitle:`) or by setting the value of the `title_page` category key in the theme to `false`.
+(It's counterpart, `:!showtitle:`, does not work with this converter).
+For all other doctypes, the title page is not added by default.
+In that case, setting the `:notitle:` attribute only removes the document title from the first page of content.
 
 [cols="3,4,5l"]
 |===
@@ -2143,19 +2328,19 @@ TIP: The title page can be disabled for the book doctype by setting the `notitle
     margin-bottom: 5
 |===
 
-. To disable the background color for the title page, set the value to white (i.e., FFFFFF).
+1. To disable the background color for the title page, set the value to white (i.e., FFFFFF).
 The color keyword `transparent` is not recognized in this context.
-. By default, page background images are automatically scaled to fit the bounds of the page (i.e., `fit=contain`) and centered (i.e., `position=center`).
+2. By default, page background images are automatically scaled to fit the bounds of the page (i.e., `fit=contain`) and centered (i.e., `position=center`).
 The size of the background image can be controlled using any of the sizing attributes on the image macro (i.e., fit, pdfwidth, scaledwidth, or width) when `fit=none`.
 The position of the background image can be controlled using the `position` attribute.
-. Target may be an absolute path or a path relative to the value of the `pdf-themesdir` attribute.
-. % unit is relative to content height; vh unit is relative to page height.
+3. Target may be an absolute path or a path relative to the value of the `pdf-themesdir` attribute.
+4. % unit is relative to content height; vh unit is relative to page height.
 
 [#keys-prose]
 === Prose
 
-The keys in this category control the spacing around paragraphs (paragraph blocks, paragraph content of a block, and other prose content).
-Typically, all the margin is placed on the bottom.
+The keys in this category control the spacing below paragraphs, lists, and index categories.
+The bottom margin is only added if the block is followed by an adjacent block within the same enclosure (e.g., a sidebar, a table cell, or the area outside of any blocks).
 
 [cols="3,4,5l"]
 |===
@@ -2163,17 +2348,17 @@ Typically, all the margin is placed on the bottom.
 
 3+|[#key-prefix-prose]*Key Prefix:* <<key-prefix-prose,prose>>
 
-|margin-top
-|<<measurement-units,Measurement>> +
-(default: 0)
-|prose:
-  margin-top: 0
+//|margin-top
+//|<<measurement-units,Measurement>> +
+//(default: 0)
+//|prose:
+//  margin-top: 0
 
 |margin-bottom
 |<<measurement-units,Measurement>> +
 (default: 12)
 |prose:
-  margin-bottom: $vertical-spacing
+  margin-bottom: 6
 
 |margin-inner^[1]^
 |<<measurement-units,Measurement>> +
@@ -2186,15 +2371,24 @@ Typically, all the margin is placed on the bottom.
 (default: _not set_)
 |prose:
   text-indent: 18
+
+|text-indent-inner^[2]^
+|<<measurement-units,Measurement>> +
+(default: _not set_)
+|prose:
+  text-indent-inner: 18
 |===
 
-. Controls the margin between adjacent paragraphs.
+1. Controls the margin between adjacent paragraphs.
 Useful when using indented paragraphs.
+2. Only applied to inner paragraphs (paragraphs that follow an adjacent paragraph).
 
 [#keys-block]
 === Block
 
-The keys in this category control the spacing around block elements when a more specific setting is not designated.
+The keys in this category control the spacing below block elements when a more specific setting is not designated.
+See the second table in this section for a list of blocks to which these keys apply.
+The bottom margin is only added if the block is followed by an adjacent block within the same enclosure (e.g., a sidebar, a table cell, or the area outside of any blocks).
 
 [cols="3,4,5l"]
 |===
@@ -2202,16 +2396,22 @@ The keys in this category control the spacing around block elements when a more
 
 3+|[#key-prefix-block]*Key Prefix:* <<key-prefix-block,block>>
 
+|anchor-top
+|<<measurement-units,Measurement>> +
+(default: 0)
+|block:
+  anchor-top: -12
+
 //|padding
 //|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>>
 //|block:
 //  padding: [12, 15, 12, 15]
 
-|margin-top
-|<<measurement-units,Measurement>> +
-(default: 0)
-|block:
-  margin-top: 6
+//|margin-top
+//|<<measurement-units,Measurement>> +
+//(default: 0)
+//|block:
+//  margin-top: 6
 
 |margin-bottom
 |<<measurement-units,Measurement>> +
@@ -2242,7 +2442,7 @@ Block styles are applied to the following block types:
 === Caption
 
 The keys in this category control the arrangement and style of block captions.
-In addition to the generic caption category, each of these keys can be set on the caption key nested inside the following block categories: blockquote, code, example, footnotes, image, listing, table, and verse.
+In addition to the generic caption category, each of these keys (except for text decoration) can be set on the caption key nested inside the following block categories: blockquote, code (applies to literal, listing, and source blocks), example, footnotes, image, table, and verse.
 
 [cols="3,4,5l"]
 |===
@@ -2286,6 +2486,24 @@ In addition to the generic caption category, each of these keys can be set on th
 |caption:
   font-style: italic
 
+|text-decoration
+|<<text-decorations,Text decoration>> +
+(default: none)
+|caption:
+  text-decoration: line-through
+
+|text-decoration-color
+|<<colors,Color>> +
+(default: $caption-font-color)
+|caption:
+  text-decoration-color: #ff0000
+
+|text-decoration-width
+|<<values,Number>> +
+(default: $base-text-decoration-width)
+|caption:
+  text-decoration-width: 0.5
+
 |text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
@@ -2305,13 +2523,13 @@ In addition to the generic caption category, each of these keys can be set on th
   margin-outside: 0
 |===
 
-. When nested inside the `image` key (i.e., `image-caption-align`), the value `inherit` is also accepted.
+1. When nested inside the `image` key (i.e., `image-caption-align`), the value `inherit` is also accepted.
 The value `inherit` resolves to the alignment of the block image.
 
 [#keys-code]
-=== Code
+=== Code Block
 
-The keys in this category are used to control the style of literal, listing and source blocks.
+The keys in this category are used to control the style of literal, listing, and source blocks and literal table cells.
 
 [cols="3,4,5l"]
 |===
@@ -2402,10 +2620,10 @@ The keys in this category are used to control the style of literal, listing and
   linenum-font-color: #ccc
 |===
 
-. The line-gap property is used to tune the height of the background color applied to a span of block text highlighted using Rouge.
-. The code-highlight category only applies when using Rouge as the source highlighter.
+1. The line-gap property is used to tune the height of the background color applied to a span of block text highlighted using Rouge.
+2. The code-highlight category only applies when using Rouge as the source highlighter.
 Otherwise, the styles are controlled by the source highlighter theme.
-. The code-linenum category only applies when using Pygments as the source highlighter.
+3. The code-linenum category only applies when using Pygments as the source highlighter.
 Otherwise, the styles are controlled by the source highlighter theme.
 
 [#keys-callout-numbers]
@@ -2455,18 +2673,19 @@ The keys in this category are used to control the style of callout numbers (i.e.
 |conum:
   line-height: 4 / 3
 
-|glyphs^[2]^
+|glyphs^[3]^
 |circled {vbar} filled {vbar} Unicode String ranges +
 (default: circled)
 |conum:
   glyphs: \u0031-\u0039
 |===
 
-. Currently, the font must contain the circle numbers starting at glyph U+2460.
-. font-family, font-kerning, font-size, font-style, and line-height are only used for markers in a colist.
+1. Currently, the font must contain the circle numbers starting at glyph U+2460.
+2. font-family, font-kerning, font-size, font-style, and line-height are only used for markers in a colist.
 These properties are inherited for conums inside a verbatim block.
-. The font must provide the required glyphs.
+3. The font must provide the required glyphs.
 The glyphs can be specified as a comma-separated list of ranges, where the range values are Unicode numbers (e.g., \u2460).
+Unicode escape sequences are recognized even if the value is not enclosed in double quotes.
 
 [#keys-button]
 === Button
@@ -2540,92 +2759,94 @@ The keys in this category apply to a button reference (generated from the inline
   font-style: normal
 |===
 
-. The border is only used if a border color is specified and the border width is not explicitly set to 0.
-. The border offset is the amount that the background and border swells around the text.
+1. The border is only used if a border color is specified and the border width is not explicitly set to 0.
+2. The border offset is the amount that the background and border swells around the text.
 It does not affect the distance between the formatted phrase and the phrases that surround it.
-. The character sequence `%s` in the content key gets replaced with the button label.
+3. The character sequence `%s` in the content key gets replaced with the button label.
 
-[#keys-key]
-=== Key
+[#keys-kbd]
+=== Kbd (Keyboard Input)
 
-The keys in this category apply to a key reference (generated from the inline kbd macro).
+The keys in this category apply to a kbd reference (generated from the inline kbd macro).
+The kbd reference is a span of text denoting textual user input from a keyboard, voice input, or other text entry device. 
 
 [cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-3+|[#key-prefix-key]*Key Prefix:* <<key-prefix-key,key>>
+3+|[#key-prefix-kbd]*Key Prefix:* <<key-prefix-kbd,kbd>>
 
 |background-color
 |<<colors,Color>> +
 (default: _not set_)
-|key:
+|kbd:
   background-color: #fafafa
 
 |border-color^[1]^
 |<<colors,Color>> +
 (default: _not set_)
-|key:
+|kbd:
   border-color: #cccccc
 
 |border-offset^[2]^
 |<<values,Number>> +
 (default: 0)
-|key:
+|kbd:
   border-offset: 1.5
 
 |border-radius
 |<<values,Number>> +
 (default: 0)
-|key:
+|kbd:
   border-radius: 2
 
 |border-width
 |<<values,Number>> +
 (default: $base-border-width)
-|key:
+|kbd:
   border-width: 0.375
 
 |separator^[3]^
 |<<quoted-string,Quoted string>> +
 (default: "+")
-|key:
+|kbd:
   separator: "\u2009+\u2009"
 
 |font-color
 |<<colors,Color>> +
 (default: _inherit_)
-|key:
+|kbd:
   font-color: #000
 
 |font-family
 |<<fonts,Font family name>> +
 (default: Courier)
-|key:
+|kbd:
   font-family: $base-font-family
 
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
-|key:
+|kbd:
   font-size: 10.5
 
 |font-style
 |<<font-styles,Font style>> +
 (default: italic)
-|key:
+|kbd:
   font-style: normal
 |===
 
-. The border is only used if a border color is specified and the border width is not explicitly set to 0.
-. The border offset is the amount that the background and border swells around the text.
+1. The border is only used if a border color is specified and the border width is not explicitly set to 0.
+2. The border offset is the amount that the background and border swells around the text.
 It does not affect the distance between the formatted phrase and the phrases that surround it.
-. The separator is only used for multi-key sequences.
+3. The separator is only used for multi-key input sequences.
 
 [#keys-menu]
 === Menu
 
 The keys in this category apply to the menu label (generated from the inline menu macro).
+Keep in mind that the styles for the caret can be controlled independently using the `<font>` tag.
 
 [cols="3,4,5l"]
 |===
@@ -2638,6 +2859,66 @@ The keys in this category apply to the menu label (generated from the inline men
 (default: " \u203a ")
 |menu:
   caret-content: ' > '
+
+|font-color
+|<<colors,Color>> +
+(default: _inherit_)
+|menu:
+  font-color: #AA0000
+
+|font-family
+|<<fonts,Font family name>> +
+(default: _inherit_)
+|menu:
+  font-family: M+ 1mn
+
+|font-size
+|<<values,Number>> +
+(default: _inherit_)
+|menu:
+  font-size: 8
+
+|font-style
+|<<font-styles,Font style>> +
+(default: bold)
+|menu:
+  font-style: bold_italic
+|===
+
+[#keys-mark]
+=== Mark
+
+The keys in this category apply to a mark phrase.
+
+[cols="3,4,5l"]
+|===
+|Key |Value Type |Example
+
+3+|[#key-prefix-mark]*Key Prefix:* <<key-prefix-mark,mark>>
+
+|font-color
+|<<colors,Color>> +
+(default: _inherit_)
+|mark:
+  font-color: #333333
+
+|font-style
+|<<font-styles,Font style>> +
+(default: _inherit_)
+|mark:
+  font-style: bold
+
+|background-color
+|<<colors,Color>> +
+(default: #ff0000)
+|mark:
+  background-color: #fcf8e3
+
+|border-offset
+|<<values,Number>> +
+(default: 1)
+|mark:
+  border-offset: 2
 |===
 
 [#keys-blockquote]
@@ -2762,7 +3043,7 @@ The keys in this category control the arrangement and style of quote blocks.
     text-transform: uppercase
 |===
 
-. If border-left-width is non-zero, the border is only applied to the left side.
+1. If border-left-width is non-zero, the border is only applied to the left side.
 Otherwise, if border-width is non-zero, the border is drawn around the whole block.
 
 [#keys-verse]
@@ -2806,7 +3087,7 @@ The keys in this category control the arrangement and style of verse blocks.
 |verse:
   font-color: #333333
 
-|font-family
+|font-family^[2]^
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |verse:
@@ -2887,8 +3168,10 @@ The keys in this category control the arrangement and style of verse blocks.
     text-transform: uppercase
 |===
 
-. If border-left-width is non-zero, the border is only applied to the left side.
+1. If border-left-width is non-zero, the border is only applied to the left side.
 Otherwise, if border-width is non-zero, the border is drawn around the whole block.
+2. The verse block does not use a fixed-width font by default, which can affect the layout if the content relies on columns.
+You can change verse blocks to use a fixed-width font (not necessarily a monospaced font) using this setting.
 
 [#keys-sidebar]
 === Sidebar
@@ -3188,7 +3471,8 @@ The keys in this category control the arrangement and style of admonition blocks
 |<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
 (default: $admonition-padding)
 |admonition:
-  padding: [0, 12, 0, 12]
+  label:
+    padding: [0, 12, 0, 12]
 
 |vertical-align
 |top {vbar} middle {vbar} bottom +
@@ -3268,12 +3552,12 @@ The keys in this category control the arrangement and style of admonition blocks
       size: 24
 |===
 
-. The top and bottom padding values are ignored on admonition-label-padding.
-. `<name>` can be `note`, `tip`, `warning`, `important`, or `caution`.
+1. The top and bottom padding values are ignored on admonition-label-padding.
+2. `<name>` can be `note`, `tip`, `warning`, `important`, or `caution`.
 All icon types must be grouped under a single `icons` category.
 In other words, _do not_ declare the `icons` category multiple times.
 The subkeys in the icon category cannot be flattened (e.g., `tip-name: far-lightbulb` is not valid syntax).
-. Required.
+3. Required.
 See the `.yml` files in the https://github.com/jessedoyle/prawn-icon/tree/master/data/fonts[prawn-icon repository] for a list of valid icon names.
 The prefix (e.g., `fas-`) determines which font set to use.
 If the prefix is not specified, `fa-` is assumed.
@@ -3369,6 +3653,8 @@ The keys in this category control the arrangement of block images.
   alt:
     font-style: italic
 
+3+|[#key-prefix-image-caption]*Key Prefix:* <<key-prefix-image-caption,image-caption>>
+
 |caption-align
 |<<text-alignments,Text alignment>> {vbar} inherit +
 (default: $caption-align)
@@ -3376,22 +3662,29 @@ The keys in this category control the arrangement of block images.
   caption:
     align: inherit
 
+|caption-text-align
+|<<text-alignments,Text alignment>> {vbar} inherit +
+(default: $image-caption-align)
+|image:
+  caption:
+    text-align: left
+
 |caption-max-width^[5]^
-|fit-content {vbar} none {vbar} <<measurement-units,Measurement>> +
+|fit-content {vbar} fit-content(percentage) {vbar} none {vbar} <<measurement-units,Measurement>> +
 (default: none)
 |image:
   caption:
     max-width: fit-content
 |===
 
-. Only applies to block images that don't have either a `pdfwidth` or `scaledwidth` attribute on the image macro.
+1. Only applies to block images that don't have either a `pdfwidth` or `scaledwidth` attribute on the image macro.
 If specified, this value takes precedence over the value of the `width` attribute on the image macro, but not over the value of the `pdfwidth` or `scaledwidth` attributes.
 This key accepts the same values as the `pdfwidth` attribute.
-. The border is only used if a border color is specified, the border width is specified, the border width is greater than 0, and the `noborder` role is not present.
+2. The border is only used if a border color is specified, the border width is specified, the border width is greater than 0, and the `noborder` role is not present.
 The border is drawn above the image on the inside of the box reserved for the image.
-. The value `auto` means the border should expand to fit the width of the container (i.e., full width) instead of the image.
-. Use the placeholders `%\{alt}`, `%\{target}`, `%\{link}`, and `%{/link}` to insert the alt text, image target, and link open/close tags into the content template.
-. In order for the image to be sized correctly when max-width is fit-content, a width should always be specified on the image.
+3. The value `auto` means the border should expand to fit the width of the container (i.e., full width) instead of the image.
+4. Use the placeholders `%\{alt}`, `%\{target}`, `%\{link}`, and `%{/link}` to insert the alt text, image target, and link open/close tags into the content template.
+5. In order for the image to be sized correctly when max-width is fit-content, a width should always be specified on the image.
 
 [#keys-svg]
 === SVG
@@ -3411,61 +3704,7 @@ The keys in this category control the SVG integration.
   fallback_font_family: Times-Roman
 |===
 
-. The fallback font family is only used when the font family in the SVG does not map to a known font name from the font catalog.
-
-[#keys-lead]
-=== Lead
-
-The keys in this category control the styling of lead paragraphs.
-
-[cols="3,4,5l"]
-|===
-|Key |Value Type |Example
-
-3+|[#key-prefix-lead]*Key Prefix:* <<key-prefix-lead,lead>>
-
-|font-color
-|<<colors,Color>> +
-(default: _inherit_)
-|lead:
-  font-color: #262626
-
-|font-family
-|<<fonts,Font family name>> +
-(default: _inherit_)
-|lead:
-  font-family: M+ 1p
-
-|font-kerning
-|normal {vbar} none +
-(default: _inherit_)
-|lead:
-  font-kerning: none
-
-|font-size
-|<<values,Number>> +
-(default: 13.5)
-|lead:
-  font-size: 13
-
-|font-style
-|<<font-styles,Font style>> +
-(default: _inherit_)
-|lead:
-  font-style: bold
-
-|text-transform
-|<<text-transforms,Text transform>> +
-(default: _inherit_)
-|lead:
-  text-transform: uppercase
-
-|line-height
-|<<values,Number>> +
-(default: 1.4)
-|lead:
-  line-height: 1.4
-|===
+1. The fallback font family is only used when the font family in the SVG does not map to a known font name from the font catalog.
 
 [#keys-abstract]
 === Abstract
@@ -3619,7 +3858,7 @@ The keys in this category control the style of thematic breaks (aka horizontal r
 
 |margin-bottom
 |<<measurement-units,Measurement>> +
-(default: $vertical-spacing)
+(default: 12)
 |thematic-break:
   margin-bottom: 18
 |===
@@ -3635,9 +3874,8 @@ Asciidoctor PDF supports unordered and ordered description lists.
 These are defined as a description list, but get displayed as an unordered or ordered description list with the term as a subject.
 Only one term is supported.
 The subject is shown using the term font style (bold by default).
-The subject is stacked above the description if the "stack" role is present.
-Otherwise, the subject is arranged as a run-in followed by a subject stop (`:` by default).
-The subject stop can be customized using the `subject-stop` attribute.
+
+By default, the subject is arranged as a run-in followed by a subject stop (`:` by default).
 
 [source,asciidoc]
 ----
@@ -3645,6 +3883,25 @@ The subject stop can be customized using the `subject-stop` attribute.
 alpha:: partially complete and unstable
 beta:: feature complete and undergoing testing
 ----
+
+The subject stop can be customized using the `subject-stop` attribute.
+
+[source,asciidoc]
+----
+[unordered,subject-stop=)]
+alpha:: partially complete and unstable
+beta:: feature complete and undergoing testing
+----
+
+If the `stack` role is present, the subject is stacked above the description.
+In this case, the subject stop is only used if specified explicitly.
+
+[source,asciidoc]
+----
+[unordered.stack]
+alpha:: partially complete and unstable
+beta:: feature complete and undergoing testing
+----
 ====
 
 [cols="3,4,5l"]
@@ -3708,44 +3965,44 @@ beta:: feature complete and undergoing testing
   description-indent: 15
 |===
 
-[#keys-outline-list]
-=== Outline List
+[#keys-list]
+=== List
 
-The keys in this category control the arrangement and style of outline list items.
+The keys in this category control the arrangement and style of regular (ordered and unordered) lists.
 
 [cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-3+|[#key-prefix-outline-list]*Key Prefix:* <<key-prefix-outline-list,outline-list>>
+3+|[#key-prefix-list]*Key Prefix:* <<key-prefix-list,list>>
 
 |indent
 |<<measurement-units,Measurement>> +
 (default: 30)
-|outline-list:
+|list:
   indent: 40
 
 |item-spacing
 |<<measurement-units,Measurement>> +
 (default: 6)
-|outline-list:
+|list:
   item-spacing: 4
 
 |marker-font-color^[1]^
 |<<colors,Color>> +
 (default: _inherit_)
-|outline-list:
+|list:
   marker-font-color: #3c763d
 
 |text-align^[2]^
 |<<text-alignments,Text alignment>> +
 (default: $base-align)
-|outline-list:
+|list:
   text-align: left
 |===
 
-. Controls the color of the bullet glyph that marks items in unordered lists and the number for items in ordered lists.
-. Controls the alignment of the list text only, not nested content (blocks or lists).
+1. Controls the color of the bullet glyph that marks items in unordered lists and the number for items in ordered lists.
+2. Controls the alignment of the list text only, not nested content (blocks or lists).
 
 [#keys-ulist]
 === Unordered List
@@ -3774,7 +4031,7 @@ The keys in this category control the arrangement and style of unordered list it
 
 |font-color
 |<<colors,Color>> +
-(default: $outline-list-marker-font-color)
+(default: $list-marker-font-color)
 |ulist:
   marker:
     font-color: #cccccc
@@ -3833,7 +4090,90 @@ The keys in this category control the arrangement and style of unordered list it
       line-height: 2
 |===
 
-. <type> is one of disc, square, circle, checked, unchecked
+1. <type> is one of disc, square, circle, checked, unchecked
+
+[#keys-callout-list]
+=== Callout List
+
+The keys in this category control the arrangement and style of callout lists (i.e., colists).
+
+NOTE: The <<keys-callout-numbers>> category controls the appearance of the list markers (i.e., conums) in a callout list.
+If you change the font-size setting on the callout list, then you likely need to change the font-size setting on the conum category as well.
+
+[cols="3,4,5a"]
+|===
+|Key |Value Type |Example
+
+3+|[#key-prefix-callout-list]*Key Prefix:* <<key-prefix-callout-list,callout-list>>
+
+|item-spacing
+|<<measurement-units,Measurement>> +
+(default: $list-item-spacing)
+|[source,yaml]
+callout-list:
+  item-spacing: 3
+
+|font-color
+|<<colors,Color>> +
+(default: _inherit_)
+|[source,yaml]
+callout-list:
+  font-color: #555555
+
+|font-family
+|<<fonts,Font family name>> +
+(default: _inherit_)
+|[source,yaml]
+callout-list:
+  font-family: M+ 1p
+
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|[source,yaml]
+callout-list:
+  font-kerning: none
+
+|font-size
+|<<values,Number>> +
+(default: _inherit_)
+|[source,yaml]
+callout-list:
+  font-size: 9
+
+|font-style
+|<<font-styles,Font style>> +
+(default: _inherit_)
+|[source,yaml]
+callout-list:
+  font-style: italic
+
+|text-transform
+|<<text-transforms,Text transform>> +
+(default: _inherit_)
+|[source,yaml]
+callout-list:
+  text-transform: lowercase
+
+|line-height
+|<<values,Number>> +
+(default: _inherit_)
+|[source,yaml]
+callout-list:
+  line-height: 1
+
+|text-align
+|<<text-alignments,Text alignment>> +
+(default: $list-text-align)
+|callout-list:
+  text-align: left
+
+|margin-top-after-code
+|<<measurement-units,Measurement>> +
+(default: -$block-margin-bottom)
+|callout-list:
+  margin-top-after-code: 0
+|===
 
 [#keys-table]
 === Table
@@ -3876,6 +4216,13 @@ The keys in this category control the arrangement and style of tables and table
 |table:
   caption-align: inherit
 
+|caption-text-align
+|<<text-alignments,Text alignment>> {vbar} inherit +
+(default: $table-caption-align)
+|table:
+  caption:
+    text-align: left
+
 |caption-side
 |top {vbar} bottom +
 (default: top)
@@ -3883,7 +4230,7 @@ The keys in this category control the arrangement and style of tables and table
   caption-side: bottom
 
 |caption-max-width
-|fit-content {vbar} none {vbar} <<measurement-units,Measurement>> +
+|fit-content {vbar} fit-content(percentage) {vbar} none {vbar} <<measurement-units,Measurement>> +
 (default: fit-content)
 |table:
   caption-max-width: none
@@ -3919,19 +4266,19 @@ The keys in this category control the arrangement and style of tables and table
   font-style: italic
 
 |grid-color
-|<<colors,Color>> +
+|<<colors,Color>> {vbar} <<colors,Color[x,y]>> +
 (default: $table-border-color)
 |table:
   grid-color: #eeeeee
 
 |grid-style
-|solid {vbar} dashed {vbar} dotted +
+|solid {vbar} dashed {vbar} dotted {vbar} Style[x,y] +
 (default: solid)
 |table:
   grid-style: dashed
 
 |grid-width
-|<<values,Number>> +
+|<<values,Number>> {vbar} <<values,Number[x,y]>> +
 (default: $table-border-width)
 |table:
   grid-width: 0.5
@@ -4008,6 +4355,13 @@ The keys in this category control the arrangement and style of tables and table
   head:
     font-style: normal
 
+|line-height
+|<<values,Number>> +
+(default: _inherit_)
+|table:
+  head:
+    line-height: 1.15
+
 |text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
@@ -4070,6 +4424,13 @@ The keys in this category control the arrangement and style of tables and table
 
 3+|[#key-prefix-table-cell]*Key Prefix:* <<key-prefix-table-cell,table-cell>>
 
+|line-height
+|<<values,Number>> +
+(default: _inherit_)
+|table:
+  cell:
+    line-height: 1.5
+
 |padding
 |<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
 (default: 2)
@@ -4077,6 +4438,15 @@ The keys in this category control the arrangement and style of tables and table
   cell:
     padding: 3
 
+3+|[#key-prefix-table-asciidoc-cell]*Key Prefix:* <<key-prefix-table-asciidoc-cell,table-asciidoc-cell>>
+
+|style
+|inherit {vbar} initial
+(default: inherit)
+|table:
+  asciidoc-cell:
+    style: initial
+
 3+|[#key-prefix-table-header-cell]*Key Prefix:* <<key-prefix-table-header-cell,table-header-cell>>
 
 //|align
@@ -4129,12 +4499,30 @@ The keys in this category control the arrangement and style of tables and table
     text-transform: uppercase
 |===
 
-. This key only controls the color that is used for stripes.
+1. This key only controls the color that is used for stripes.
 The appearance of stripes is controlled using the `stripes` table attribute, the `table-stripes` document attribute (since Asciidoctor 2), or the `stripes` document attribute (prior to Asciidoctor 2).
 Permitted attribute values are even, odd, all, and none.
 Prior to Asciidoctor 2, even rows are shaded by default (e.g., `stripes=even`).
 Since Asciidoctor 2, table stripes are not enabled by default (e.g., `stripes=none`).
 
+[#keys-index]
+=== Index
+
+The keys in this category control the style of the autogenerated index section.
+
+[cols="3,4,5l"]
+|===
+|Key |Value Type |Example
+
+3+|[#key-prefix-index]*Key Prefix:* <<key-prefix-index,index>>
+
+|columns
+|Integer +
+(default: 2)
+|index:
+  columns: 2
+|===
+
 [#keys-footnotes]
 === Footnotes
 
@@ -4241,7 +4629,7 @@ The keys in this category control the arrangement and style of the table of cont
 
 |text-decoration-width
 |<<values,Number>> +
-(default: 1)
+(default: $base-text-decoration-width)
 |toc:
   text-decoration-width: 0.5
 
@@ -4395,9 +4783,9 @@ The keys in this category control the arrangement and style of the table of cont
     levels: 2 3
 |===
 
-. `<n>` is a number ranging from 1 to 6, representing each of the six heading levels.
-. The dot leader inherits all font properties except `font-style` from the root `toc` category.
-. 0-based levels (e.g., part = 0, chapter = 1).
+1. `<n>` is a number ranging from 1 to 6, representing each of the six heading levels.
+2. The dot leader inherits all font properties except `font-style` from the root `toc` category.
+3. 0-based levels (e.g., part = 0, chapter = 1).
 Dot leaders are only shown for the specified levels.
 If value is not specified, dot leaders are shown for all levels.
 
@@ -4407,7 +4795,7 @@ If value is not specified, dot leaders are shown for all levels.
 The keys in this category control the arrangement and style of running header and footer content.
 Please note that the running content will _not_ be used unless a) the periphery (header or footer) is configured and b) the height key for the periphery is assigned a value.
 
-CAUTION: If the height of the running content periphery is larger than the page margin, the running content will cover the main content.
+CAUTION: If the height of the running content periphery is taller than the page margin, the running content will cover the main content.
 To avoid this problem, reduce the height of the running content periphery or make the page margin on that side larger.
 
 [cols="3,4,5l"]
@@ -4446,6 +4834,30 @@ To avoid this problem, reduce the height of the running content periphery or mak
 |header:
   border-width: 0.25
 
+|column-rule-color
+|<<colors,Color>> +
+(default: _not set_)
+|header:
+  column-rule-color: #CCCCCC
+
+|column-rule-spacing
+|<<measurement-units,Measurement>> +
+(default: 0)
+|header:
+  column-rule-spacing: 5
+
+|column-rule-style
+|solid {vbar} double {vbar} dashed {vbar} dotted +
+(default: solid)
+|header:
+  column-rule-style: dashed
+
+|column-rule-width
+|<<measurement-units,Measurement>> +
+(default: _not set_)
+|header:
+  column-rule-width: 0.25
+
 |font-color
 |<<colors,Color>> +
 (default: _inherit_)
@@ -4488,6 +4900,18 @@ To avoid this problem, reduce the height of the running content periphery or mak
 |header:
   line-height: 1.2
 
+|margin
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom (n/a),left]>> +
+(default: [0, inherit])
+|header:
+  margin: 0
+
+|content-margin
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
+(default: [0, inherit])
+|header:
+  content-margin: 0
+
 |padding^[3]^
 |<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
 (default: 0)
@@ -4531,6 +4955,27 @@ To avoid this problem, reduce the height of the running content periphery or mak
   recto:
     columns: <25% =50% >25%
 
+|<side>-margin^[5]^
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom (n/a),left]>> +
+(default: _inherit_)
+|header:
+  recto:
+    margin: [0, 0, 0, inherit]
+
+|<side>-content-margin^[5]^
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
+(default: _inherit_)
+|header:
+  recto:
+    content-margin: [0, 0, 0, inherit]
+
+|<side>-padding^[5]^
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
+(default: _inherit_)
+|header:
+  recto:
+    padding: [0, 3, 0, 3]
+
 |<side>-<position>-content^[5,6]^
 |<<quoted-string,Quoted string>> +
 (default: '\{page-number}')
@@ -4571,6 +5016,30 @@ To avoid this problem, reduce the height of the running content periphery or mak
 |footer:
   border-width: 0.25
 
+|column-rule-color
+|<<colors,Color>> +
+(default: _not set_)
+|footer:
+  column-rule-color: #CCCCCC
+
+|column-rule-spacing
+|<<measurement-units,Measurement>> +
+(default: 0)
+|footer:
+  column-rule-spacing: 5
+
+|column-rule-style
+|solid {vbar} double {vbar} dashed {vbar} dotted +
+(default: solid)
+|footer:
+  column-rule-style: dashed
+
+|column-rule-width
+|<<measurement-units,Measurement>> +
+(default: _not set_)
+|footer:
+  column-rule-width: 0.25
+
 |font-color
 |<<colors,Color>> +
 (default: _inherit_)
@@ -4613,6 +5082,18 @@ To avoid this problem, reduce the height of the running content periphery or mak
 |footer:
   line-height: 1.2
 
+|margin
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top (n/a),right,bottom,left]>> +
+(default: [0, inherit])
+|footer:
+  margin: 0
+
+|content-margin
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
+(default: [0, inherit])
+|footer:
+  content-margin: 0
+
 |padding^[3]^
 |<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
 (default: 0)
@@ -4656,6 +5137,27 @@ To avoid this problem, reduce the height of the running content periphery or mak
   verso:
     columns: <50% =0% <50%
 
+|<side>-margin^[5]^
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top (n/a),right,bottom,left]>> +
+(default: [0, inherit])
+|footer:
+  verso:
+    margin: [0, inherit, 0, 0]
+
+|<side>-content-margin^[5]^
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
+(default: _inherit_)
+|footer:
+  verso:
+    content-margin: [0, inherit, 0, 0]
+
+|<side>-padding^[5]^
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
+(default: _inherit_)
+|footer:
+  verso:
+    padding: [0, 3, 0, 3]
+
 |<side>-<position>-content^[5,6]^
 |<<quoted-string,Quoted string>> +
 (default: '\{page-number}')
@@ -4667,23 +5169,27 @@ To avoid this problem, reduce the height of the running content periphery or mak
 3+|[#key-prefix-running-content]*Key Prefix:* <<key-prefix-running-content,running-content>>
 
 |start-at^[7]^
-|title {vbar} toc {vbar} body {vbar} Integer +
+|title {vbar} toc {vbar} after-toc {vbar} body {vbar} Integer +
 (default: body)
 |running-content:
   start-at: toc
 |===
 
-. The background color spans the width of the page, as does the border when a background color is specified.
-. *If the height is not set, the running content at this periphery is disabled.*
-. If the side padding is negative, the content will bleed into the margin of the page.
-. The maximum section level considered when assigning the implicit `section-title` attribute (and related) available to the running content.
-. `<side>` can be `recto` (right-hand, odd-numbered pages) or `verso` (left-hand, even-numbered pages).
+1. To make the background color and border span the width of the page, set the margin to 0 (and adjust the content-margin accordingly).
+2. *If the height is not set, the running content at this periphery is disabled.*
+3. Do not use negative margins.
+Instead, adjust the values of the margin and content-margin keys.
+4. The maximum section level considered when assigning the implicit `section-title` attribute (and related) available to the running content.
+5. `<side>` can be `recto` (right-hand, odd-numbered pages) or `verso` (left-hand, even-numbered pages).
 The `columns` key can also be defined one level up (on `header` or `footer`), in which case the setting will be inherited.
 Where the page sides fall in relation to the physical or printed page number is controlled using the `pdf-folio-placement` attribute (except when `media=prepress`, which implies `physical`).
-. `<position>` can be `left`, `center` or `right`.
-. Only works if the document uses a title page (i.e., doctype is book or `title-page` attribute is set)
+The column rules are only added if the `columns` key is specified.
+6. `<position>` can be `left`, `center` or `right`.
+7. The `title`, `toc`, and `after-toc` values are only recognized if the title page is enabled (i.e., doctype is book or `title-page` attribute is set)
 The `toc` value only applies if the toc is in the default location (before the first page of the body).
-If the toc macro is used to position the toc, the start-at behavior is the same as if the toc is not enabled.
+If value is `toc`, and the toc macro is used to position the toc, the start-at behavior is the same as if the toc is not enabled.
+If value is `after-toc`, the running content will start after the toc, no matter where it's placed in the document.
+To disable the running content on toc pages inserted by the toc macro, set the noheader and/or nofooter options on the macro (e.g., `toc::[opts=nofooter]`).
 If value is an integer, the running content will start at the specified page of the body (i.e., 1 is first page, 2 is second page, etc.)
 
 IMPORTANT: If you don't specify a height for either the header or footer key, it effectively disables the content at that periphery.
@@ -4754,6 +5260,7 @@ In addition, the following attributes are also available when defining the conte
 
 * page-count
 * page-number (only set if the `pagenums` attribute is set on the document, which it is by default)
+* page-layout
 * document-title
 * document-subtitle
 * part-title
@@ -4782,6 +5289,7 @@ header:
     center:
       content: $header-recto-center-content
 footer:
+  background-image: image:running-content-bg-{page-layout}.svg[]
   height: 0.75in
   line-height: 1
   recto:
@@ -4856,18 +5364,18 @@ This is done using AsciiDoc attributes.
 
 There are three AsciiDoc attributes that tell Asciidoctor PDF how to locate and apply your theme.
 
-pdf-theme (or pdf-style):: The name of the YAML theme file to load.
+pdf-theme:: The name of the YAML theme file to load.
 If the name ends with `.yml`, it's assumed to be the complete name of a file and is resolved relative to `pdf-themesdir`, if specified, otherwise the current directory.
 Otherwise, `-theme.yml` is appended to the name to make the file name (i.e., `<name>-theme.yml`) and is resolved relative to `pdf-themesdir`, if specified, otherwise the built-in themes dir.
 
-pdf-themesdir (or pdf-stylesdir):: The directory where the theme file is located.
+pdf-themesdir:: The directory where the theme file is located.
 _Specifying an absolute path is recommended._
 +
 If you use images in your theme, image paths are resolved relative to this directory.
 If `pdf-theme` ends with `.yml`, and `pdf-themesdir` is not specified, then `pdf-themesdir` defaults to the directory of the path specified by `pdf-theme`.
 
 pdf-fontsdir:: The directory or directories where the fonts used by your theme, if any, are located.
-Multiple entries must be separated by a semi-colon.
+Multiple entries must be separated by either a comma or a semi-colon.
 To reference a file inside a JAR file on the classpath, prefix with the path with `uri:classloader:` (AsciidoctorJ only).
 _Specifying an absolute path is recommended._
 
@@ -4922,149 +5430,240 @@ This only works when running Asciidoctor PDF on the JVM.
 == Theme-Related Document Attributes
 
 There are various settings in the theme you control using document attributes.
-These settings override equivalent keys defined in the theme file, where applicable.
+If an attribute is marked as "Header Only", it only takes effect if defined in the AsciiDoc document header or via the API.
+If an attribute matches a key in the theme file, the attribute takes precedence.
 
-[cols="2,3,6l"]
+[cols="2,3,^1,6l"]
 |===
-|Attribute |Value Type |Example
+|Attribute |Value Type | Header Only |Example
 
 |autofit-option
 |flag (default: _not set_)
+|No
 |:autofit-option:
 
-|chapter-label
-|string (default: Chapter)
-|:chapter-label: Chapitre
-
 |<face>-cover-image^[1]^
 |path^[2]^ {vbar} image macro^[3]^ +
 (format can be image or PDF)
+|Yes
 |:front-cover-image: image:front-cover.pdf[]
 
 |hyphens^[7]^
 |language code {vbar} _blank_ to default to en_us (default: _not set_)
+|Yes
 |:hyphens: de
 
+|icons^[13]^
+|font {vbar} image (default: _not set_)
+|No
+|:icons: font
+
 |media
 |screen {vbar} print {vbar} prepress
+|Yes
 |:media: prepress
 
 |compress
 |flag (default: _not set_)
+|Yes
 |:compress:
 
 |optimize
 |screen {vbar} ebook {vbar} printer {vbar} prepress {vbar} default (default: default)
+|Yes
 |:optimize: prepress
 
-|outlinelevels^[10]^
+|outlinelevels^[12]^
 |Integer {vbar} Integer:Integer (default: same as _toclevels_)
+|Yes
 |:outlinelevels: 2
 
 |page-background-image^[4]^
 |path^[2]^ {vbar} image macro^[3]^
+|Yes
 |:page-background-image: image:bg.jpg[]
 
 |page-background-image-(recto{vbar}verso)^[4]^
 |path^[2]^ {vbar} image macro^[3]^
+|Yes
 |:page-background-image-recto: image:bg-recto.jpg[]
 
 |page-foreground-image
 |path^[2]^ {vbar} image macro^[3]^
+|Yes
 |:page-foreground-image: image:watermark.svg[]
 
 |pagenums^[5]^
 |flag (default: _set_)
+|Yes
 |:pagenums:
 
 |pdf-page-layout
 |portrait {vbar} landscape
+|Yes
 |:pdf-page-layout: landscape
 
 |pdf-page-margin
 |<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>>
+|Yes
 |:pdf-page-margin: [1in, 0.5in]
 
 |pdf-page-mode
 |outline {vbar} none {vbar} thumbs {vbar} fullscreen {vbar} fullscreen outline {vbar} fullscreen none {vbar} fullscreen thumbs (default: outline)
+|Yes
 |:pdf-page-mode: fullscreen none
 
 |pdf-page-size
 |https://github.com/prawnpdf/pdf-core/blob/0.6.0/lib/pdf/core/page_geometry.rb#L16-L68[Named size^] {vbar} <<measurement-units,Measurement[width, height]>>
+|Yes
 |:pdf-page-size: [6in, 9in]
 
 |pdf-folio-placement
 |virtual {vbar} virtual-inverted {vbar} physical {vbar} physical-inverted
+|Yes
 |:pdf-folio-placement: physical
 
 |pdf-version
 |1.3 {vbar} 1.4 {vbar} 1.5 {vbar} 1.6 {vbar} 1.7 (default: 1.4)
+|Yes
 |:pdf-version: 1.7
 
 |pdfmark^[6]^
 |flag (default: _not set_)
+|Yes
 |:pdfmark:
 
-|scripts^[7]^
+|scripts^[8]^
 |cjk (default: _not set_)
+|Yes
 |:scripts: cjk
 
-|text-align^[8]^
+|text-align^[9]^
 |<<text-alignments,Text alignment>>
+|Yes
 |:text-align: left
 
 |title-logo-image
 |path^[2]^ {vbar} image macro^[3]^
+|Yes
 |:title-logo-image: image:logo.png[top=25%, align=center, pdfwidth=0.5in]
 
-|title-page^[9]^
+|title-page^[10]^
 |flag (default: _not set_)
+|Yes
 |:title-page:
 
 |title-page-background-image
 |path^[2]^ {vbar} image macro^[3]^
+|Yes
 |:title-page-background-image: image:title-bg.jpg[]
 
-|toc-max-pagenum-digits^[10]^
+|toc-max-pagenum-digits^[11]^
 |Integer (default: 3)
+|Yes
 |:toc-max-pagenum-digits: 4
 |===
 
-. `<face>` can be `front` or `back`.
-. The path is resolved relative to base_dir.
-. The target of the image macro is resolved relative to `imagesdir`.
-If the image macro syntax is not used, the value is resolved relative to the base directory, which defaults to the document directory.
-. By default, page background images are automatically scaled to fit the bounds of the page (i.e., `fit=contain`) and centered (i.e., `position=center`).
+1. `<face>` can be `front` or `back`.
+2. A bare path is resolved relative to base_dir, which defaults to the document directory.
+3. The target of the image macro is resolved relative to `imagesdir` since it's defined in the AsciiDoc document (unlike in the theme, where it is resolved relative to the value of `pdf-themesdir`).
+4. By default, page background images are automatically scaled to fit the bounds of the page (i.e., `fit=contain`) and centered (i.e., `position=center`).
 The size of the background image can be controlled using any of the sizing attributes on the image macro (i.e., fit, pdfwidth, scaledwidth, or width) when `fit=none`.
 The position of the background image can be controlled using the `position` attribute.
 If the recto (right-hand, odd-numbered pages) or verso (left-hand, even-numbered pages) background is specified, it will be used only for that side.
 If a background image isn't specified for a side, the converter will use the default page background image (`page-background-image`), if specified.
 To disable the background image for a side, use the value `none`.
-. Controls whether the implicit `page-number` attribute is to the running header and footer content specified in the theme file.
+5. Controls whether the implicit `page-number` attribute is to the running header and footer content specified in the theme file.
 Instead of disabling page numbers, you can use the `noheader` and `nofooter` attributes to disable the running header and footer, respectively.
-. Enables generation of the http://milan.kupcevic.net/ghostscript-ps-pdf/#marks[pdfmark] file, which contains metadata that is fed to Ghostscript when optimizing the PDF file.
-. Activates line break rules for CJK languages (specifically Chinese and Japanese).
+6. Enables generation of the http://milan.kupcevic.net/ghostscript-ps-pdf/#marks[pdfmark] file, which contains metadata that can be fed to Ghostscript when optimizing the PDF file.
+If you're using Ghostscript >= 8.54, this feature is not needed.
+7. Activates hyphenation for the language code specified (defaults to en_us).
+8. Activates line break rules for CJK languages (specifically Chinese and Japanese).
 Chinese and Japanese are written without spaces (and may not use spaces when mixing with English words either).
 This setting allows a line break to be placed between any two CJK characters to accommodate wrapping.
 These languages also use different punctuation for pause, full stop, and dash, which are taken into account when breaking lines.
-. _(Experimental)_ The `text-align` document attribute is intended as a simple way to toggle text justification.
+9. _(Experimental)_ The `text-align` document attribute is intended as a simple way to toggle text justification.
 The value of this attribute overrides the `base-align` key set by the theme.
 For more fine-grained control, you should customize using the theme.
-. The title page is only enabled by default for the book doctype.
+10. The title page is only enabled by default for the book doctype.
 To force the title page to be used for other doctypes, set the `title-page` attribute in the document header.
-. If the TOC overlaps the first page of content, increase this number.
-. The second number in the value of `outlinelevels` is the number of levels of the outline to expand (e.g., `3:1`).
+11. If the TOC overlaps the first page of content, increase this number.
+12. The second number in the value of `outlinelevels` is the number of levels of the outline to expand (e.g., `3:1`).
 If the second number is not present, all levels are expanded.
+13. By default, admonitions have a text-based label that matches the admonition type.
+To use icons instead, set the `icons` attribute to `font`.
+This setting allows the theme to control the icon used for each type (see the <<key-prefix-admonition-icon,admonition-icon key>>).
+It also enables the `icon` macro (covered in the README).
+To use local image filees, set the `icons` attribute to `image`.
+Note that if the value of the `icons` attribute is `image`, the `icon` macro will produce text-based output.
+
+== Page Numbering
+
+The converter automatically keeps track of page numbers.
+These page numbers are available as metadata and determine folio placement (recto/verso pages).
+
+By default, the converter assigns the page number 1 to the first body page of the document.
+It then increments the page number for each page thereafter.
+All front matter pages that precede the first body page in the book doctype (or when the `title-page` attribute is set) (e.g., cover page, title page, and toc pages) are numbered using roman numerals (e.g., i, ii, iii, etc).
+Since these computed page numbers can differ from the physical page numbers, we refer to them as [.term]_virtual page numbers_.
+
+By default, the folio placement is derived from the virtual page number.
+Odd page numbers (e.g., 1, 3, 5, ...) designate recto pages and even page numbers (e.g., 2, 4, 6, ...) designate verso pages.
+
+It's possible to influence the virtual page numbering using a combination of the theme and document attributes.
+One such customization is to control where the transition from roman numerals to integers occurs.
+
+The theme can specify the page where the integer (1-based) page numbering should begin using the `page-numbering-start-at` key.
+For instance, the theme can specify `page-numbering-start-at: title`, which will make the integer page numbering start at the title page when enabled (i.e., the title page will be assigned the virtual page number 1).
+Alternately, the theme can specify an offset from the first body page where the page numbering should begin (all doctypes).
+For instance, `page-numbering-start-at: 2` tells the converter to assign the virtual page number 1 to the second page of the body.
+Any page that precedes that page will be numbered using roman numerals.
+
+Changing the page on which the integer page numbering begins can alter to folio placement.
+To correct for this, or to change the folio placement in general, you can use the `pdf-folio-placement` document attribute.
+For instance, to base the folio placement on physical page numbers, set the value of this attribute to `physical` (e.g., `pdf-folio-placement=physical`).
+To invert the recto and verso pages, add the `-inverted` qualifier to the value (e.g., `pdf-folio-placement=physical-inverted`).
+
+The default theme shows the virtual page number in the footer of all body pages.
+If you're starting with a blank theme, you can add the page number by using the `\{page-number}` attribute reference in the `content` key of the running content (header or footer).
+For example:
+
+[source,yaml]
+----
+footer:
+  recto:
+    right:
+      content: '\{page-number}'
+----
+
+If you want the running content to also appear on front matter pages, you can use the theme to change the page on which the running content starts with the `running-content-start-at` key.
+For instance, to start the running content on the title page, assuming the title page is enabled, set `running-content-start-at: title` in your theme file.
+
+Aside from the configurability mentioned, the page numbering logic is computed automatically.
+
+[#print]
+== Printing Mode (print)
+
+Asciidoctor PDF provides the following behaviors to assist with printing:
 
-== Publishing Mode
+* Shows the URL for links (unless the linked text matches the URL)
+* Consolidates page ranges in the index
+* Disables links from page numbers in index to location of term in document
 
-Asciidoctor PDF provides the following features to assist with publishing:
+You activate these printing features by setting the `media` attribute to `print` in the header of your AsciiDoc document (e.g., `:media: print`) or from the API or CLI (e.g., `-a media=print`).
+You may also want to consider using the print-optimized theme, which uses darker, grayscale colors for text and borders (e.g., `-a pdf-theme=default-for-print`).
+
+[#prepress]
+== Publishing Mode (prepress)
+
+In addition to the <<print,printing mode behaviors>>, Asciidoctor PDF provides the following behaviors to assist with publishing:
 
 * Double-sided (mirror) page margins
 * Automatic facing pages
 
-These features are activated when you set the `media` attribute to `prepress` in the header of your AsciiDoc document or from the CLI or API.
+You activate these publishing (aka prepress) features by setting the `media` attribute to `prepress` in the header of your AsciiDoc document (e.g., `:media: prepress`) or from the API or CLI (e.g., `-a media=prepress`).
 The following sections describe the behaviors that this setting activates.
+You may also want to consider using the print-optimized theme, which uses darker, grayscale colors for text and borders (e.g., `-a pdf-theme=default-for-print`).
 
 === Double-Sided Page Margins
 
@@ -5089,7 +5688,7 @@ The page margins alternate between recto and verso.
 The first page in the document (after the cover) is a recto page.
 
 If no cover is specified, the recto margin is not applied to the title page.
-To apply the recto margin to the title page, but not include a cover, assign the value `~` to the `front-cover-image` attribute.
+To apply the recto margin to the title page, but not include a cover, assign the value `~` to the `front-cover-image` and `back-cover-image` attributes.
 
 === Automatic Facing Pages
 
@@ -5122,8 +5721,31 @@ You can check on the status of this defect by following https://github.com/ascii
 
 == Source Highlighting Theme
 
-You can define and apply your own source highlighting theme to source blocks when using Rouge as the source highlighter.
-This section explains how.
+When using Rouge as the source highlighter, you can apply a bundled theme (aka style) to your source blocks or define and apply your own.
+
+=== Using a Highlighting Theme
+
+Rouge bundles several themes you can use to colorize your source blocks.
+To use one of these themes, first set the value of the `source-highlighter` document attribute to `rouge`.
+Then, specify the desired theme using the `rouge-style` document attribute.
+
+The following example demonstrates how to apply the monokai theme from Rouge to source blocks.
+
+[source,asciidoc]
+----
+:source-highlighter: rouge
+:rouge-style: monokai
+----
+
+You can generate a list of all available themes by running the following command:
+
+ $ ruby -e 'require :rouge.to_s; puts Rouge::Theme.registry.keys.sort.join ?\n'
+
+You can also find the list of themes in the Rouge source repository at https://github.com/rouge-ruby/rouge/tree/master/lib/rouge/themes.
+
+If the bundled themes don't suit your needs, you can define one of your own.
+
+=== Custom Highlighting Theme
 
 A custom theme for Rouge is defined using a Ruby class.
 Start by creating a Ruby source file to define your theme.
@@ -5306,8 +5928,8 @@ Let's customize the part title page by making the background orange, making the
 The method `typeset_text` and `calc_line_metrics` are provided by Asciidoctor PDF to make writing text easier.
 If you wanted, you could just use the low-level `text` method provided by Prawn.
 
-To find all the available methods to override, consult the https://www.rubydoc.info/github/asciidoctor/asciidoctor-pdf/Asciidoctor/Pdf/Converter[API docs].
-For deeper examples of how to override the behavior of the converter, refer to the extended converter in the https://github.com/mraible/infoq-mini-book/blob/master/src/main/ruby/asciidoctor-pdf-extensions.rb[InfoQ Mini-Book template].
+To find all the available methods to override, consult the https://www.rubydoc.info/github/asciidoctor/asciidoctor-pdf/Asciidoctor/PDF/Converter[API docs].
+For deeper examples of how to override the behavior of the converter, refer to the extended converter in the https://github.com/mraible/infoq-mini-book/blob/main/src/main/ruby/asciidoctor-pdf-extensions.rb[InfoQ Mini-Book template].
 
 Now that you've seen some examples of how to extend the converter, let's look at how to use it.
 
@@ -5323,14 +5945,15 @@ Now you're hacking the typesetting!
 [appendix]
 == Preparing a Custom Font
 
-Any TTF font can be used with Prawn--and hence Asciidoctor PDF--without modifications (unless, of course, it's corrupt or contains errors).
+Any TTF or OTF font can be used with Prawn--and hence Asciidoctor PDF--without modifications (unless, of course, it's corrupt or contains errors).
 However, you may discover that kerning is disabled and certain required glyphs are missing (or replaced with boxes).
 To address these problems, you need to prepare the font using a font program such as {url-fontforge}[FontForge].
+These instructions will cover how to prepare a TTF font, but the same applies for an OTF font.
 
 === Validate the Font
 
 Before using the font, you may want to check that the font is valid.
-To do so, create the following script, which will verify that the TTF font is free from errors.
+To do so, create the following script, which will verify that the font is free from errors.
 
 .validate-font.rb
 [source,ruby]
@@ -5363,7 +5986,7 @@ You can find a crash course in how to use the program on the FontForge project s
 
 Here are the modifications you need to apply to a custom font for it to work best with Asciidoctor PDF:
 
-* Convert the font to TTF (only required if the font is not already a TTF, such as an OTF or TTC).
+* Convert the font to TTF or OTF (only required if the font is a TTC or other format not supported by Prawn).
 * Add the glyphs for the required characters if missing from the font (optional if using a fallback font).
 * Subset the font to exclude unused characters to reduce the file size (optional).
 * Save the file using the old-style kern table to activate kerning.
@@ -5426,5 +6049,5 @@ Performing all this font modification manually can be tedious (not to mention ha
 Fortunately, FontForge provides a {url-fontforge-scripting}[scripting interface], which you can use to automate the process.
 
 In fact, that's what we use to prepare the fonts that are bundled with Asciidoctor PDF.
-You can find that FontForge script, the Bash script that calls it, and the Docker image in which it is run in the https://github.com/asciidoctor/asciidoctor-pdf/tree/main/scripts[scripts directory] of this project.
+You can find that FontForge script, the Bash script that calls it, and the Docker image in which it is run in the {url-repo-root}/scripts[scripts directory] of this project.
 You can use that script as a starting point or reference for your own font preparation / modification script.