asciidoctor-pdf 1.5.0.beta.5 → 1.5.0.beta.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6a1fbcfb416a485f625f2b12c4b7c30806e0d05cdf3ecc327b2ae6b0b04003e
-  data.tar.gz: bb1f4811237d7478cd132474175e11fbc1fa9e4755a0888ba1bb633215174b16
+  metadata.gz: fa4efe2963835f293701e1e831c7fc5cafce4c1922362b063e8265bd133e29a1
+  data.tar.gz: '08ff1cbea70552786797786465cfab1c626506287dbd8e56ae0204da000c5807'
 SHA512:
-  metadata.gz: f8ed0674cbc59c95bd5408874381d24708d3d07f3c6762297e9352727ddab3a67afae2e32bd48585feac84f57f9cfc03d8cee1388003617772a457591354793a
-  data.tar.gz: 1d38fa4fce88891b32d15b52829244222f5a1ada6269ad6108ed38cda7ed8a202d8793a4dab1ff9eadd597c53768994e0bf844e94587752d5ce51f7801677152
+  metadata.gz: 16733468d925e9e30158073fd0859498c2c70fd9c8f3ede9e49ab57eda7391dbde5eda608dead1fcf01db5414a4d46f5f0e486470f45f467b263cf11fdd95ded
+  data.tar.gz: ed4a9a710c1bf31940265451e4bafb312c1fb4ca4d75a2ab69e89948f6e2975c1410a9335edef5e1fd0ce4bb7bb286b4612149d5d01c52014d571143f4d807f4

data/CHANGELOG.adoc

@@ -5,6 +5,35 @@
 This document provides a high-level view of the changes to the {project-name} by release.
 For a detailed view of what has changed, refer to the {uri-repo}/commits/master[commit history] on GitHub.
 
