asciidoctor-pdf 1.5.0.beta.2 → 1.5.0.beta.3

data/data/themes/base-theme.yml

@@ -3,6 +3,7 @@
 vertical_spacing: 12
 page_background_color: 'FFFFFF'
 page_layout: portrait
+page_initial_zoom: FitH
 # 36 is equivalent to 0.5in
 page_margin: 36
 page_margin_inner: 48
@@ -15,10 +16,9 @@ base_font_color: '000000'
 base_font_family: Helvetica
 base_font_size: 12
 # QUESTION should we rename to min_font_size?
-base_font_size_min: 9
+base_font_size_min: 6
 base_font_style: normal
 base_line_height: 1.15
-base_line_height_length: 13.8
 base_border_color: 'EEEEEE'
 base_border_width: 0.5
 role_big_font_size: 14
@@ -28,6 +28,8 @@ button_font_family: Courier
 button_font_style: bold
 key_font_family: Courier
 key_font_style: italic
+mark_background_color: ffff00
+mark_border_offset: 0.5
 link_font_color: '0000EE'
 literal_font_family: Courier
 heading_font_style: bold
@@ -40,6 +42,7 @@ heading_h6_font_size: 10
 heading_line_height: 1.15
 heading_margin_top: 4
 heading_margin_bottom: 12
+heading_min_height_after: 20
 title_page_align: center
 title_page_line_height: 1.15
 title_page_logo_top: 10%

data/data/themes/default-theme.yml

@@ -15,6 +15,7 @@ font:
 page:
   background_color: ffffff
   layout: portrait
+  initial_zoom: FitH
   margin: [0.5in, 0.67in, 0.67in, 0.67in]
   # margin_inner and margin_outer keys are used for recto/verso print margins when media=prepress
   margin_inner: 0.75in
@@ -54,7 +55,6 @@ base:
 role:
   big:
     font_size: $base_font_size_large
-role:
   small:
     font_size: $base_font_size_small
 # FIXME vertical_rhythm is weird; we should think in terms of ems
@@ -81,6 +81,9 @@ key:
   border_width: 0.375
   font_family: $literal_font_family
   separator: "\u202f+\u202f"
+mark:
+  background_color: ffff00
+  border_offset: 0.5
 menu:
   caret_content: " <font size=\"1.15em\"><color rgb=\"b12146\">\u203a</color></font> "
 heading:
@@ -102,6 +105,7 @@ heading:
   line_height: 1
   margin_top: $vertical_rhythm * 0.4
   margin_bottom: $vertical_rhythm * 0.9
+  min_height_after: $base_line_height_length * 1.5
 title_page:
   align: right
   logo:

data/docs/theming-guide.adoc

@@ -34,10 +34,10 @@ Topics remaining to document:
 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.
 
-TIP: The quickest way to get started creating your own theme is to <<Extends,extend the default theme>>.
-This not only gives you all the styles you need to build on, but also a collection of <<Bundled Fonts,bundled fonts>>.
-If you override the font catalog in your theme file, you must declare all the fonts you use (and provide the font files themselves).
-Insted, if you want to reuse the bundled fonts, simply reference the <<Bundled Fonts,bundled fonts>> in the <<Custom Fonts,font catalog>>.
+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.
 
 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.
 Using AFM fonts can result in missing functionality and warnings.
@@ -74,8 +74,9 @@ The theme language adds some extra features to YAML, such as variables, basic ma
 These enhancements will be explained in detail in later sections.
 
 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._
 
-Here's an example of a basic theme file:
+Here's an example of a basic theme file that extends the base theme:
 
 .basic-theme.yml
 [source,yaml]
@@ -116,7 +117,7 @@ When creating a new theme, you only have to define the keys you want to override
 All the available keys are documented in <<Keys>>.
 The converter uses the information from the theme map to help construct the PDF.
 
