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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 032a48f8d8cda0a29e3e7c3249cb2c74aaccc0f910adcb4607ef30733b70b948
-  data.tar.gz: 1e995ab8292dedab7deef06867f5da0ca41570be9abe88e6be81af999fe4965b
+  metadata.gz: 39073eb8a1bb2d5cac70b6909884e9c7e28813919295d5058c4471ea5805f103
+  data.tar.gz: e527403b220a3969d0398e9a6e3b4e3101fb9a55eafe9dacbe429b6abd8399ee
 SHA512:
-  metadata.gz: 945a1f3e02ee7c08e7a08f5566dc9bf79aac394674f44665285cf40f7fbaf1bd16c2b2d491b37ad467a5e718c23fa311e245b46f4d46de3f1fe54badf83a69e9
-  data.tar.gz: e3d6c083f0b4ecf716a2264127f523f4a8febfa0a2915838c31f67a4d2cf5201b2178d15a5e6b057528bad4d7b5f685cbc69a8dcaa44538359d2a27532ab8a4c
+  metadata.gz: 15142864ee5aa1ab97c6ec2c5c82793532528b10ebe093a3af8514c313c0c3f06b4a3aabc2c1d246546991332a6de7bd8772843373fd715a96b4d38d5f563228
+  data.tar.gz: 3c3d20aebe612eb3869fc5f38b8af536e5bb51ea95765cbe1c61515e36d03e0d62dbe97262629b581524a6d8783cb886c8bfc4832c6e5b4dab0dd3a4e4624a17

data/CHANGELOG.adoc

@@ -5,6 +5,32 @@
 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.2 (2019-07-30) - @mojavelinux