+== 1.5.0.beta.6 (2019-10-11) - @mojavelinux
+
+* reorganize source files under asciidoctor/pdf folder (instead of asciidoctor-pdf)
+* reorganize monkeypatch files under asciidoctor/pdf/ext
+* allow toc to be positioned using toc macro (#1030)
+* extend dots leading up to page number from wrapped line in toc (#1152)
+* set fit=contain by default on cover and page background images (#1275)
+* implement fit=fill for cover, page background, and running content raster (non-SVG) images (#1276)
+* allow foreground image (e.g., watermark) to be added to each page using page-foreground-image attribute or theme key (#727)
+* allow section body to be indented using section_indent key in theme (#737)
+* add glyphs for built-in characters to bundled monospace font (M+ 1mn) (#1274)
+* look for "noborder" role on image even if other roles are defined
+* remove deprecated table_odd_row_background_color and table_even_row_background_color keys from theme
+* implement unordered and ordered description lists (#1280)
+* recognize transparent as valid value for cellbgcolor attribute
+* allow custom role to revert font style to normal (#1286)
+* allow theme to control font properties (font size, font color, etc) of description list term (#1289)
+* allow theme to override caption styles for specific block categories: blockquote, code, example, footnotes, image, listing, and table (#307)
+* allow theme to control style of verse block independently of a quote block (#40)
+* position list marker correctly when media=prepress and list item is advanced to next page or split across pages (#1303)
+* layout horizontal dlist in two columns (#310)
+* apply normal substitutions to content of manname section (#1294)
+* optimize PDF using quality specified in value of optimize attribute if optimize attribute is set (#535)
+* allow xref macro to override xrefstyle set on document
+* assume admonition icon in theme is a legacy FontAwesome icon if the icon set prefix is absent
+* rewrite optimize-pdf as a bin script named asciidoctor-pdf-optimize
+* allow image alt text formatting and arrangement to be controlled by theme (#730)
+* upgrade prawn-icon to 2.5.0 (which upgrades Font Awesome to 5.11.2)
+
 == 1.5.0.beta.5 (2019-09-13) - @mojavelinux
 
 * pass styles for inline elements downwards when parsing, allowing role to override default styles for element (#1219)
@@ -110,10 +139,11 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/master[
 * scale SVG background image to fit page in the same way raster image is scaled (#765)
 * allow page background size to be controlled using image macro attributes (#1117)
 * allow page background image position to be controlled using position attribute on image macro (#1124)
-* add support for fit=cover for cover page, page background, and running content images (#1136)
+* add support for fit=cover for cover, page background, and running content images (#1136)
 * change default background image position to center (#1124)
 * allow cover image position to be controlled using position attribute on image macro (#1134)
 * change default cover image position to center (#1134)
+* allow cover image size to be controlled using fit, pdfwidth, and width attributes; don't scale image by default (#1134)
 * set enable_file_requests_with_root and enable_web_requests options for all SVGs (#683)
 * automatically set pdf-stylesdir if pdf-style ends with .yml and pdf-stylesdir is not specified (#1126)
 * replace hyphens with underscores in top-level theme keys
@@ -272,7 +302,8 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/master[
 * implement start line number for source listing (Rouge) (#752)
 * enable "start inline" option when highlighting PHP (#755)
 * persuade CodeRay to handle html+ source languages
-* introduce stripes attribute to table to control zebra-striping (#724)
+* introduce stripes attribute to table to control zebra striping (#724)
+* use theme key table_body_stripe_background_color to control color of table stripes (#724)
 * allow theme to set style of table border and grid (#766)
 * allow theme to set text transform on header cell in table body (#750)
 * set top border width of first body row to match bottom border width of header row

data/README.adoc

@@ -1,6 +1,6 @@
 = Asciidoctor PDF: A native PDF converter for AsciiDoc
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
-v1.5.0.beta.5, 2019-09-13
+v1.5.0.beta.6, 2019-10-12
 // Settings:
 :experimental:
 :idprefix:
@@ -24,7 +24,7 @@ endif::[]
 :project-name: Asciidoctor PDF
 :project-handle: asciidoctor-pdf
 // Variables:
-:release-version: 1.5.0.beta.5
+:release-version: 1.5.0.beta.6
 // URIs:
 :url-asciidoctor: http://asciidoctor.org
 :url-gem: http://rubygems.org/gems/asciidoctor-pdf
@@ -476,19 +476,20 @@ If the image height exceeds the height of the page, the image will be scaled dow
 
 === Background Image Sizing
 
-In addition to the width-related attributes previously covered, background images can be sized relative to the page using the `fit` attribute of the image macro.
+In addition to the width-related attributes previously covered, cover and background images can be sized relative to the page using the `fit` attribute of the image macro.
 The `fit` attribute works similarly to the `object-fit` property in CSS.
 It's value must be specified as a single keyword, chosen from the table below.
 The starting size of the image is determined by the explicit width, if specified, or the implicit width.
-The height is always derived from with width, respecting the implicit aspect ratio of the image.
+The height is always derived from the width while respecting the implicit aspect ratio of the image.
 The available space for a background image (i.e., the canvas) is the page.
+If the `fit` attribute is not specified, it defaults to `contain`.
 
 [cols="1s,3"]
 |===
 | Value | Purpose
 
 | contain
-| The image is scaled up or down while retaining its aspect ratio to fit within the available space.
+| The image is scaled up or down while retaining its aspect ratio to fit within the available space. (default)
 
 | cover
 | The image is scaled up or down while retaining its aspect ratio so the image completely covers the available space, even if it means the image must be clipped in one direction.
@@ -497,6 +498,10 @@ The available space for a background image (i.e., the canvas) is the page.
 | The image is scaled down while retaining its aspect ratio to fit within the available space.
 If the image already fits, it is not scaled.
 
+| fill
+| The image is scaled to fit the available space even if it means modifying the aspect ratio of the image.
+Does not apply to SVG images.
+
 | none
 | The image is not scaled.
 |===
@@ -529,13 +534,13 @@ right
 Here's an example of how to place a background image at the top center of every page:
 
 ----
-:page-background-image: image:bg.png[pdfwidth=50%,position=top]
+:page-background-image: image:bg.png[fit=none,pdfwidth=50%,position=top]
 ----
 
 Here's how to move it to the bottom right:
 
 ----
-:page-background-image: image:bg.png[pdfwidth=50%,position=bottom right]
+:page-background-image: image:bg.png[fit=none,pdfwidth=50%,position=bottom right]
 ----
 
 If an image dimension matches the height or width of the page, the positioning keyword for that axis has no effect.
@@ -712,7 +717,7 @@ Let's start small.
 
 You'll find when you run this example that all the interdocument xrefs become internal references in the PDF.
 
-The reason both the path and anchor are required (even when liking to the top of a chapter) is so the interdocument xref works independent of the converter.
+The reason both the path and anchor are required (even when linking to the top of a chapter) is so the interdocument xref works independent of the converter.
 In other words, it encodes the complete information about the reference so the converter can sort out where the target is in all circumstances.
 
 == STEM Support
@@ -894,27 +899,25 @@ However, you could use an extension, such as a TreeProcessor, to automatically m
 
 == Optimizing the Generated PDF
 
-=== optimize-pdf
+=== asciidoctor-pdf-optimize
 
-{project-name} also provides a shell script that uses GhostScript (`gs`) to optimize and compress the generated PDF (with minimal impact on quality).
-You must have Ghostscript installed to use it.
+{project-name} also provides a bin script that uses GhostScript to optimize and compress the generated PDF (with minimal impact on quality).
+You must have Ghostscript (command: `gs`) and the `rghost` gem installed to use it.
 
 Here's an example usage:
 
- $ ./bin/optimize-pdf basic-example.pdf
-
-The command will generate the file [.path]_basic-example-optimized.pdf_ in the same directory.
+ $ asciidoctor-pdf-optimize basic-example.pdf
 
-WARNING: The `optimize-pdf` script currently requires a Bash shell (Linux, OSX, etc).
-We plan to rewrite the script in Ruby so it works across platforms (see https://github.com/asciidoctor/asciidoctor-pdf/issues/1[issue #1])
+The command will overwrite the PDF file with an optimized version.
 
 If a file is found with the extension `.pdfmark` and the same rootname as the input file, it is used to add metadata to the generated PDF document.
 This file is necessary to preserve the document metadata since Ghostscript will otherwise drop it.
 That's why {project-name} always creates this file in addition to the PDF.
 
-IMPORTANT: The `optimize-pdf` script relies on Ghostscript >= 9.10.
-Otherwise, it may actually make the PDF larger.
-You should probably only consider using it if the file size of the original PDF is > 5MB.
+IMPORTANT: The `asciidoctor-pdf-optimize` is not guaranteed to reduce the size of the PDF file.
+It may actually make the PDF larger.
+You should probably only consider using it if the file size of the original PDF is several megabytes.
+You can also try reducing the quality of the output file using the `-q` flag (e.g., `-q screen`).
 
 === hexapdf
 

data/asciidoctor-pdf.gemspec

@@ -29,8 +29,7 @@ Gem::Specification.new do |s|
     files = Dir['**/*']
   end
   s.files = files.grep %r/^(?:(?:data|lib)\/.+|docs\/theming-guide\.adoc|(?:CHANGELOG|LICENSE|NOTICE|README)\.adoc|\.yardopts|#{s.name}\.gemspec)$/
-  # FIXME optimize-pdf is currently a shell script, so listing it here won't work
-  #s.executables = (files.grep %r/^bin\//).map {|f| File.basename f }
+  s.executables = (files.grep %r/^bin\//).map {|f| File.basename f }
   s.executables = ['asciidoctor-pdf']
   s.require_paths = ['lib']
   #s.test_files = files.grep %r/^(?:test|spec|feature)\/.*$/
@@ -40,20 +39,20 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'prawn-table', '~> 0.2.0'
   s.add_runtime_dependency 'prawn-templates', '~> 0.1.0'
   s.add_runtime_dependency 'prawn-svg', '~> 0.29.0'
-  s.add_runtime_dependency 'prawn-icon', '~> 2.4.0'
+  s.add_runtime_dependency 'prawn-icon', '~> 2.5.0'
   s.add_runtime_dependency 'safe_yaml', '~> 1.0.0'
   s.add_runtime_dependency 'thread_safe', '~> 0.3.0'
   s.add_runtime_dependency 'concurrent-ruby', '~> 1.1.0'
   # For our usage, treetop 1.6 is slower than treetop 1.5
   s.add_runtime_dependency 'treetop', '~> 1.5.0'
 
-  s.add_development_dependency 'rake', '~> 12.3.0'
+  s.add_development_dependency 'rake', '~> 13.0.0'
   s.add_development_dependency 'deep-cover-core', '~> 0.7.0'
   s.add_development_dependency 'simplecov', '~> 0.17.0'
-  s.add_development_dependency 'rspec', '~> 3.8.0'
+  s.add_development_dependency 'rspec', '~> 3.9.0'
   s.add_development_dependency 'pdf-inspector', '~> 1.3.0'
   # Asciidoctor PDF supports Rouge >= 2 (verified in CI build using 2.0.0)
-  s.add_development_dependency 'rouge', '~> 3.6.0'
+  s.add_development_dependency 'rouge', '~> 3.11.0'
   s.add_development_dependency 'coderay', '~> 1.1.0'
   s.add_development_dependency 'chunky_png', '~> 1.3.0'
 end

data/data/themes/base-theme.yml

@@ -74,6 +74,9 @@ admonition_label_text_transform: uppercase
 blockquote_border_color: 'EEEEEE'
 blockquote_border_width: 4
 blockquote_padding: [6, 12, -6, 14]
+verse_border_color: 'EEEEEE'
+verse_border_width: 4
+verse_padding: [6, 12, -6, 14]
 code_font_family: Courier
 code_font_size: 10.8
 code_line_height: 1.2

data/data/themes/default-theme.yml

@@ -164,7 +164,6 @@ admonition:
     text_transform: uppercase
     font_style: bold
 blockquote:
-  font_color: $base_font_color
   font_size: $base_font_size_large
   border_color: $base_border_color
   border_width: 5
@@ -172,6 +171,13 @@ blockquote:
   padding: [0, $horizontal_rhythm, $block_margin_bottom * -0.75, $horizontal_rhythm + $blockquote_border_width / 2]
   cite_font_size: $base_font_size_small
   cite_font_color: 999999
+verse:
+  font_size: $blockquote_font_size
+  border_color: $blockquote_border_color
+  border_width: $blockquote_border_width
+  padding: $blockquote_padding
+  cite_font_size: $blockquote_cite_font_size
+  cite_font_color: $blockquote_cite_font_color
 # code is used for source blocks (perhaps change to source or listing?)
 code:
   font_color: $base_font_color

data/docs/theming-guide.adoc

@@ -37,7 +37,7 @@ This document describes how the theming system works, how to define a custom the
 
 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>>.
+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.
@@ -314,7 +314,7 @@ base:
 === Math Expressions & Functions
 
 The theme language supports basic math operations to support calculated values.
-Like programming languages, multiple and divide take precedence over add and subtract.
+Like programming languages, multiply and divide take precedence over add and subtract.
 
 The following table lists the supported operations and the corresponding operator for each.
 
@@ -448,7 +448,7 @@ Images can be aligned as follows:
 
 === Font Styles
 
-In most cases, whereever you can specify a custom font family, you can also specify a font style.
+In most cases, wherever you can specify a custom font family, you can also specify a font style.
 These two settings are combined to locate the font to use.
 
 The following font styles are recognized:
@@ -578,6 +578,8 @@ table:
   background-color: transparent
 ----
 
+The `transparent` keyword can be used for the background or border color, but not the font color.
+
 === Images
 
 An image is specified either as a bare image path or as an inline image macro as found in the AsciiDoc syntax.
@@ -815,7 +817,7 @@ 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 it not a requirement, simply a personal preference.
+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:
@@ -1112,6 +1114,12 @@ See <<Title Page>> for details.
     recto: image:page-bg-recto.png[]
     verso: image:page-bg-verso.png[]
 
+|foreground-image^[2]^
+|image macro^[3]^ +
+(default: _not set_)
+|page
+  foreground-image: image:watermark.svg[]
+
 |initial-zoom
 |Fit {vbar} FitH {vbar} FitV +
 (default: FitH)
@@ -1157,12 +1165,12 @@ See <<Title Page>> for details.
 
 . 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.
+. 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 background image, use the value `none`.
+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.
 These margins and used when the value `prepress` is assigned to the `media` document attribute.
@@ -1277,9 +1285,10 @@ 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.
-. 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.
+. `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
@@ -1569,6 +1578,24 @@ The keys in this category control the style of most headings, including part tit
 . 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]
+=== Section
+
+The keys in this category control the style of a section body.
+
+[cols="3,4,5l"]
+|===
+|Key |Value Type |Example
+
+3+|[#key-prefix-section]*Key Prefix:* <<key-prefix-section,section>>
+
+|indent
+|<<measurement-units,Measurement>> +
+(default: 0)
+|section:
+  indent: 36
+|===
+
 [#keys-title-page]
 === Title Page
 
@@ -1906,7 +1933,7 @@ TIP: The title page can be disabled for the book doctype by setting the `notitle
 . 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 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.
 . Percentage unit can be % (relative to content height) or vh (relative to page height).
@@ -2002,6 +2029,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.
 
 [cols="3,4,5l"]
 |===
@@ -2392,7 +2420,7 @@ The keys in this category control the arrangement and style of quote blocks.
 |<<colors,Color>> +
 (default: #eeeeee)
 |blockquote:
-  border-color: #eeeeee
+  border-color: #dddddd
 
 |font-color
 |<<colors,Color>> +
@@ -2470,6 +2498,105 @@ The keys in this category control the arrangement and style of quote blocks.
 
 . Only applies to the left side.
 
+[#keys-verse]
+=== Verse
+
+The keys in this category control the arrangement and style of verse blocks.
+
+[cols="3,4,5l"]
+|===
+|Key |Value Type |Example
+
+3+|[#key-prefix-verse]*Key Prefix:* <<key-prefix-verse,verse>>
+
+|border-width^[1]^
+|<<values,Number>> +
+(default: 4)
+|verse:
+  border-width: 5
+
+|border-color^[1]^
+|<<colors,Color>> +
+(default: #eeeeee)
+|verse:
+  border-color: #dddddd
+
+|font-color
+|<<colors,Color>> +
+(default: _inherit_)
+|verse:
+  font-color: #333333
+
+|font-family
+|<<fonts,Font family name>> +
+(default: _inherit_)
+|verse:
+  font-family: M+ 1mn
+
+|font-size
+|<<values,Number>> +
+(default: _inherit_)
+|verse:
+  font-size: 10
+
+|font-style
+|<<font-styles,Font style>> +
+(default: _inherit_)
+|verse:
+  font-style: bold
+
+|text-transform
+|<<text-transforms,Text transform>> +
+(default: _inherit_)
+|verse:
+  text-transform: uppercase
+
+|padding
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
+(default: [6, 12, -6, 14])
+|verse:
+  padding: [5, 10, -5, 12]
+
+3+|[#key-prefix-verse-cite]*Key Prefix:* <<key-prefix-verse-cite,verse-cite>>
+
+|font-size
+|<<values,Number>> +
+(default: _inherit_)
+|verse:
+  cite:
+    font-size: 9
+
+|font-color
+|<<colors,Color>> +
+(default: _inherit_)
+|verse:
+  cite:
+    font-color: #999999
+
+|font-family
+|<<fonts,Font family name>> +
+(default: _inherit_)
+|verse:
+  cite:
+    font-family: Noto Serif
+
+|font-style
+|<<font-styles,Font style>> +
+(default: _inherit_)
+|verse:
+  cite:
+    font-style: italic
+
+|text-transform
+|<<text-transforms,Text transform>> +
+(default: _inherit_)
+|verse:
+  cite:
+    text-transform: uppercase
+|===
+
+. Only applies to the left side.
+
 [#keys-sidebar]
 === Sidebar
 
@@ -2824,6 +2951,7 @@ The subkeys in the icon category cannot be flattened (e.g., `tip-name: far-light
 . 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.
 
 [#keys-image]
 === Image
@@ -2871,6 +2999,43 @@ The keys in this category control the arrangement of block images.
 (default: content)
 |image:
   border-fit: auto
+
+3+|[#key-prefix-image-alt]*Key Prefix:* <<key-prefix-image-alt,image-alt>>
+
+|content^[4]^
+|<<quoted-string,Quoted string>> +
+(default: "%\{link}[%\{alt}]%{/link} {vbar} %\{target}")
+|image:
+  alt:
+    content: "%{alt} (%{target})"
+
+|font-color
+|<<colors,Color>> +
+(default: _inherit_)
+|image:
+  alt:
+    font-color: #ff000
+
+|font-family
+|<<fonts,Font family name>> +
+(default: _inherit_)
+|image
+  alt:
+    font-family: Courier
+
+|font-size
+|<<values,Number>> +
+(default: _inherit_)
+|image:
+  alt:
+    font-size: 9
+
+|font-style
+|<<font-styles,Font style>> +
+(default: normal)
+|iamge:
+  alt:
+    font-style: italic
 |===
 
 . Only applies to block images.
@@ -2878,6 +3043,7 @@ If specified, this value takes precedence over the value of the `width` attribut
 . 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.
 
 [#keys-svg]
 === SVG
@@ -3085,18 +3251,66 @@ The keys in this category control the style of thematic breaks (aka horizontal r
 
 The keys in this category control the arrangement and style of definition list items (terms and descriptions).
 
+[TIP]
+====
+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.
+
+[source,asciidoc]
+----
+[unordered]
+* alpha:: partially complete and unstable
+* beta:: feature complete and undergoing testing
+----
+====
+
 [cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
 3+|[#key-prefix-description-list]*Key Prefix:* <<key-prefix-description-list,description-list>>
 
+|term-font-color
+|<<colors,Color>> +
+(default: _inherit_)
+|description-list:
+  term-font-color: #AA0000
+
+|term-font-family
+|<<fonts,Font family name>> +
+(default: _inherit_)
+|description-list:
+  term-font-family: Noto Serif
+
+|term-font-size
+|<<values,Number>> +
+(default: _inherit_)
+|description-list:
+  term-font-size: 12
+
 |term-font-style
 |<<font-styles,Font style>> +
 (default: bold)
 |description-list:
   term-font-style: italic
 
+|term-text-transform
+|<<text-transforms,Text transform>> +
+(default: none)
+|description-list:
+  term-text-transform: none
+
+|term-line-height
+|<<values,Number>> +
+(default: $base-line-height)
+|description-list:
+  term-line-height: 1.2
+
 |term-spacing
 |<<measurement-units,Measurement>> +
 (default: 4)
@@ -3847,7 +4061,7 @@ To avoid this problem, reduce the height of the running content periphery or mak
 |header:
   image-vertical-align: 4
 
-|sectlevels
+|sectlevels^[4]^
 |Integer +
 (default: 2)
 |header:
@@ -3871,14 +4085,14 @@ To avoid this problem, reduce the height of the running content periphery or mak
 |header:
   vertical-align: center
 
-|<side>-columns^[4]^
+|<side>-columns^[5]^
 |Column specs triple +
 (default: _not set_)
 |header:
   recto:
     columns: <25% =50% >25%
 
-|<side>-<position>-content^[4,5]^
+|<side>-<position>-content^[5,6]^
 |<<quoted-string,Quoted string>> +
 (default: '\{page-number}')
 |header:
@@ -3960,7 +4174,7 @@ To avoid this problem, reduce the height of the running content periphery or mak
 |footer:
   image-vertical-align: 4
 
-|sectlevels
+|sectlevels^[4]^
 |Integer +
 (default: 2)
 |footer:
@@ -3984,14 +4198,14 @@ To avoid this problem, reduce the height of the running content periphery or mak
 |footer:
   vertical-align: top
 
-|<side>-columns^[4]^
+|<side>-columns^[5]^
 |Column specs triple +
 (default: _not set_)
 |footer:
   verso:
     columns: <50% =0% <50%
 
-|<side>-<position>-content^[4,5]^
+|<side>-<position>-content^[5,6]^
 |<<quoted-string,Quoted string>> +
 (default: '\{page-number}')
 |footer:
@@ -4002,7 +4216,9 @@ To avoid this problem, reduce the height of the running content periphery or mak
 . 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).
+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`.
 
@@ -4022,7 +4238,7 @@ You can use _any_ attribute defined in your AsciiDoc document (such as `doctitle
 In addition, the following attributes are also available when defining the content keys in the footer:
 
 * page-count
-* page-number
+* page-number (only set if the `pagenums` attribute is set on the document, which it is by default)
 * document-title
 * document-subtitle
 * part-title
@@ -4030,6 +4246,10 @@ In addition, the following attributes are also available when defining the conte
 * section-title
 * section-or-chapter-title
 
+If you reference an attribute which is not defined, all the text on that same line in the running content will be dropped.
+One case where this is useful is when referencing the `page-number` attribute.
+If you unset the `pagenums` attribute on the document, any line in the running content that makes reference to `\{page-number}` will be dropped.
+
 You can also built-in AsciiDoc text replacements like `+(C)+`, numeric character references like `+&#169;+` and inline formatting (e.g., bold, italic, monospace).
 
 Here's an example that shows how attributes and replacements can be used in the running footer:
@@ -4056,6 +4276,8 @@ footer:
       content: '*{page-number}* | {chapter-title}'
 ----
 
+==== Multiple Lines
+
 You can split the content value across multiple lines using YAML's multiline string syntax.
 In this case, the single quotes around the string are not necessary.
 To force a hard line break in the output, add `{sp}+` to the end of the line in normal AsciiDoc fashion.
@@ -4199,6 +4421,10 @@ These settings override equivalent keys defined in the theme file, where applica
 |screen {vbar} print {vbar} prepress
 |:media: prepress
 
+|optimize
+|screen {vbar} ebook {vbar} printer {vbar} prepress {vbar} default (default: default)
+|:optimize: prepress
+
 |outlinelevels^[10]^
 |Integer {vbar} Integer:Integer (default: same as _toclevels_)
 |:outlinelevels: 2
@@ -4211,6 +4437,10 @@ These settings override equivalent keys defined in the theme file, where applica
 |path^[2]^ {vbar} image macro^[3]^
 |:page-background-image-recto: image:bg-recto.jpg[]
 
+|page-foreground-image
+|path^[2]^ {vbar} image macro^[3]^
+|:page-foreground-image: image:watermark.svg[]
+
 |pagenums^[5]^
 |flag (default: _set_)
 |:pagenums:
@@ -4265,13 +4495,13 @@ These settings override equivalent keys defined in the theme file, where applica
 . 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`).
-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 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 `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.
+. 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.
 . _(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.
@@ -4447,7 +4677,7 @@ When you override a block element, you write PDF objects directly to the Prawn D
 When you override an inline element, you return pseudo-HTML, which is then parsed and converted into PDF objects.
 
 The pseudo-HTML in Asciidoctor PDF evolved from the inline formatting in Prawn, now supporting the following elements: a, br, button, code, color, del, em, font, img, key, mark, span, strong, sub, sup.
-All decimal and hexadecimal character references are supported, as well as the named entities amp, apos, gt, lt, nbsp, and quot (e.g., `\&apos;`.
+All decimal and hexadecimal character references are supported, as well as the named entities amp, apos, gt, lt, nbsp, and quot (e.g., `\&apos;`).
 You can change the font color using `rgb` attribue on the `color` element (e.g., `<color rgb="#ff0000">`) and the font family and size using `name` and `size` attributes on the `font` element, respectively (e.g., `<font name="sans" size="12">`).
 You can also use the `style` attribute on `span` to control the font color, weight, and style using the relevant CSS property names.
 The pseudo-HTML in Asciidoctor PDF also supports the `class` attribute on any element for applying roles from the theme.