-Instead of writing a theme from scratch, you can extend the default theme using the `extends` key as follows:
+Instead of designing a theme from scratch, you can extend the default theme using the `extends` key as follows:
 
 [source,yaml]
 ----
@@ -126,7 +127,7 @@ base:
 ----
 
 You can also point the extends key at another custom theme to extend from it.
-Currently, the base theme is always loaded first.
+If you don't want to extend any theme, including the base theme, assign the value `~` to the `extends` key (i.e., `extends: ~`).
 
 WARNING: If you start a new theme from scratch, we strongly recommend defining TrueType fonts and specifying them in the `base` and `literal` categories.
 Otherwise, Asciidoctor PDF will use built-in AFM fonts, which can result in missing functionality and warnings.
@@ -572,7 +573,7 @@ It's possible to specify no color by assigning the special value `transparent`,
 
 [source,yaml]
 ----
-base:
+table:
   background-color: transparent
 ----
 
@@ -652,7 +653,7 @@ IMPORTANT: Asciidoctor has no challenge working with Unicode.
 In fact, it prefers Unicode and considers the entire range.
 However, once you convert to PDF, you have to meet the font requirements of PDF in order to preserve Unicode characters.
 That means you need to provide a font (at least a fallback font) that contains glyphs for all the characters you want to use.
-If you don't, you may notice that characters are missing.
+If you don't, you may notice that characters are missing (usually replaced with a box).
 There's nothing Asciidoctor can do to convince PDF to work with extended characters without the right fonts in play.
 
 === Built-In (AFM) Fonts
@@ -707,6 +708,7 @@ To prevent this warning, you need to specify a TrueType font.
 
 When using a TrueType font, you will get no warning for a missing glyph.
 That's a consequence of how Prawn works and is outside of Asciidoctor PDF's control.
+However, you'll likely see it substituted with a box (guaranteed if you're using one of the bundled fonts).
 
 For more information about how Prawn handles character encodings for built-in fonts, see https://github.com/prawnpdf/prawn/blob/master/CHANGELOG.md#vastly-improved-handling-of-encodings-for-pdf-built-in-afm-fonts[this note in the Prawn CHANGELOG].
 ****
@@ -731,8 +733,8 @@ 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.
 
-CAUTION: At the time of this writing, you cannot use the bundled fonts if you change the value of the `pdf-fontsdir` attribute (and thus define your own custom fonts).
-This limitation may be lifted in the future.
+TIP: 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 refer to the bundled fonts using the `GEM_FONTS_DIR` token.
+To do so, you can either a) prefix the path of the bundled font in the theme file with the segment `GEM_FONTS_DIR` (e.g., `GEM_FONTS_DIR/mplus1p-regular-fallback.ttf`, or b) include `GEM_FONT_DIR` in the value of the `pdf-fontsdir` attribute, separated from the location of your custom fonts by the path separator (e.g., `path/to/fonts:GEM_FONTS_DIR`).
 
 === Custom Fonts
 
@@ -790,7 +792,13 @@ When you execute Asciidoctor PDF, specify the directory where the fonts reside u
 
  $ asciidoctor-pdf -a pdf-theme=basic-theme.yml -a pdf-fontsdir=path/to/fonts document.adoc
 
-WARNING: Currently, all fonts referenced by the theme need to be present in the directory specified by the `pdf-fontsdir` attribute.
+You can specify multiple directories by separating the entries with the path separator (`:` for Unix, `;` for Windows).
+
+ $ 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:
+
+ $ asciidoctor-pdf -a pdf-theme=basic-theme.yml -a pdf-fontsdir=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.
 Effectively, it subsets the font.
@@ -826,6 +834,7 @@ This will allow you to use the same font names (aka families) in both your graph
 
 If a TrueType font is missing a character needed to render the document, such as a special symbol, you can have Asciidoctor PDF look for the character in a fallback font.
 You only need to specify a single fallback font, typically one that provides a full set of symbols.
