asciidoctor-pdf 1.5.0.beta.8 → 1.5.0.rc.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4971b7ad193cc6b81346ac764010d20b46bbfdd66986e601938fcca2cd3929ba
-  data.tar.gz: 86076a5fcb2bc9f6fbb54b8479f04be26a576b207be08ea5b504013dec48ef72
+  metadata.gz: 977d0e8db99f3145ff750ee38a5617ff80ee96e10f20daf0382b18b9f69eaca0
+  data.tar.gz: aa3c20fe2553679f0d59014a306f6d327ba7af0e7700206cb119ee0b7d228e6e
 SHA512:
-  metadata.gz: 940b1a41aa08c0950fb9e609f1ab5cf5c960bee9535cbd5710306b5c7a20d30794ec41fa2ea4b0a78a9c11f5d53262e6bac25417777f6a96e2fded72dd5d121c
-  data.tar.gz: 3017ce6726c7cae78b59394fe12be84587e691375c9e11f196384d42b8a254d2f10201e110503af1447eb456c0e070d90e7d1c0f7099e4e87057d2a4c69606ff
+  metadata.gz: e4a3e16fb9e8b6a0b6118101348efeecbe0a0e1141ec6b7be58691c6f99057cf3a39cee200391a4fac6050b967849ce71942f309665a0c8ab9d52c7e7bdc69f2
+  data.tar.gz: 2e4fedb49b6a0d30b2e6c6cc353d1b69b6aa2cca0688daeda980bdf462dfc387d367e8b8d1402a0f89ff0ca8381ec8c2f1d2e2ef6432b2d20f04a65f9402280d

data/CHANGELOG.adoc

@@ -5,6 +5,55 @@
 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.rc.1 (2020-01-06) - @mojavelinux