+
+* only apply title page background image to the title page (#1144)
+* make sure title page background or color (and only title page background or color) gets applied to title page even when page has already been created (#1144)
+* fix crash when image_width is defined in theme (#995)
+* fix crash when toc is enabled and toc-title attribute is unset
+* correctly map legacy Font Awesome icon names when icon set is not specified (#1157)
+* coerce color values in theme that contain uppercase letters (#1149)
+* prevent table alignment from modifying margins of subsequent pages; only align table if width is less than bounds (#1170)
+* ensure base font color is set
+* use more robust mechanism to detect an empty page; tare content stream after adding page background color or image
+* ignore pdf-themesdir unless pdf-theme is specified (#1167)
+* allow theme to control glyphs used for conums (#133)
+* allow theme to control background and border of inline kbd (#313, #1004)
+* add support for link on image in running content (#1002)
+* allow theme to disable font kerning
+* add support for default theme alignment for tables (#1164)
+* add theming support to (inline) roles on phrases (#368)
+* allow theme to customize style of titles in running content (#1044)
+* add support for the built-in big and small roles on phrases (#459)
+* route AFM font warning through Asciidoctor logger
+* upgrade code font (M+ 1mn) to TESTFLIGHT-63a
+* include all alphanumeric characters in code font (mplus1mn) (#282)
+* report clearer error message when theme can't be found or loaded
+* document how to prepare a TTF font to work best with Asciidoctor PDF (#297)
+
 == 1.5.0.beta.1 (2019-07-08) - @mojavelinux
 
 * rename pdf-style and pdf-stylesdir attributes to pdf-theme and pdf-themesdir, respectively (while still honoring the old names for compatibility) (#1127)

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.1, 2019-07-08
+v1.5.0.beta.2, 2019-07-30
 // Settings:
 :experimental:
 :idprefix:
@@ -24,7 +24,7 @@ endif::[]
 :project-name: Asciidoctor PDF
 :project-handle: asciidoctor-pdf
 // Variables:
-:release-version: 1.5.0.beta.1
+:release-version: 1.5.0.beta.2
 // URIs:
 :uri-asciidoctor: http://asciidoctor.org
 :uri-gem: http://rubygems.org/gems/asciidoctor-pdf

data/asciidoctor-pdf.gemspec

@@ -40,7 +40,7 @@ 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.3.0'
+  s.add_runtime_dependency 'prawn-icon', '~> 2.4.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'
@@ -48,8 +48,8 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'treetop', '~> 1.5.0'
 
   s.add_development_dependency 'rake', '~> 12.3.0'
-  # Asciidoctor PDF supports Rouge >= 2; Rouge 3.4.1 emits a superfluous warning in verbose mode
-  s.add_development_dependency 'rouge', '~> 3.4.0', '!= 3.4.1'
+  # 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 'rspec', '~> 3.8.0'
   s.add_development_dependency 'pdf-inspector', '~> 1.3.0'
   s.add_development_dependency 'chunky_png', '~> 1.3.0'

data/bin/asciidoctor-pdf

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 if File.file?(asciidoctor_pdf = (File.expand_path '../../lib/asciidoctor/pdf.rb', __FILE__))
   require asciidoctor_pdf

data/data/fonts/ABOUT-mplus1mn-subset

@@ -0,0 +1,24 @@
+M+ fonts are generated from the M+ outline fonts TESTFLIGHT 63a retrieved from http://mplus-fonts.osdn.jp/mplus-outline-fonts/download/index-en.html.
+
+The following changes were made using fontforge to produce mplus1mn-*-ascii.ttf fonts:
+
+* Subsetted to include (ascii variant):
+ ** Non-visible Characters (U+00a0)
+ ** Basic Latin (U+0020–U+007e)
+ ** Enclosed Numbers (U+2460–U+2473, U+2776–U+277f, U+24eb–U+24f4) (M+ 1mn Regular only)
+ ** Box Drawing Symbols (U+2500–U+257f)
+* Subsetted to include (subset variant):
+ ** Non-visible Characters (U+00a0)
+ ** Basic Latin (U+0020–U+007e)
+ ** Latin-1 Supplement (U+00a0–U+00fd)
+ ** Latin Extended-A (U+0100–U+017f)
+ ** Greek Alphabet (U+0391–U+03c9)
+ ** Cyrillic (U+0400–U+04ff)
+ ** Assorted Symbols (U+20ac)
+ ** Enclosed Numbers (U+2460–U+2473, U+2776–U+277f, U+24eb–U+24f4) (mplus1mn-regular only)
+ ** Box Drawing Symbols (U+2500–U+257f)
+* Added BOM (U+feff) and line feed (U+000a) characters (from blank)
+* Generated old-style kern table (neither Apple or OpenType) (required to make kerning work in Prawn) (flags: 0x90)
+* Removed Truetype instructions (information not used by Prawn) (flags: 0x08)
+* Generated with PS Glyph Names option enabled (didn't use 0x04 flag)
+* Generate flags used, in total: 0x90 + 0x08

data/data/fonts/ABOUT-mplus1p-subset

@@ -0,0 +1,25 @@
+M+ fonts are generated from the M+ outline fonts TESTFLIGHT 63a retrieved from http://mplus-fonts.osdn.jp/mplus-outline-fonts/download/index-en.html.
+
+The following changes were made using fontforge to produce mplus1p-regular-fallback.ttf font:
+
+* Subsetted to include:
+ ** Non-visible Characters (U+00a0)
+ ** Basic Latin (U+0020–U+007e)
+ ** Latin-1 Supplement (U+00a0–U+00fd)
+ ** Latin Extended-A (U+0100–U+017f)
+ ** Latin Extended-B (U+0180–U+024f)
+ ** IPA (U+0259, U+02b0–U+02ff)
+ ** Greek (U+0370–U+03ff)
+ ** Cyrillic (U+0400–U+04ff)
+ ** Vietnamese (U+01a0–U01b0, U+1ea0–U1ef9)
+ ** CJK (U+4e00–U+9fff, U+3000–U+303f) (mostly Japanese, limited selection based on what M+ supports)
+ ** Mathematical Operators (U+2200–U+22ff)
+ ** General Punctuation (U+2000–U203a)
+ ** Geometric Shapes (U+25a0–U25ff)
+ ** Assorted Symbols (U+20ac, U+2122, U+21d0–U+21d5, U+2190–U+2195, U+2610–U+2611, U+2713)
+* Added BOM (U+feff), hair space (U+200a), zero-width space (U+200b) and line feed (U+000a) characters (from blank)
+* Manually added non-breaking hyphen (U+2011) from hyphen (U+002d)
+* Generated old-style kern table (neither Apple or OpenType) (required to make kerning work in Prawn) (flags: 0x90)
+* Removed Truetype instructions (information not used by Prawn) (flags: 0x08)
+* Generated with PS Glyph Names option enabled (didn't use 0x04 flag)
+* Generate flags used, in total: 0x90 + 0x08

data/data/fonts/ABOUT-notoserif-subset

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

data/data/fonts/{LICENSE-mplus-testflight-58 → LICENSE-mplus}

@@ -1,4 +1,4 @@
-M+ FONTS                                Copyright (C) 2002-2014 M+ FONTS PROJECT
+M+ FONTS                                Copyright (C) 2002-2019 M+ FONTS PROJECT
 
 -
 
@@ -13,4 +13,4 @@ or without modification, either commercially or noncommercially.
 THESE FONTS ARE PROVIDED "AS IS" WITHOUT WARRANTY.
 
 
-http://mplus-fonts.sourceforge.jp/mplus-outline-fonts/
+http://mplus-fonts.osdn.jp

data/data/themes/base-theme.yml

@@ -21,9 +21,13 @@ 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
+role_small_font_size: 10
 button_content: '[%s]'
 button_font_family: Courier
 button_font_style: bold
+key_font_family: Courier
+key_font_style: italic
 link_font_color: '0000EE'
 literal_font_family: Courier
 heading_font_style: bold
@@ -68,12 +72,13 @@ blockquote_border_color: 'EEEEEE'
 blockquote_border_width: 4
 blockquote_padding: [6, 12, -6, 14]
 code_font_family: Courier
-code_font_size: 10.5
+code_font_size: 10.8
 code_line_height: 1.2
 code_padding: 9
 code_border_color: 'EEEEEE'
 code_border_width: 0.5
 conum_line_height: 1.15
+conum_glyphs: circled
 example_background_color: 'FFFFFF'
 example_border_color: 'EEEEEE'
 example_border_width: 0.5
@@ -101,3 +106,5 @@ thematic_break_border_style: solid
 thematic_break_border_width: 0.5
 toc_indent: 15
 toc_line_height: 1.4
+footnotes_font_size: 9
+footnotes_item_space: 3

data/data/themes/default-theme.yml

@@ -8,10 +8,10 @@ font:
       bold_italic: notoserif-bold_italic-subset.ttf
     # M+ 1mn supports ASCII and the circled numbers used for conums
     M+ 1mn:
-      normal: mplus1mn-regular-ascii-conums.ttf
-      bold: mplus1mn-bold-ascii.ttf
-      italic: mplus1mn-italic-ascii.ttf
-      bold_italic: mplus1mn-bold_italic-ascii.ttf
+      normal: mplus1mn-regular-subset.ttf
+      bold: mplus1mn-bold-subset.ttf
+      italic: mplus1mn-italic-subset.ttf
+      bold_italic: mplus1mn-bold_italic-subset.ttf
 page:
   background_color: ffffff
   layout: portrait
@@ -51,6 +51,12 @@ base:
   border_color: eeeeee
   border_radius: 4
   border_width: 0.5
+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
 #vertical_rhythm: $base_line_height_length * 2 / 3
 # correct line height for Noto Serif metrics (comes with built-in line height)
@@ -58,15 +64,23 @@ vertical_rhythm: $base_line_height_length
 horizontal_rhythm: $base_line_height_length
 # QUESTION should vertical_spacing be block_spacing instead?
 vertical_spacing: $vertical_rhythm
-button:
-  content: "[\u2009%s\u2009]"
-  font_style: bold
 link:
   font_color: 428bca
 # literal is currently used for inline monospaced in prose and table cells
 literal:
   font_color: b12146
   font_family: M+ 1mn
+button:
+  content: "[\u2009%s\u2009]"
+  font_style: bold
+key:
+  background_color: f5f5f5
+  border_color: cccccc
+  border_offset: 1.5
+  border_radius: 2
+  border_width: 0.375
+  font_family: $literal_font_family
+  separator: "\u202f+\u202f"
 menu:
   caret_content: " <font size=\"1.15em\"><color rgb=\"b12146\">\u203a</color></font> "
 heading:
@@ -172,6 +186,7 @@ conum:
   font_color: $literal_font_color
   font_size: $base_font_size
   line_height: 4 / 3
+  glyphs: circled
 example:
   border_color: $base_border_color
   border_radius: $base_border_radius

data/data/themes/default-with-fallback-font-theme.yml

@@ -7,10 +7,10 @@ font:
       italic: notoserif-italic-subset.ttf
       bold_italic: notoserif-bold_italic-subset.ttf
     M+ 1mn:
-      normal: mplus1mn-regular-ascii-conums.ttf
-      bold: mplus1mn-bold-ascii.ttf
-      italic: mplus1mn-italic-ascii.ttf
-      bold_italic: mplus1mn-bold_italic-ascii.ttf
+      normal: mplus1mn-regular-subset.ttf
+      bold: mplus1mn-bold-subset.ttf
+      italic: mplus1mn-italic-subset.ttf
+      bold_italic: mplus1mn-bold_italic-subset.ttf
     # M+ 1p supports Latin, Latin-1 Supplement, Latin Extended, Greek, Cyrillic, Vietnamese, Japanese & an assortment of symbols
     # It also provides arrows for ->, <-, => and <= replacements in case these glyphs are missing from font
     M+ 1p Fallback:

data/docs/theming-guide.adoc

@@ -4,6 +4,7 @@ Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
 :idprefix:
 :idseparator: -
 :toc: preamble
+:experimental:
 ifndef::env-github[:icons: font]
 ifdef::env-github[]
 :outfilesuffix: .adoc
@@ -19,6 +20,8 @@ endif::[]
 :conum-guard-yaml: #
 ifndef::icons[:conum-guard-yaml: # #]
 ifdef::backend-pdf[:conum-guard-yaml: # #]
+:url-fontforge: https://fontforge.github.io/en-US/
+:url-fontforge-scripting: https://fontforge.github.io/en-US/documentation/scripting/
 
 ////
 Topics remaining to document:
@@ -31,12 +34,12 @@ 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.
 
-IMPORTANT: If you're creating a custom theme, you're expected to supply your own fonts.
-We recognize this can be a major obstacle when you're starting out.
-Therefore, your other option is to simply redeclare the fonts from the https://github.com/asciidoctor/asciidoctor-pdf/blob/master/data/themes/default-theme.yml[default theme] in the <<Custom Fonts,font catalog>>.
-Asciidoctor PDF will then resolve the fonts that are bundled with the gem.
+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>>.
 
-WARNING: If you don't declare your own fonts, the built-in (AFM) fonts declared in https://github.com/asciidoctor/asciidoctor-pdf/blob/master/data/themes/base-theme.yml[base theme] will be used instead.
+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.
 See the <<Built-In (AFM) Fonts>> section to learn more about these limitations.
 
@@ -186,23 +189,23 @@ Also note the presence of the colon (`:`) after each key name.
 The value of a key may be one of the following types:
 
 * String
-  - Font family name (e.g., Roboto)
-  - Font style (normal, bold, italic, bold_italic)
-  - Alignment (left, center, right, justify)
-  - Color as hex string (e.g., 'ff0000', #ff0000, or '#ff0000')
-  - Image path
-  - Enumerated type (where specified)
-  - Text content (where specified)
+ ** Font family name (e.g., Roboto)
+ ** Font style (normal, bold, italic, bold_italic)
+ ** Alignment (left, center, right, justify)
+ ** Color as hex string (e.g., 'ff0000', #ff0000, or '#ff0000')
+ ** Image path
+ ** Enumerated type (where specified)
+ ** Text content (where specified)
 * Null (clears any previously assigned value)
-  - _empty_ (i.e., no value specified)
-  - null
-  - ~
+ ** _empty_ (i.e., no value specified)
+ ** null
+ ** ~
 * Number (integer or float) with optional units (default unit is points)
 * Array
-  - Color as RGB array (e.g., [51, 51, 51])
-  - Color CMYK array (e.g., [50, 100, 0, 0])
-  - Margin (e.g., [1in, 1in, 1in, 1in])
-  - Padding (e.g., [1in, 1in, 1in, 1in])
+ ** Color as RGB array (e.g., [51, 51, 51])
+ ** Color CMYK array (e.g., [50, 100, 0, 0])
+ ** Margin (e.g., [1in, 1in, 1in, 1in])
+ ** Padding (e.g., [1in, 1in, 1in, 1in])
 * Variable reference (e.g., $base_font_color or $base-font-color)
 * Math expression
 
@@ -687,7 +690,7 @@ For anything outside of that, PDF is BYOF (Bring Your Own Font).
 Even though the built-in fonts require the content to be encoded in WINANSI, _you still type your AsciiDoc document in UTF-8_.
 Asciidoctor PDF encodes the content into WINANSI when building the PDF.
 
-CAUTION: Built-in fonts do not use the <<fallback-fonts,fallback fonts>>.
+WARNING: Built-in (AFM) fonts do not use the <<fallback-fonts,fallback fonts>>.
 In order for the fallback font to kick in, you must be using a TrueType font.
 
 .WINANSI Encoding Behavior
@@ -726,7 +729,7 @@ Also provides the circuled numbers used in callouts.
 http://mplus-fonts.osdn.jp/mplus-outline-fonts/design/index-en.html#mplus_1p[M+ 1p Fallback]::
 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.
+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.
@@ -736,8 +739,8 @@ This limitation may be lifted in the future.
 The limited character set of WINANSI, or the bland look of the built-in fonts, may motivate you to load your own font.
 Custom fonts can enhance the look of your PDF theme substantially.
 
-To start, you need to find a TTF file collection for the font you want to use.
-A collection typically consists of all four styles of a font:
+To start, find the TTF file collection for the font you want to use.
+A collection typically consists of all four font styles:
 
 * normal
 * italic
@@ -745,13 +748,16 @@ A collection typically consists of all four styles of a font:
 * bold_italic
 
 You'll need all four styles to support AsciiDoc content properly.
-_Asciidoctor PDF cannot italicize a font dynamically like a browser can, so you need the italic style._
+_Asciidoctor PDF cannot italicize a font dynamically like a browser can, so the italic styles are required._
 
-Once you've obtained the TTF files, put them into a directory in your project where you want to store the fonts.
+In order for a third-party font to work properly with Prawn (and hence Asciidoctor PDF), several modifications are required.
+See <<Prepare a Custom Font>> to learn how to prepare your font for use with Asciidoctor PDF.
+
+Once you've obtained the TTF files, put them in the directory inside your project where you want to store the fonts.
 It's recommended that you name them consistently so it's easier to type the names in the theme file.
 
 Let's assume the name of the font is https://github.com/google/roboto/tree/master/out/RobotoTTF[Roboto].
-Name the files as follows:
+Rename the files as follows:
 
 * roboto-normal.ttf (_originally Roboto-Regular.ttf_)
 * roboto-italic.ttf (_originally Roboto-Italic.ttf_)
@@ -772,7 +778,7 @@ font:
 ----
 
 You can use the key that you assign to the font in the font catalog anywhere the `font-family` property is accepted in the theme file.
-For instance, to use the Roboto font for all headings, you'd use:
+For example, to use the Roboto font for all headings, use:
 
 [source,yaml]
 ----
@@ -780,16 +786,18 @@ heading:
   font-family: Roboto
 ----
 
-When you execute Asciidoctor PDF, you need to specify the directory where the fonts reside using the `pdf-fontsdir` attribute:
+When you execute Asciidoctor PDF, specify the directory where the fonts reside using the `pdf-fontsdir` attribute:
 
  $ asciidoctor-pdf -a pdf-theme=basic-theme.yml -a pdf-fontsdir=path/to/fonts document.adoc
 
 WARNING: Currently, all fonts referenced by the theme need to be present in the directory specified by the `pdf-fontsdir` attribute.
 
-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.
-In other words, Asciidoctor PDF automatically subsets the font.
-However, if you're storing the fonts in a repository, you may want to subset the font (for instance, by using FontForge) to reduce the space the font occupies in that storage.
-This is simply a personal preference.
+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.
+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.
 
 You can add any number of fonts to the catalog.
 Each font must be assigned a unique key, as shown here:
@@ -810,22 +818,23 @@ font:
       bold_italic: roboto-light-bold_italic.ttf
 ----
 
-TIP: Text in SVGs will use the font catalog from your theme.
-We recommend that you match the font key to the name of the font seen by the operating system.
-This will allow you to use the same font names (aka families) in both your graphics program and Asciidoctor PDF.
+Text in SVGs will use the font catalog from your theme.
+We recommend that you match the font key in your theme file to the name of the font seen by the operating system.
+This will allow you to use the same font names (aka families) in both your graphics program and Asciidoctor PDF, thus making them portable.
 
 === Fallback Fonts
 
 If a TrueType font is missing a character needed to render the document, such as a special symbol, 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.
 
-IMPORTANT: The fallback font is only used when the primary font is a TrueType font (i.e., TTF, DFont, TTC).
+IMPORTANT: The fallback font only gets used when the primary font is a TrueType font (i.e., TTF, DFont, TTC).
 Any glyph missing from an AFM font is simply replaced with the "`not`" glyph (`&#172;`).
 
-CAUTION: Using the fallback font slows down PDF generation slightly because it has to analyze every single character.
+CAUTION: The `default` theme does not use a fallback font.
+However, the built-in `default-with-fallback-font` theme does.
+Using the fallback font slows down PDF generation slightly because it has to analyze every single character.
 It's use is not recommended for large documents.
 Instead, it's best to select primary fonts that have all the characters you need.
-Keep in mind that the default theme currently uses a fallback font, though this may change in the future.
 
 Like with other custom fonts, you first need to declare the fallback font.
 Let's choose https://github.com/android/platform_frameworks_base/blob/master/data/fonts/DroidSansFallback.ttf[Droid Sans Fallback].
@@ -866,7 +875,7 @@ font:
       bold: droid-sans-fallback.ttf
       bold_italic: droid-sans-fallback.ttf
   fallbacks:
-    - DroidSansFallback
+  - DroidSansFallback
 ----
 
 TIP: If you are using more than one fallback font, add additional lines to the `fallbacks` key.
@@ -881,7 +890,7 @@ base:
 
 That's it!
 Now you're covered.
-If your custom font is missing a glyph, Asciidoctor PDF will look in your fallback font.
+If your custom TTF font is missing a glyph, Asciidoctor PDF will look in your fallback font.
 You don't need to reference the fallback font anywhere else in your theme file.
 
 == Keys
@@ -907,6 +916,15 @@ Therefore, you only have to declare keys that you want to override.
 === Extends
 
 A theme can extend another theme using the `extends` key.
+For example:
+
+[source,yaml]
+----
+extends: default
+base:
+  font-color: #ff0000
+----
+
 The extends key accepts either a single value or an array of values.
 Each value is interpreted as a filename.
 If the filename equals `default`, it resolves to the location of the default (built-in) theme.
@@ -931,6 +949,67 @@ Each time a theme is loaded, the keys are overlaid onto the keys from the previo
 - ./brand-theme.yml
 |===
 
+[#keys-role]
+=== Role
+
+The keys in the `role` category define custom roles for formatting.
+The name of the role is the first subkey level.
+The role name may not contain a hyphen or underscore.
+The keys under the role are the concrete theming properties.
+
+Here's an example of a role for making text red:
+
+[source,yaml]
+----
+role:
+  red:
+    font-color: #ff0000
+----
+
+This role can be used as follows:
+
+[source,asciidoc]
+----
+Error text is shown in [.red]#red#.
+----
+
+Currently, custom roles only apply to inline phrases and only support changing the font properties.
+
+[cols="3,4,5l"]
+|===
+|Key |Value Type |Example
+
+3+|[#key-prefix-role]*Key Prefix:* <<key-prefix-role,role-<name> >>
+
+|font-color
+|<<colors,Color>> +
+(default: _inherit_)
+|role:
+  red:
+    font-color: #ff0000
+
+|font-family
+|<<fonts,Font family name>> +
+(default: Courier)
+|role:
+  label:
+    font-family: M+ 1mn
+
+|font-size
+|<<values,Number>> +
+(default: _inherit_)
+|role:
+  large:
+    font-size: 12
+
+|font-style
+|<<font-styles,Font style>> +
+(default: _inherit_)
+|role:
+  heavy:
+    font-style: bold
+|===
+
 [#keys-page]
 === Page
 
@@ -1062,6 +1141,12 @@ NOTE: While it's common to define additional keys in this category (e.g., `base-
 |base:
   font-family: Noto Serif
 
+|font-kerning
+|normal {vbar} default +
+(default: normal)
+|base:
+  font-kerning: none
+
 |font-size
 |<<values,Number>> +
 (default: 12)
@@ -1187,6 +1272,36 @@ The keys in this category are used for inline monospaced text in prose and table
 
 3+|[#key-prefix-literal]*Key Prefix:* <<key-prefix-literal,literal>>
 
+|background-color
+|<<colors,Color>> +
+(default: _not set_)
+|literal:
+  background-color: #f5f5f5
+
+|border-color^[1]^
+|<<colors,Color>> +
+(default: _not set_)
+|literal:
+  border-color: #cccccc
+
+|border-offset^[2]^
+|<<values,Number>> +
+(default: 0)
+|literal:
+  border-offset: 2
+
+|border-radius
+|<<values,Number>> +
+(default: _not set_)
+|literal:
+  border-radius: 3
+
+|border-width
+|<<values,Number>> +
+(default: $base-border-width)
+|literal:
+  border-width: 0.5
+
 |font-color
 |<<colors,Color>> +
 (default: _inherit_)
@@ -1211,6 +1326,11 @@ The keys in this category are used for inline monospaced text in prose and table
 |literal:
   font-style: bold
 |===
+. The border is only used if a border color is specified and the border width is not explicitly set to 0.
+The border only works properly if the literal phrase does not have nested formatting.
+Otherwise, the border will be inherited, producing a less than desirable result.
+. The border offset is the amount that the background and border swells around the text.
+It does not affect the distance between the formatted phrase and the phrases that surround it.
 
 [#keys-heading]
 === Heading
@@ -1852,7 +1972,7 @@ The keys in this category are used to control the style of literal, listing and
 
 |font-size
 |<<values,Number>> +
-(default: 10.5)
+(default: 10.8)
 |code:
   font-size: 11
 
@@ -1895,7 +2015,7 @@ Otherwise, the style is controlled by the source highlighter theme.
 [#keys-callout-numbers]
 === Callout Numbers
 
-The keys in this category are used to control the style of callout numbers (conums) inside verbatim blocks and in callout lists (colists).
+The keys in this category are used to control the style of callout numbers (i.e., conums) inside verbatim blocks and in callout lists (colists).
 
 [cols="3,4,5l"]
 |===
@@ -1932,11 +2052,171 @@ The keys in this category are used to control the style of callout numbers (conu
 (default: 1.15)
 |conum:
   line-height: 4 / 3
+
+|glyphs^[2]^
+|circled {vbar} filled {vbar} Unicode String ranges +
+(default: circled)
+|conum:
+  glyphs: \u0031-\u0039
 |===
 
 . Currently, the font must contain the circle numbers starting at glyph U+2460.
 . font-family, font-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).
+
+[#keys-button]
+=== Button
+
+The keys in this category apply to a button reference (generated from the inline button macro).
+
+[cols="3,4,5l"]
+|===
+|Key |Value Type |Example
+
+3+|[#key-prefix-button]*Key Prefix:* <<key-prefix-button,button>>
+
+|background-color
+|<<colors,Color>> +
+(default: _not set_)
+|button:
+  background-color: #0000ff
+
+|border-color^[1]^
+|<<colors,Color>> +
+(default: _not set_)
+|button:
+  border-color: #cccccc
+
+|border-offset^[2]^
+|<<values,Number>> +
+(default: 0)
+|button:
+  border-offset: 1.5
+
+|border-radius
+|<<values,Number>> +
+(default: 0)
+|button:
+  border-radius: 2
+
+|border-width
+|<<values,Number>> +
+(default: $base-border-width)
+|button:
+  border-width: 0.5
+
+|content^[3]^
+|<<quoted-string,Quoted string>> +
+(default: "%s")
+|button:
+  content: "[\u2009%s\u2009]"
+
+|font-color
+|<<colors,Color>> +
+(default: _inherit_)
+|button:
+  font-color: #ffffff
+
+|font-family
+|<<fonts,Font family name>> +
+(default: Courier)
+|button:
+  font-family: M+ 1mn
+
+|font-size
+|<<values,Number>> +
+(default: _inherit_)
+|button:
+  font-size: 12
+
+|font-style
+|<<font-styles,Font style>> +
+(default: bold)
+|button:
+  font-style: normal
+|===
+. The border is only used if a border color is specified and the border width is not explicitly set to 0.
+. The border offset is the amount that the background and border swells around the text.
+It does not affect the distance between the formatted phrase and the phrases that surround it.
+. The character sequence `%s` in the content key gets replaced with the button label.
+
+[#keys-key]
+=== Key
+
+The keys in this category apply to a key reference (generated from the inline kbd macro).
+
+[cols="3,4,5l"]
+|===
+|Key |Value Type |Example
+
+3+|[#key-prefix-key]*Key Prefix:* <<key-prefix-key,key>>
+
+|background-color
+|<<colors,Color>> +
+(default: _not set_)
+|key:
+  background-color: #fafafa
+
+|border-color^[1]^
+|<<colors,Color>> +
+(default: _not set_)
+|key:
+  border-color: #cccccc
+
+|border-offset^[2]^
+|<<values,Number>> +
+(default: 0)
+|key:
+  border-offset: 1.5
+
+|border-radius
+|<<values,Number>> +
+(default: 0)
+|key:
+  border-radius: 2
+
+|border-width
+|<<values,Number>> +
+(default: $base-border-width)
+|key:
+  border-width: 0.375
+
+|separator^[3]^
+|<<quoted-string,Quoted string>> +
+(default: "+")
+|key:
+  separator: "\u2009+\u2009"
+
+|font-color
+|<<colors,Color>> +
+(default: _inherit_)
+|key:
+  font-color: #000
+
+|font-family
+|<<fonts,Font family name>> +
+(default: Courier)
+|key:
+  font-family: $base-font-family
+
+|font-size
+|<<values,Number>> +
+(default: _inherit_)
+|key:
+  font-size: 10.5
+
+|font-style
+|<<font-styles,Font style>> +
+(default: italic)
+|key:
+  font-style: normal
+|===
+. The border is only used if a border color is specified and the border width is not explicitly set to 0.
+. The border offset is the amount that the background and border swells around the text.
+It does not affect the distance between the formatted phrase and the phrases that surround it.
+. The separator is only used for multi-key sequences.
 
 [#keys-menu]
 === Menu
@@ -2435,6 +2715,25 @@ The keys in this category control the arrangement of block images.
 . 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.
 
+[#keys-svg]
+=== SVG
+
+The keys in this category control the SVG integration.
+
+[cols="3,4,5l"]
+|===
+|Key |Value Type |Example
+
+3+|[#key-prefix-image]*Key Prefix:* <<key-prefix-svg,svg>>
+
+|fallback_font_family^[1]^
+|<<fonts,Font family name>> +
+(default: $base-font-family)
+|svg:
+  fallback_font_family: Times-Roman
+|===
+. The fallback font family is only used when the font family in the SVG does not map to a known font name from the font catalog.
+
 [#keys-lead]
 === Lead
 
@@ -3075,9 +3374,9 @@ The styling of the links is controlled by the global link styles.
 
 |font-size
 |<<values,Number>> +
-(default: 8)
+(default: 9)
 |footnotes:
-  font-size: 6
+  font-size: 8
 
 |font-style
 |<<font-styles,Font style>> +
@@ -3396,6 +3695,12 @@ To avoid this problem, reduce the height of the running content periphery or mak
 |header:
   text-transform: uppercase
 
+|title-style
+|document {vbar} toc {vbar} basic +
+(default: document)
+|header:
+  title-style: toc
+
 |vertical-align
 |top {vbar} middle {vbar} bottom +
 (default: middle)
@@ -3503,6 +3808,12 @@ To avoid this problem, reduce the height of the running content periphery or mak
 |footer:
   text-transform: uppercase
 
+|title-style
+|document {vbar} toc {vbar} basic +
+(default: document)
+|footer:
+  title-style: toc
+
 |vertical-align
 |top {vbar} middle {vbar} bottom +
 (default: middle)
@@ -3926,3 +4237,107 @@ For more information about source highlighting with Rouge, refer to the http://r
 
 * http://www.sitepoint.com/hackable-pdf-typesetting-in-ruby-with-prawn[Hackable PDF typesetting in Ruby with Prawn]
 ////
+
+[appendix]
+== Preparing a Custom Font
+
+Any TTF font can be used with Prawn--and hence Asciidoctor PDF--without modifications (unless, of course, it's corrupt or contains errors).
+However, you may discover that kerning is disabled and certain required glyphs are missing.
+To address these problems, you need to prepare the font using a font program such as {url-fontforge}[FontForge].
+
+=== Validate the Font
+
+Before using the font, you may want to check that the font is valid.
+To do so, create the following script, which will verify that the TTF font is free from errors.
+
+.validate-font.rb
+[source,ruby]
+----
+require 'ttfunk'
+require 'ttfunk/subset_collection'
+
+ttf_subsets = TTFunk::SubsetCollection.new TTFunk::File.open ARGV[0]
+(0...(ttf_subsets.instance_variable_get :@subsets).size).each {|idx| ttf_subsets[idx].encode }
+----
+
+Run the script on your font as follows:
+
+ $ ruby validate-font.rb path/to/font.ttf
+
+If this script fails, the font will not work with Asciidoctor PDF.
+To repair it, open the font in FontForge and resave it using menu:File[Generate Fonts...,Generate].
+Dismiss any warning dialogs.
+
+Resaving the font in FontForge will usually resolve any errors in the font.
+(If not, you may need to find another font, or at least another copy of it).
+
+=== Modifying the Font
+
+To ready your font for use with Asciidoctor PDF, you'll need to modify it using a font program.
+We recommend using {url-fontforge}[FontForge].
+But don't let this scare you off.
+FontForge essentially works like a vector-drawing tool, in which each character is a separate canvas.
+You can find a crash course in how to use the program on the FontForge project site.
+
+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).
+* 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.
+
+NOTE: Technically, subsetting the font (i.e., removing glyphs) is not required since Prawn only embeds the characters from the font used in the document (i.e., it automatically subsets the font).
+However, if you plan to commit the font to a repository, subsetting helps keep the file size down.
+
+Most fonts do not provide glyphs for all the Unicode character ranges (i.e., scripts).
+(A glyph is the corresponding vector image for a Unicode character).
+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):
+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
+* \ufeff - zero width no-break space
+* \u200b - zero width space (used for line break hints)
+* \u000a - line feed character (zero width)
+* \u2009 - thin spaced (used in the button UI element)
+* \u202f - narrow no-break space (used in the keybinding UI element)
+* \u2011 - non-breaking hyphen
+* \u2022 - disc (used for first-level unordered list level)
+* \u25e6 - circle (used for second-level unordered list level)
+* \u25aa - square (used for third-level unordered list level)
+* \u2611 - ballot box checked (used for checked list item)
+* \u2610 - ballot box unchecked (used for unchecked list item)
+* \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)
+
+If you're preparing a font for use in verbatim blocks (e.g., a listing block), you'll also need this range of characters:
+
+* \u2460 to \u2468 - circled numbers
+
+One way to get these glyphs is to steal them from another font (or from another character in the same font).
+To do so, open the other font in FontForge, select the character, press kbd:[Ctrl,c], switch back to your font, select the character again, and press kbd:[Ctrl,v].
+You may need to scale the glyph so it fits properly in the art box.
+
+IMPORTANT: If you're copying a non-visible character, be sure to set the width to 0 using menu:Metrics[Set Width...], enter 0 into *Set Width To*, then click btn:[OK].
+
+When you're done, save the font with the old-style kern table enabled.
+To do so, select menu:File[Generate Fonts...], click btn:[Options], and make sure only the following options are selected (equivalent to the flags 0x90 + 0x08):
+
+* [x] OpenType
+ ** [x] Old style 'kern'
+
+Then click btn:[Generate] to generate and save the font.
+
+Your font file is now ready to be used with Asciidoctor PDF.
+
+=== Scripting the Font Modifications
+
+Performing all this font modification manually can be tedious (not to mention hard to reproduce).
+Fortunately, FontForge provides a {url-fontforge-scripting}[scripting interface], which you can use to automate the process.
+
+In fact, that's what we use to prepare the fonts that are bundled with Asciidoctor PDF.
+You can find that FontForge script, the Bash script that calls it, and the Docker image in which it is run in the https://github.com/asciidoctor/asciidoctor-pdf/tree/master/scripts[scripts directory] of this project.
+You can use that script as a starting point or reference for your own font preparation / modification script.