+If the character isn't found in the fallback font, it will mostly likely be replaced by a box (guaranteed if you're using the bundled fallback font).
 
 IMPORTANT: The fallback font only gets used when the primary font is a TrueType font (i.e., TTF, DFont, TTC).
 Any glyph missing from an AFM font is simply replaced with the "`not`" glyph (`&#172;`).
@@ -975,11 +984,19 @@ Error text is shown in [.red]#red#.
 
 Currently, custom roles only apply to inline phrases and only support changing the font properties.
 
+The converter provides several predefined roles.
+The `big` and `small` roles map the font size to the $base-font-size-large and $base-font-size-small values, respectively.
+These two roles can be redefined.
+The `underline` and `line-through` roles add the underline and strikethrough decorations, respectively.
+These two roles _can't_ be redefined.
+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 in your theme if you'd like to make use of them when converting to PDF.
+
 [cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-3+|[#key-prefix-role]*Key Prefix:* <<key-prefix-role,role-<name> >>
+3+|[#key-prefix-role]*Key Prefix:* <<key-prefix-role,role-<name>{zwsp}>>
 
 |font-color
 |<<colors,Color>> +
@@ -1016,7 +1033,7 @@ Currently, custom roles only apply to inline phrases and only support changing t
 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.
+NOTE: The background of the title page can be styled independently of other pages.
 See <<Title Page>> for details.
 
 [cols="3,4,5l"]
@@ -1031,20 +1048,26 @@ See <<Title Page>> for details.
 |page:
   background-color: #fefefe
 
-|background-image^[1]^
-|image macro^[2]^ +
+|background-image^[2]^
+|image macro^[3]^ +
 (default: _not set_)
 |page:
   background-image: image:page-bg.png[]
 
-|background-image-(recto{vbar}verso)^[1]^
-|image macro^[2]^ +
+|background-image-(recto{vbar}verso)^[2]^
+|image macro^[3]^ +
 (default: _not set_)
 |page:
   background-image:
     recto: image:page-bg-recto.png[]
     verso: image:page-bg-verso.png[]
 
+|initial-zoom
+|Fit {vbar} FitH {vbar} FitV +
+(default: FitH)
+|page:
+  initial-zoom: Fit
+
 |layout
 |portrait {vbar} landscape +
 (default: portrait)
@@ -1057,13 +1080,13 @@ See <<Title Page>> for details.
 |page:
   margin: [0.5in, 0.67in, 1in, 0.67in]
 
-|margin-inner^[3]^
+|margin-inner^[4]^
 |<<measurement-units,Measurement>> +
 (default: 48)
 |page:
   margin-inner: 0.75in
 
-|margin-outer^[3]^
+|margin-outer^[4]^
 |<<measurement-units,Measurement>> +
 (default: 24)
 |page:
@@ -1082,11 +1105,14 @@ See <<Title Page>> for details.
   numbering-start-at: toc
 |===
 
-. By default, page background images are automatically scaled to fit the bounds of the page (i.e., `fit=contain`).
-The size of the background can be controlled using any of the sizing attributes on the image macro (i.e., fit, pdfwidth, scaledwidth, or width).
+. 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 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).
+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 you flatten out the keys (e.g., `page-background-recto`), you can also set the default page background image (`page-background`), which will then be used as a fallback if a background image isn't specified for a side.
-To disable the background for a side, use the value `none`.
+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 background 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.
 These margins and used when the value `prepress` is assigned to the `media` document attribute.
@@ -1161,9 +1187,9 @@ NOTE: While it's common to define additional keys in this category (e.g., `base-
 
 |font-size-min
 |<<values,Number>> +
-(default: 9)
+(default: 6)
 |base:
-  font-size-min: 6
+  font-size-min: $base-font-size * 0.75
 
 // font-size-small is a variable, not an official key
 //|font-size-small
@@ -1185,7 +1211,7 @@ NOTE: While it's common to define additional keys in this category (e.g., `base-
 
 |line-height-length^[2]^
 |<<values,Number>> +
-(default: 13.8)
+(default: _not set_)
 |base:
   line-height-length: 12
 
@@ -1201,8 +1227,9 @@ NOTE: While it's common to define additional keys in this category (e.g., `base-
 . 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.
-. You should set one of `line-height` or `line-height-length`, then derive the value of the other using a calculation as these are correlated values.
-For instance, if you set `line-height-length`, then use `$base-line-height-length / $base-font-size` as the value of `line-height`.
+. The `line-height-length` is a pseudo property that's local the theme.
+It's often used 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`.
 
 [#keys-vertical-spacing]
 === Vertical Spacing
@@ -1392,13 +1419,46 @@ The keys in this category control the style of most headings, including part tit
 |heading:
   margin-top: $vertical-spacing * 0.2
 
+|margin-page-top
+|<<measurement-units,Measurement>> +
+(default: 0)
+|heading:
+  margin-page-top: $vertical-spacing
+
 |margin-bottom
 |<<measurement-units,Measurement>> +
 (default: 12)
 |heading:
   margin-bottom: 9.6
 
-3+|[#key-prefix-heading-level]*Key Prefix:* <<key-prefix-heading-level,heading-h<n> >>^[1]^
+|min-height-after
+|<<measurement-units,Measurement>> +
+(default: $base-font-size * $base-line-height * 1.5)
+|heading:
+  min-height-after: 0.5in
+
+|chapter-break-before
+|always {vbar} auto +
+(default: always)
+|heading:
+  chapter:
+    break-before: auto
+
+|part-break-before
+|always {vbar} auto +
+(default: always)
+|heading:
+  part:
+    break-before: auto
+
+|part-break-after
+|always {vbar} auto +
+(default: auto)
+|heading:
+  part:
+    break-after: always
+
+3+|[#key-prefix-heading-level]*Key Prefix:* <<key-prefix-heading-level,heading-h<n>{zwsp}>>^[1]^
 
 |align
 |<<text-alignments,Text alignment>> +
@@ -1434,7 +1494,25 @@ The keys in this category control the style of most headings, including part tit
 |<<text-transforms,Text transform>> +
 (default: $heading-text-transform)
 |heading:
-  text-transform: lowercase
+  h3-text-transform: lowercase
+
+|margin-top
+|<<measurement-units,Measurement>> +
+(default: $heading-margin-top)
+|heading:
+  h2-margin-top: $vertical-spacing * 0.5
+
+|margin-page-top
+|<<measurement-units,Measurement>> +
+(default: $heading-margin-page-top)
+|heading:
+  h2-margin-page-top: $vertical-spacing
+
+|margin-bottom
+|<<measurement-units,Measurement>> +
+(default: $heading-margin-bottom)
+|heading:
+  h2-margin-bottom: 10
 |===
 
 . `<n>` is a number ranging from 1 to 6, representing each of the six heading levels.
@@ -1446,7 +1524,11 @@ If you want the font size of a specific level to be inherited, you must assign t
 
 The keys in this category control the style of the title page as well as the arrangement and style of the elements on it.
 
-TIP: The title page can be disabled from the document by setting the `notitle` attribute in the AsciiDoc document header.
+IMPORTANT: The title page is only enabled by default for the book doctype (e.g., `:doctype: book`).
+If you want to enable the title page when using a different doctype (such as the article doctype), you must define the `title-page` attribute in the document header (i.e., `:title-page:`).
+
+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).
 
 [cols="3,4,5l"]
 |===
@@ -1466,8 +1548,8 @@ TIP: The title page can be disabled from the document by setting the `notitle` a
 |title-page:
   background-color: #eaeaea
 
-|background-image^[1]^
-|image macro^[2]^ +
+|background-image^[2]^
+|image macro^[3]^ +
 (default: _not set_)
 |title-page:
   background-image: image:title.png[]
@@ -1518,14 +1600,14 @@ TIP: The title page can be disabled from the document by setting the `notitle` a
     align: right
 
 |image
-|image macro^[2]^ +
+|image macro^[3]^ +
 (default: _not set_)
 |title-page:
   logo:
     image: image:logo.png[pdfwidth=25%]
 
 |top
-|Percentage^[3]^ +
+|Percentage^[4]^ +
 (default: 10%)
 |title-page:
   logo:
@@ -1771,8 +1853,11 @@ TIP: The title page can be disabled from the document by setting the `notitle` a
     margin-bottom: 5
 |===
 
-. By default, page background images are automatically scaled to fit the bounds of the page (i.e., `fit=contain`).
-The size of the background can be controlled using any of the sizing attributes on the image macro (i.e., fit, pdfwidth, scaledwidth, or width).
+. 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`).
+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).
+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.
 . Percentage unit can be % (relative to content height) or vh (relative to page height).
 
@@ -2000,7 +2085,7 @@ The keys in this category are used to control the style of literal, listing and
 |code:
   padding: 11
 
-3+|[#key-prefix-table-cell]*Key Prefix:* <<key-prefix-code-linenum,code-linenum>>^[2]^
+3+|[#key-prefix-code-linenum]*Key Prefix:* <<key-prefix-code-linenum,code-linenum>>^[2]^
 
 |font-color
 |<<colors,Color>> +
@@ -2654,7 +2739,7 @@ The keys in this category control the arrangement and style of admonition blocks
   label:
     text-transform: lowercase
 
-3+|[#key-prefix-admonition-icon]*Key Prefix:* <<key-prefix-admonition-icon,admonition-icon-<name> >>^[2]^
+3+|[#key-prefix-admonition-icon]*Key Prefix:* <<key-prefix-admonition-icon,admonition-icon-<name>{zwsp}>>^[2]^
 
 |name
 |<icon set>-<icon name>^[3]^ +
@@ -2683,6 +2768,8 @@ The keys in this category control the arrangement and style of admonition blocks
 
 . The top and bottom padding values are ignored on admonition-label-padding.
 . `<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.
 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.
@@ -2710,10 +2797,37 @@ The keys in this category control the arrangement of block images.
 (default: _not set_)
 |image:
   width: 100%
+
+|border-color^[2]^
+|<<colors,Color>> +
+(default: _not set_)
+|image:
+  border-color: #cccccc
+
+|border-radius
+|<<values,Number>> +
+(default: _not set_)
+|image:
+  border-radius: 2
+
+|border-width^[2]^
+|<<values,Number>> +
+(default: _not set_)
+|image:
+  border-width: 0.5
+
+|border-fit^[3]^
+|content {vbar} auto
+(default: content)
+|image:
+  border-fit: auto
 |===
 
 . Only applies to block images.
 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` 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.
+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.
 
 [#keys-svg]
 === SVG
@@ -3029,7 +3143,7 @@ The keys in this category control the arrangement and style of unordered list it
 |===
 |Key |Value Type |Example
 
-3+|*Key Prefix:* ulist-marker-<type>^[1]^
+3+|[#key-prefix-ulist-marker-type]*Key Prefix:* <<key-prefix-ulist-marker-type,ulist-marker-<type>{zwsp}>>^[1]^
 
 |content
 |<<quoted-string,Quoted string>>
@@ -3469,7 +3583,7 @@ The keys in this category control the arrangement and style of the table of cont
 |toc:
   margin-top: 0
 
-3+|[#key-prefix-toc-level]*Key Prefix:* <<key-prefix-toc-level,toc-h<n> >>^[1]^
+3+|[#key-prefix-toc-level]*Key Prefix:* <<key-prefix-toc-level,toc-h<n>{zwsp}>>^[1]^
 
 |font-color
 |<<colors,Color>> +
@@ -3920,8 +4034,9 @@ One exception to this rule are inline images, which are described in the next se
 ==== Images
 
 You can add an image to the running header or footer using the AsciiDoc inline image syntax.
-Note that the image must be the whole value for a given position (left, center or right).
-It cannot be combined with text.
+The image target is resolved relative to the value of the `pdf-themesdir` attribute.
+If the image macro is the whole value for a column position, you can use the `position` and `fit` attributes to align and scale it relative to the column box.
+Otherwise, the image is treated like a normal inline image, for which you can only adjust the width.
 
 Here's an example of how to use an image in the running header (which also applies for the footer).
 
@@ -3961,7 +4076,8 @@ _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 where the fonts used by your theme, if any, are located.
+pdf-fontsdir:: The directory or directories where the fonts used by your theme, if any, are located.
+Multiple entries must be separated by path separator (`:` for Unix, `;` for Windows).
 _Specifying an absolute path is recommended._
 
 Let's assume that you've put your theme files inside a directory named `resources` with the following layout:
@@ -3984,7 +4100,7 @@ Here's how you'd load your theme when calling Asciidoctor PDF:
 
 If all goes well, Asciidoctor PDF should run without an error or warning.
 
-NOTE: You only need to specify the `pdf-fontsdir` if you are using custom fonts in your theme.
+NOTE: You only need to specify the `pdf-fontsdir` if you're using custom fonts in your theme.
 
 You can skip setting the `pdf-themesdir` attribute and just pass the absolute path of your theme file to the `pdf-theme` attribute.
 
@@ -4091,18 +4207,20 @@ These settings override equivalent keys defined in the theme file, where applica
 . 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`).
-The size of the background can be controlled using any of the sizing attributes on the image macro (i.e., fit, pdfwidth, scaledwidth, or width).
+. 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).
+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 for a side, use the value `none`.
+To disable the background image for a side, use the value `none`.
 . Controls whether the `page-number` attribute is accessible to the running header and footer content specified in the theme file.
 Use the `noheader` and `nofooter` attributes to disable the running header and footer, respectively, from the document.
 . 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.
 . _(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.
-. Force a title page to be added even when the doctype is not book.
+. 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.
 
 == Publishing Mode
 
@@ -4242,7 +4360,7 @@ For more information about source highlighting with Rouge, refer to the http://r
 == 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).
-However, you may discover that kerning is disabled and certain required glyphs are missing.
+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].
 
 === Validate the Font
@@ -4282,7 +4400,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).
-* Add the glyphs for the required characters if missing from the font (optional if using a falback font).
+* 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.
 