+
+* support data URI for SVG image (#1423)
+* account for border offset in width of fragment (#1264)
+* ignore case when sorting index terms (#1405)
+* partition section title (title and subtitle) if `title-separator` document attribute or `separator` block attribute is set (#623)
+* allow page numbering to start after first page of body by assigning an integer to the page_numbering_start_at theme key (#560)
+* allow running content to start after first page of body by assigning an integer to the running_content_start_at theme key (#1455)
+* allow output file to be written to stdout (#1411)
+* implement line highlighting for source blocks when using Rouge as source highlighter (#681)
+* implement line highlighting for source blocks when using Pygments as source highlighter (#1444)
+* indent wrapped lines in source block beyond linenum gutter (#504)
+* don't mangle source block if linenums are enabled and language is not set
+* don't print line number if source block is empty
+* don't apply recto margin to title page if cover is absent unless value of front-cover-image attribute is `~` (#793)
+* expose theme as property on converter
+* add support for unbreakable option on open blocks (#1407) *@mogztter*
+* don't add mailto: prefix to revealed mailto URI when hide-uri-scheme is set (#920)
+* allow theme to set base text decoration width (#1414)
+* allow theme to set font-kerning per category (#1431)
+* allow theme to specify background image for running content (#356)
+* allow theme to specify border for admonition block (#444)
+* allow theme to specify background color for admonition block (#444)
+* allow theme to specify background color and full border for quote and verse blocks (#1309)
+* allow text alignment roles to be used to control alignment of discrete heading
+* allow theme to configure image caption align(ment) to inherit from image align(ment) (#1459)
+* allow theme to confine width of image caption to width of image (#1291)
+* don't apply border to block if border width is not set (or nil)
+* use font color from pygments style for unhighlighted text (#1441)
+* render stem block as raw literal block
+* render stem phrase as monospaced text
+* honor percentage unit on width attribute value on image (#1402)
+* fix crash when capitalizing text that does not contain markup
+* allow custom inline role to control text transform (#1379)
+* convert link macro enclosed in smart quotes
+* allow inline image to be fit within line using fit=line (#711)
+* fix fit=cover for background image when aspect ratio of image is taller than page (#1430)
+* compute and apply line metrics for cells in table head row (#1436)
+* compute and apply line metrics correctly for cells in table body and foot rows (#1436)
+* allow section to override toclevels for self and children using toclevels attribute on section (#734)
+* allocate space for pagenum in toc consistently (#1434)
+* fall back to default theme instead of crashing if specified theme cannot be resolved
+* allow font color to be set on nested span in passthrough content
+* move width and align attributes from font tag to width and align style properties on span tag
+* compute table cell padding correctly when specified as a 4 element array
+* preserve isolated callout on final line of source block
+* fix missing require in asciidoctor-pdf-optimize script (#1467)
+* lock version of ttfunk to 1.5.x
+
 == 1.5.0.beta.8 (2019-11-23) - @mojavelinux
 
 * automatically hyphenate prose using the text-hyphen gem if the `hyphens` document attribute is set (#20)

data/LICENSE.adoc

@@ -1,6 +1,6 @@
 .The MIT License
 ....
-Copyright (C) 2014-2019 OpenDevise Inc. and the Asciidoctor Project
+Copyright (C) 2014-2020 OpenDevise Inc. and the Asciidoctor Project
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/NOTICE.adoc

@@ -1,7 +1,7 @@
 = Asciidoctor PDF
 OpenDevise Inc.; Asciidoctor Project
 
-Copyright (C) 2014-2019 OpenDevise Inc. and the Asciidoctor Project.
+Copyright (C) 2014-2020 OpenDevise Inc. and the Asciidoctor Project.
 
 Please visit the Asciidoctor project site for more information:
 

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.8, 2019-11-23
+v1.5.0.rc.1, 2020-01-06
 // Settings:
 :experimental:
 :idprefix:
@@ -23,7 +23,7 @@ endif::[]
 :project-name: Asciidoctor PDF
 :project-handle: asciidoctor-pdf
 // Variables:
-:release-version: 1.5.0.beta.8
+:release-version: 1.5.0.rc.1
 // URIs:
 :url-asciidoctor: http://asciidoctor.org
 :url-gem: http://rubygems.org/gems/asciidoctor-pdf
@@ -45,63 +45,41 @@ image:https://img.shields.io/gem/v/asciidoctor-pdf.svg[Latest Release, link={url
 image:https://img.shields.io/badge/license-MIT-blue.svg[MIT License, link=#copyright]
 endif::[]
 
-ifdef::env-site[]
 Asciidoctor PDF is a native PDF converter for AsciiDoc.
 It bypasses the requirement to generate an interim format such as DocBook, Apache FO, or LaTeX.
-Instead, you can use it to convert directly from AsciiDoc to PDF.
+Instead, you can use this extension to convert directly from AsciiDoc to PDF.
 Its aim is to take the pain out of creating PDF documents from AsciiDoc.
-endif::[]
-ifndef::env-site[]
-_Lo and behold_, a native PDF converter for AsciiDoc built with {url-asciidoctor}[Asciidoctor] and {url-prawn}[Prawn]! +
-_No more middleman._ +
-_No more DocBook toolchain._ +
-It's AsciiDoc straight to PDF!
 
 toc::[]
 
-== Prawn, the Majestic PDF Generator
-
-{url-project}[{project-name}] is made possible by an amazing Ruby gem named Prawn.
-And what a gem it is!
-
-{url-prawn}[Prawn] is a nimble PDF writer for Ruby.
-More important, it's a hackable platform that offers both high level APIs for the most common needs and low level APIs for bending the document model to accommodate special circumstances.
-
-With Prawn, you can write text, draw lines and shapes and place images _anywhere_ on the page and add as much color as you like.
-In addition, it brings a fluent API and aggressive code re-use to the printable document space.
-
-Here's an example that demonstrates how to use Prawn to create a basic PDF document.
-
-.Create a basic PDF document using Prawn
-[source,ruby]
-----
-require 'prawn'
+== Overview
 
-Prawn::Document.generate 'output.pdf' do
-  text 'Hello, PDF creation!'
-end
-----
+{project-name} is an Asciidoctor extension that converts an AsciiDoc document directly to a PDF document.
+The style and layout of the PDF is controlled by a specialized theme file.
+To the degree possible, this converter supports all the features of AsciiDoc supported by the built-in converters, but there are limits to what Prawn supports and what is possible with PDF in general.
 
-It's that easy.
-And that's just the beginning.
-Skip ahead to <<getting-started,Getting started>> to start putting it use.
+Under the covers, {project-name} uses the Prawn gem (and its extensions, such as prawn-svg and prawn-table) to generate the PDF document.
+{url-prawn}[Prawn] is a general purpose PDF generator for Ruby that features high-level APIs for common needs like setting up the page and inserting images and low-level APIs for positioning and rendering text and graphics.
 
-Prawn is the _killer library_ for PDF generation we've needed to close this critical gap in Asciidoctor.
-It absolutely takes the pain out of creating printable documents.
-Picking up from there, {project-name} takes the pain out of creating PDF documents _from AsciiDoc_.
-endif::[]
+Prawn takes the pain out of creating (basic) PDF documents.
+Likewise, {project-name} takes the pain out of creating PDF documents _directly from AsciiDoc_.
+Skip ahead to <<getting-started,Getting started>> to start putting {project-name} use.
+But don't miss the <<Highlights>> and <<Known Limitations>> sections to understand what's possible.
 
 == Highlights
 
 * Direct AsciiDoc to PDF conversion
 * <<docs/theming-guide.adoc#,Configuration-driven theme (style and layout)>>
-* SVG support
+* Full SVG support
 * PDF document outline (i.e., bookmarks)
+* Title page
 * Table of contents page(s)
 * Document metadata (title, authors, subject, keywords, etc)
 * Internal cross reference links
 * Syntax highlighting with Rouge, Pygments, or CodeRay
+* Page background color or page background image with named scaling
 * Page numbering
+* Double-sided (aka prepress) printing mode (i.e., margins alternate on recto and verso pages)
 * Customizable running content (header and footer)
 * “Keep together” blocks (i.e., page breaks avoided in certain block content)
 * Orphaned section titles avoided
@@ -109,7 +87,22 @@ endif::[]
 * Table border settings honored
 * Font-based icons
 * Custom (TTF) fonts
-* Double-sided printing mode (margins alternate on recto and verso pages)
+* Auto-generated index
+* Automatic hyphenation (when enabled)
+* Compression / optimization of output file
+
+== Known Limitations
+
+* Footnotes are always rendered as endnotes (at end of chapter for books; at end of document for all other doctypes)
+* Table cells that exceed height of a single page will be truncated (see https://github.com/prawnpdf/prawn-table/issues/41[prawn-table#41])
+* Columns cannot be assigned a 0% width (or a width less than the width of a single character); in the same vein, a column cannot be set to autowidth if width of all other columns meets or exceeds 100%; the result is that the converter with throw a Prawn::Errors::CannotFit error
+* An inline image in a table cell will not force the column wider if the width of the image exceeds the width of the column; either reduce the image width using `pdfwidth` or increase the width of the column using `cols`; another solution is to convert the cell to an AsciiDoc table cell (see https://github.com/asciidoctor/asciidoctor-pdf/issues/830)
+* Must use development version of prawn-table for autowidth to work on table head row
+* Must use development version of prawn for error to include font name when requested font style is missing
+* Must use Ruby >= 2.4 for natural cross references to work with non-ASCII titles
+* AsciiDoc table cell leaves padding below last block (due to lack of margin collapsing)
+* Prawn does not support double-wide box drawing glyphs correctly, so box drawings aren't aligned properly in verbatim blocks (see https://github.com/prawnpdf/prawn/issues/1002[prawn#1002]
+* Orphan / widow support is limited; a page break can occur between a section title and its section content, a table caption and the caption, etc.; use a manual page break to avoid
 
 == Prerequisites
 
@@ -390,7 +383,10 @@ To find a complete list of available icons, consult the https://github.com/jesse
 
 == Image Paths
 
-Relative images paths in the document are resolved relative to the value of the `imagesdir` attribute (at the time the converter runs).
+Images are resolved at the time the converter runs.
+That means they need to be located where the converter can find them.
+
+Relative images paths in the document are resolved relative to the value of the `imagesdir` attribute.
 This is effectively the same as how the built-in HTML converter works when the `data-uri` attribute is set.
 The `imagesdir` is blank by default, which means relative images paths are resolved relative to the input document.
 Relative images paths in the theme are resolved relative to the value of the `pdf-themesdir` attribute (which defaults to the directory of the theme file).
@@ -442,6 +438,7 @@ _Only applies to block images._
 
 |width
 |The unitless display width of the image (assumed to be pixels), typically matching the intrinsic width of the image.
+If the value ends in % (not recommended), it's assumed to be the percentage of the available content area width.
 If the width exceeds the content area width, the image is scaled down to the content area width.
 
 |_unspecified_
@@ -456,10 +453,7 @@ If you want a block image to align to the boundaries of the page (not the conten
 This is most useful when using vw units because you can make the image cover the entire width of the page.
 
 Images in running content and page background images also support the `fit` attribute (when specified using the image macro).
-If the value of this attribute is `contain`, the image size is increased or decreased to fill the available space while preserving its aspect ratio.
-If the value of this attribute is `scaled-down`, the image size is first resolved in the normal way, then scaled down further to fit within the available space, if necessary.
-
-If sizing information is not specified for a page background image, the image is automatically scaled to fit the bounds of the page (i.e., `fit=contain`).
+See <<Background Image Sizing>> for details.
 
 === Using the pdfwidth Attribute
 
@@ -499,6 +493,8 @@ Inline images can be sized in much the same way as block images (using the pdfwi
 * The image will be scaled down, if necessary, to fit the width and height of the content area.
 * Inline images do not currently support a default width controlled from the theme.
 
+To confine the inline image to the height of the line while preserving the aspect ratio, use the attribute `fit=line`.
+
 If the resolved height of the image is less than or equal to 1.5 times the line height, the image won't disrupt the line height and is centered vertically in the line.
 This is done to maximize the use of available space.
 Once the resolved height exceeds this amount, the height of the line is increased (by increasing the font size of the invisible placeholder text) to accommodate the image.
@@ -513,7 +509,7 @@ 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 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`.
+If the `fit` attribute is not specified, it defaults to `contain` (i.e., the image is automatically scaled to fit the bounds of the page).
 
 [cols="1s,3"]
 |===
@@ -1005,7 +1001,7 @@ To help develop {project-name}, or to simply use the development version, refer
 
 == Copyright
 
-Copyright (C) 2014-2019 OpenDevise Inc. and the Asciidoctor Project.
+Copyright (C) 2014-2020 OpenDevise Inc. and the Asciidoctor Project.
 Free use of this software is granted under the terms of the MIT License.
 
 For the full text of the license, see the <<LICENSE.adoc#,LICENSE>> file.

data/asciidoctor-pdf.gemspec

@@ -35,6 +35,8 @@ Gem::Specification.new do |s|
 
   s.add_runtime_dependency 'asciidoctor', '>= 1.5.3', '< 3.0.0'
   s.add_runtime_dependency 'prawn', '~> 2.2.0'
+  # NOTE ttfunk 1.6 generates TT instructions ghostscript cannot process, so lock the version of ttfunk
+  s.add_runtime_dependency 'ttfunk', ['~> 1.5.0'], ['>= 1.5.1']
   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.30.0'
@@ -51,7 +53,9 @@ Gem::Specification.new do |s|
   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.11.0'
+  s.add_development_dependency 'rouge', '~> 3.14.0'
+  s.add_development_dependency 'rubocop', '~> 0.78.0'
+  s.add_development_dependency 'rubocop-rspec', '~> 1.37.0'
   s.add_development_dependency 'coderay', '~> 1.1.0'
   s.add_development_dependency 'chunky_png', '~> 1.3.0'
 end

data/bin/asciidoctor-pdf-optimize

@@ -5,7 +5,7 @@ optimizer = File.absolute_path '../lib/asciidoctor/pdf/optimizer.rb', __dir__
 if File.exist? optimizer
   require optimizer
 else
-  require 'asciidoctor-pdf/optimizer'
+  require 'asciidoctor/pdf/optimizer'
 end
 
 args = ARGV.dup

data/data/themes/base-theme.yml

@@ -25,13 +25,14 @@ role_line-through_text_decoration: line-through
 role_underline_text_decoration: underline
 role_big_font_size: 14
 role_small_font_size: 10
+role_subtitle_font_size: 0.8em
 button_content: '[%s]'
 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
+mark_border_offset: 1
 link_font_color: '0000EE'
 literal_font_family: Courier
 heading_font_style: bold
@@ -74,10 +75,10 @@ admonition_padding: [0, 12, 0, 12]
 admonition_label_font_style: bold
 admonition_label_text_transform: uppercase
 blockquote_border_color: 'EEEEEE'
-blockquote_border_width: 4
+blockquote_border_left_width: 4
 blockquote_padding: [6, 12, -6, 14]
 verse_border_color: 'EEEEEE'
-verse_border_width: 4
+verse_border_left_width: 4
 verse_padding: [6, 12, -6, 14]
 code_font_family: Courier
 code_font_size: 10.8

data/data/themes/default-theme.yml

@@ -61,6 +61,9 @@ role:
     font_size: $base_font_size_large
   small:
     font_size: $base_font_size_small
+  subtitle:
+    font_size: 0.8em
+    font_color: 999999
 # FIXME vertical_rhythm is weird; we should think in terms of ems
 #vertical_rhythm: $base_line_height_length * 2 / 3
 # correct line height for Noto Serif metrics (comes with built-in line height)
@@ -80,14 +83,14 @@ button:
 key:
   background_color: f5f5f5
   border_color: cccccc
-  border_offset: 1.5
+  border_offset: 2
   border_radius: 2
-  border_width: 0.375
+  border_width: 0.5
   font_family: $literal_font_family
   separator: "\u202f+\u202f"
 mark:
   background_color: ffff00
-  border_offset: 0.5
+  border_offset: 1
 menu:
   caret_content: " <font size=\"1.15em\"><color rgb=\"b12146\">\u203a</color></font> "
 heading:
@@ -170,15 +173,17 @@ admonition:
 blockquote:
   font_size: $base_font_size_large
   border_color: $base_border_color
-  border_width: 5
+  border_width: 0
+  border_left_width: 5
   # FIXME disable negative padding bottom once margin collapsing is implemented
-  padding: [0, $horizontal_rhythm, $block_margin_bottom * -0.75, $horizontal_rhythm + $blockquote_border_width / 2]
+  padding: [0, $horizontal_rhythm, $block_margin_bottom * -0.75, $horizontal_rhythm + $blockquote_border_left_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
+  border_left_width: $blockquote_border_left_width
   padding: $blockquote_padding
   cite_font_size: $blockquote_cite_font_size
   cite_font_color: $blockquote_cite_font_color

data/docs/theming-guide.adoc

@@ -1030,13 +1030,12 @@ This role can be used as follows:
 == [.heading-code]`SELECT` clause
 ----
 
-The converter provides several predefined roles.
+The converter provides several predefined roles, which can can all be redefined.
 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 `subtitle` role is used to configure the font properties of the subtitle of a section title.
 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.
+You'll need to define these color roles in your theme if you'd like to make use of them when converting to PDF.
 
 [cols="3,4,5l"]
 |===
@@ -1213,7 +1212,7 @@ See <<Title Page>> for details.
   size: Letter
 
 |numbering-start-at^[5]^
-|title {vbar} toc {vbar} body +
+|title {vbar} toc {vbar} body {vbar} Integer +
 (default: body)
 |page:
   numbering-start-at: toc
@@ -1230,8 +1229,11 @@ 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.
+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.
 . 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 an integer, page numbering will start at the specified page of the body (i.e., 1 is first page, 2 is second page, etc.)
 
 [#keys-base]
 === Base
@@ -1284,7 +1286,7 @@ NOTE: While it's common to define additional keys in this category (e.g., `base-
   font-family: Noto Serif
 
 |font-kerning
-|normal {vbar} default +
+|normal {vbar} none +
 (default: normal)
 |base:
   font-kerning: none
@@ -1338,6 +1340,12 @@ NOTE: While it's common to define additional keys in this category (e.g., `base-
   line-height: >
     $base-line-height-length /
     $base-font-size
+
+|text-decoration-width
+|<<values,Number>> +
+(default: 1)
+|base:
+  text-decoration-width: 0.5
 |===
 
 . The `text-transform` key cannot be set globally.
@@ -1518,6 +1526,12 @@ The keys in this category control the style of most headings, including part tit
 |heading:
   font-family: Noto Serif
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|heading:
+  font-kerning: none
+
 // NOTE: heading-font-size is overridden by h<n>-font-size in base theme
 //|font-size
 //|<<values,Number>> +
@@ -1626,6 +1640,12 @@ The keys in this category control the style of most headings, including part tit
 |heading:
   h4-font-family: Roboto
 
+|font-kerning
+|normal {vbar} none +
+(default: $heading-font-kerning)
+|heading:
+  h3-font-kerning: none
+
 |font-size^[1]^
 |<<values,Number>> +
 (default: <1>=24; <2>=18; <3>=16; <4>=14; <5>=12; <6>=10)
@@ -1736,6 +1756,12 @@ TIP: The title page can be disabled for the book doctype by setting the `notitle
 |title-page:
   font-family: Noto Serif
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|title-page:
+  font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
@@ -1806,6 +1832,13 @@ TIP: The title page can be disabled for the book doctype by setting the `notitle
   title:
     font-family: Noto Serif
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|title-page:
+  title:
+    font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: 18)
@@ -1878,6 +1911,13 @@ TIP: The title page can be disabled for the book doctype by setting the `notitle
   subtitle:
     font-family: Noto Serif
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|title-page:
+  subtitle:
+    font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: 14)
@@ -1961,6 +2001,13 @@ TIP: The title page can be disabled for the book doctype by setting the `notitle
   authors:
     font-family: Noto Serif
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|title-page:
+  authors:
+    font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
@@ -2026,6 +2073,13 @@ TIP: The title page can be disabled for the book doctype by setting the `notitle
   revision:
     font-family: Noto Serif
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|title-page:
+  revision:
+    font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
@@ -2169,7 +2223,7 @@ In addition to the generic caption category, each of these keys can be set on th
 
 3+|[#key-prefix-caption]*Key Prefix:* <<key-prefix-caption,caption>>
 
-|align
+|align^[1]^
 |<<text-alignments,Text alignment>> +
 (default: left)
 |caption:
@@ -2187,6 +2241,12 @@ In addition to the generic caption category, each of these keys can be set on th
 |caption:
   font-family: M+ 1mn
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|caption:
+  font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
@@ -2218,6 +2278,9 @@ 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.
+The value `inherit` resolves to the alignment of the block image.
+
 [#keys-code]
 === Code
 
@@ -2295,7 +2358,15 @@ The keys in this category are used to control the style of literal, listing and
 |code:
   padding: 11
 
-3+|[#key-prefix-code-linenum]*Key Prefix:* <<key-prefix-code-linenum,code-linenum>>^[2]^
+3+|[#key-prefix-code-highlight]*Key Prefix:* <<key-prefix-code-highlight,code-highlight>>^[2]^
+
+|background-color
+|<<colors,Color>> +
+(default: #FFFFCC)
+|code:
+  highlight-background-color: #ffff00
+
+3+|[#key-prefix-code-linenum]*Key Prefix:* <<key-prefix-code-linenum,code-linenum>>^[3]^
 
 |font-color
 |<<colors,Color>> +
@@ -2305,8 +2376,10 @@ The keys in this category are used to control the style of literal, listing and
 |===
 
 . 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.
+Otherwise, the styles are controlled by the source highlighter theme.
 . The code-linenum category only applies when using Pygments as the source highlighter.
-Otherwise, the style is controlled by the source highlighter theme.
+Otherwise, the styles are controlled by the source highlighter theme.
 
 [#keys-callout-numbers]
 === Callout Numbers
@@ -2331,6 +2404,12 @@ The keys in this category are used to control the style of callout numbers (i.e.
 |conum:
   font-family: M+ 1mn
 
+|font-kerning^[2]^
+|normal {vbar} none +
+(default: _inherit_)
+|conum:
+  font-kerning: none
+
 |font-size^[2]^
 |<<values,Number>> +
 (default: _inherit_)
@@ -2357,7 +2436,7 @@ The keys in this category are used to control the style of callout numbers (i.e.
 |===
 
 . Currently, the font must contain the circle numbers starting at glyph U+2460.
-. font-family, font-size, font-style, and line-height are only used for markers in a colist.
+. 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.
 The glyphs can be specified as a comma-separated list of ranges, where the range values are Unicode numbers (e.g., \u2460).
@@ -2545,11 +2624,23 @@ The keys in this category control the arrangement and style of quote blocks.
 
 3+|[#key-prefix-blockquote]*Key Prefix:* <<key-prefix-blockquote,blockquote>>
 
+|background-color
+|<<colors,Color>> +
+(default: _not set_)
+|blockquote:
+  background-color: #dddddd
+
 |border-width^[1]^
 |<<values,Number>> +
+(default: 0)
+|blockquote:
+  border-width: 0.5
+
+|border-left-width^[1]^
+|<<values,Number>> +
 (default: 4)
 |blockquote:
-  border-width: 5
+  border-left-width: 5
 
 |border-color^[1]^
 |<<colors,Color>> +
@@ -2569,6 +2660,12 @@ The keys in this category control the arrangement and style of quote blocks.
 |blockquote:
   font-family: Noto Serif
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|blockquote:
+  font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
@@ -2616,6 +2713,13 @@ The keys in this category control the arrangement and style of quote blocks.
   cite:
     font-family: Noto Serif
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|blockquote:
+  cite:
+    font-kerning: none
+
 |font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
@@ -2631,7 +2735,8 @@ The keys in this category control the arrangement and style of quote blocks.
     text-transform: uppercase
 |===
 
-. Only applies to the left side.
+. 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]
 === Verse
@@ -2644,11 +2749,23 @@ The keys in this category control the arrangement and style of verse blocks.
 
 3+|[#key-prefix-verse]*Key Prefix:* <<key-prefix-verse,verse>>
 
+|background-color
+|<<colors,Color>> +
+(default: _not set_)
+|verse:
+  background-color: #dddddd
+
 |border-width^[1]^
 |<<values,Number>> +
+(default: 0)
+|verse:
+  border-width: 0.5
+
+|border-left-width^[1]^
+|<<values,Number>> +
 (default: 4)
 |verse:
-  border-width: 5
+  border-left-width: 5
 
 |border-color^[1]^
 |<<colors,Color>> +
@@ -2668,6 +2785,12 @@ The keys in this category control the arrangement and style of verse blocks.
 |verse:
   font-family: M+ 1mn
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|verse:
+  font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
@@ -2715,6 +2838,13 @@ The keys in this category control the arrangement and style of verse blocks.
   cite:
     font-family: Noto Serif
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|verse:
+  cite:
+    font-kerning: none
+
 |font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
@@ -2730,7 +2860,8 @@ The keys in this category control the arrangement and style of verse blocks.
     text-transform: uppercase
 |===
 
-. Only applies to the left side.
+. 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-sidebar]
 === Sidebar
@@ -2779,6 +2910,12 @@ The keys in this category control the arrangement and style of sidebar blocks.
 |sidebar:
   font-family: M+ 1p
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|sidebar:
+  font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
@@ -2826,6 +2963,13 @@ The keys in this category control the arrangement and style of sidebar blocks.
   title:
     font-family: Noto Serif
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|sidebar:
+  title:
+    font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
@@ -2895,6 +3039,12 @@ The keys in this category control the arrangement and style of example blocks.
 |example:
   font-family: M+ 1p
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|example:
+  font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
@@ -2961,6 +3111,12 @@ The keys in this category control the arrangement and style of admonition blocks
 |admonition:
   font-family: Noto Sans
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|admonition:
+  font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
@@ -3030,6 +3186,13 @@ The keys in this category control the arrangement and style of admonition blocks
   label:
     font-family: M+ 1p
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|admonition:
+  label:
+    font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
@@ -3158,6 +3321,13 @@ The keys in this category control the arrangement of block images.
   alt:
     font-family: Courier
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|image:
+  alt:
+    font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
@@ -3171,6 +3341,20 @@ The keys in this category control the arrangement of block images.
 |iamge:
   alt:
     font-style: italic
+
+|caption-align
+|<<text-alignments,Text alignment>> {vbar} inherit +
+(default: $caption-align)
+|image:
+  caption:
+    align: inherit
+
+|caption-max-width^[5]^
+|fit-content {vbar} none +
+(default: none)
+|image:
+  caption:
+    max-width: fit-content
 |===
 
 . Only applies to block images.
@@ -3179,6 +3363,7 @@ If specified, this value takes precedence over the value of the `width` attribut
 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.
 
 [#keys-svg]
 === SVG
@@ -3223,6 +3408,12 @@ The keys in this category control the styling of lead paragraphs.
 |lead:
   font-family: M+ 1p
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|lead:
+  font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: 13.5)
@@ -3318,6 +3509,13 @@ The keys in this category control the arrangement and style of the abstract.
   title:
     font-family: Noto Serif
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|abstract:
+  title:
+    font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: $base-font-size)
@@ -3423,6 +3621,12 @@ The subject stop can be customized using the `subject-stop` attribute.
 |description-list:
   term-font-family: Noto Serif
 
+|term-font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|description-list:
+  term-font-kerning: none
+
 |term-font-size
 |<<values,Number>> +
 (default: _inherit_)
@@ -3646,6 +3850,12 @@ The keys in this category control the arrangement and style of tables and table
 |table:
   font-family: Helvetica
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|table:
+  font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
@@ -3727,6 +3937,13 @@ The keys in this category control the arrangement and style of tables and table
   head:
     font-family: Noto Serif
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|table:
+  head:
+    font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: $table-font-size)
@@ -3871,7 +4088,7 @@ Since Asciidoctor 2, table stripes are not enabled by default (e.g., `stripes=no
 [#keys-footnotes]
 === Footnotes
 
-The keys in this catagory control the style the list of footnotes at the end of the chapter (book) or document (otherwise).
+The keys in this catagory control the style of the footnotes list at the end of the chapter (book) or document (otherwise).
 If the `footnotes-title` attribute is specified, it is styled as a block caption.
 The styling of the links is controlled by the global link styles.
 
@@ -3941,6 +4158,12 @@ The keys in this category control the arrangement and style of the table of cont
 |toc:
   font-family: Noto Serif
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|toc:
+  font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
@@ -4014,25 +4237,31 @@ The keys in this category control the arrangement and style of the table of cont
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |toc:
-  font-family: Noto Serif
+  h2-font-family: Noto Serif
+
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|toc:
+  h3-font-kerning: none
 
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
 |toc:
-  font-size: 9
+  h3-font-size: 9
 
 |font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
 |toc:
-  font-style: italic
+  h2-font-style: italic
 
 |text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
 |toc:
-  text-transform: uppercase
+  h3-text-transform: uppercase
 
 3+|[#key-prefix-toc-title]*Key Prefix:* <<key-prefix-toc-title,toc-title>>
 
@@ -4057,6 +4286,13 @@ The keys in this category control the arrangement and style of the table of cont
   title:
     font-family: Noto Serif
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|toc:
+  title:
+    font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: $heading-h2-font-size)
@@ -4136,6 +4372,12 @@ To avoid this problem, reduce the height of the running content periphery or mak
 |header:
   background-color: #eeeeee
 
+|background-image
+|image macro +
+(default: _not set_)
+|header:
+  background-image: image:running-content.svg[fit=contain]
+
 |border-color
 |<<colors,Color>> +
 (default: _not set_)
@@ -4166,6 +4408,12 @@ To avoid this problem, reduce the height of the running content periphery or mak
 |header:
   font-family: Noto Serif
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|header:
+  font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
@@ -4249,6 +4497,12 @@ To avoid this problem, reduce the height of the running content periphery or mak
 |footer:
   background-color: #eeeeee
 
+|background-image
+|image macro +
+(default: _not set_)
+|footer:
+  background-image: image:running-content.svg[fit=contain]
+
 |border-color
 |<<colors,Color>> +
 (default: _not set_)
@@ -4279,6 +4533,12 @@ To avoid this problem, reduce the height of the running content periphery or mak
 |footer:
   font-family: Noto Serif
 
+|font-kerning
+|normal {vbar} none +
+(default: _inherit_)
+|footer:
+  font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: _inherit_)
@@ -4357,7 +4617,7 @@ 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 +
+|title {vbar} toc {vbar} body {vbar} Integer +
 (default: body)
 |running-content:
   start-at: toc
@@ -4373,6 +4633,7 @@ Where the page sides fall in relation to the physical or printed page number is
 . `<position>` can be `left`, `center` or `right`.
 . 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 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.
 
@@ -4764,7 +5025,10 @@ recto page margin:: [0.5in, *0.59in*, 0.67in, *0.75in*]
 verso page margin:: [0.5in, *0.75in*, 0.67in, *0.59in*]
 
 The page margins alternate between recto and verso.
-The first page in the document is a recto page.
+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.
 
 === Automatic Facing Pages
 
@@ -4779,7 +5043,7 @@ Other "`facing`" pages may be added in the future.
 
 It's possible to disable the automatic facing feature for a given part or chapter.
 This can be done by adding the nonfacing option to the section node.
-When the nonfacing option is present, the part or chapter title will be placed on the following page.
+When the nonfacing option is present, the part or chapter title will be placed on the next adjacent page rather than the next facing page.
 
 [source,asciidoc]
 ----