@@ -4294,7 +4412,7 @@ Most fonts do not provide glyphs for all the Unicode character ranges (i.e., scr
 In fact, many fonts only include glyphs for Latin (Basic, Supplement, and Extended) and a few other scripts (e.g., Cyrillic, Greek).
 That means certain glyphs Asciidoctor PDF relies on may be missing from the font.
 
-Below are are the non-Latin characters that Asciidoctor PDF uses (for which glyphs are often missing):
+Below are the non-Latin characters (identified by Unicode code point) on which Asciidoctor PDF relies that are often missing from fonts.
 Unless you're using a fallback font that fills in the missing glyphs, you need to ensure these glyphs are present in your font (and add them if not).
 
 * \u00a0 - no-break space
@@ -4312,6 +4430,11 @@ Unless you're using a fallback font that fills in the missing glyphs, you need t
 * \u2014 - em-dash (used in quote attribute)
 * \u203a - single right-pointing quotation mark (used in the menu UI element)
 * \u25ba - right pointer (used for media play icon when icon fonts are disabled)
+* .notdef - used as the default glyph when a requested character is missing from the font (usually a box)
+
+NOTE: If the .notdef glyph is non-empty (i.e., contains splines), it will be used as the default glyph when the document requests a character that is missing from the font.
+Unlike other glyphs, the .notdef glyph is referenced by name only.
+It does not have a designated Unicode code point.
 
 If you're preparing a font for use in verbatim blocks (e.g., a listing block), you'll also need this range of characters: