resolves #460 document how to inherit font size for a given heading level (PR #461)

- document that each heading level is assigned a font size by the base theme
- explain how to clear the default value so the font size is inherited
- don't quote null values in theme

3 files changed, 10 insertions, 4 deletions

diff --git a/docs/theming-guide.adoc b/docs/theming-guide.adoc
index 107ec071..d9cab63c 100644
--- a/docs/theming-guide.adoc
+++ b/docs/theming-guide.adoc
@@ -148,6 +148,10 @@ The value of a key may be one of the following types:
   - Alignment (left, center, right, justify)
   - Color as hex string (e.g., #ffffff)
   - Image path
+* Null (clears any previously assigned value)
+  - _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])
@@ -177,7 +181,8 @@ The following keys are inherited:
 
 .Heading Inheritance
 ****
-Headings are special in that they inherit starting from a specific heading level (e.g., `heading_font_size_h2`) to the heading category (e.g., `heading_font_size`) and then directly to the base value (e.g., `base_font_size`), skipping any enclosing context.
+Headings inherit starting from a specific heading level (e.g., `heading_h2_font_size`), then to the heading category (e.g., `heading_font_size`), then directly to the base value (e.g., `base_font_size`).
+Any setting from an enclosing context, such as a sidebar, is skipped.
 ****
 
 === Variables
@@ -1020,7 +1025,7 @@ The keys in this category control the style of most headings, including part tit
 |heading:
   h4_font_family: Roboto
 
-|font_size
+|font_size^[1]^
 |<<values,Number>> +
 (default: h1=24; h2=18; h3=16; h4=14; h5=12; h6=10)
 |heading:
@@ -1040,6 +1045,8 @@ The keys in this category control the style of most headings, including part tit
 |===
 
 . `<n>` is a number ranging from 1 to 6, representing each of the six heading levels.
+. A font size is assigned to each heading level by the base theme.
+If you want the font size of a specific level to be inherited, you must assign the value `null` (or `~` for short).
 
 === Title page
 
diff --git a/lib/asciidoctor-pdf/converter.rb b/lib/asciidoctor-pdf/converter.rb
index 26cda348..edb0dd69 100644
--- a/lib/asciidoctor-pdf/converter.rb
+++ b/lib/asciidoctor-pdf/converter.rb
@@ -2181,7 +2181,6 @@ class Converter < ::Prawn::Document
   def theme_font category, opts = {}
     if (level = opts[:level])
       family = @theme[%(#{category}_h#{level}_font_family)] || @theme[%(#{category}_font_family)] || @theme.base_font_family
-      # FIXME technically the size fallback isn't necessary since the base theme assigns sizes to all levels
       size = @theme[%(#{category}_h#{level}_font_size)] || @theme[%(#{category}_font_size)] || @theme.base_font_size
       style = @theme[%(#{category}_h#{level}_font_style)] || @theme[%(#{category}_font_style)]
       color = @theme[%(#{category}_h#{level}_font_color)] || @theme[%(#{category}_font_color)]
diff --git a/lib/asciidoctor-pdf/theme_loader.rb b/lib/asciidoctor-pdf/theme_loader.rb
index 0494fba4..6fa0120c 100644
--- a/lib/asciidoctor-pdf/theme_loader.rb
+++ b/lib/asciidoctor-pdf/theme_loader.rb
@@ -13,7 +13,7 @@ class ThemeLoader
 
   VariableRx = /\$([a-z0-9_]+)/
   LoneVariableRx = /^\$([a-z0-9_]+)$/
-  HexColorEntryRx = /^(?<k>[[:blank:]]*[[:graph:]]+): +(?<q>["']?)#?(?<v>\w{3,6})\k<q> *(?:#.*)?$/
+  HexColorEntryRx = /^(?<k>[[:blank:]]*[[:graph:]]+): +(?!null$)(?<q>["']?)#?(?<v>\w{3,6})\k<q> *(?:#.*)?$/
   MeasurementValueRx = /(?<=^| |\()(-?\d+(?:\.\d+)?)(in|mm|cm|pt)(?=$| |\))/
   MultiplyDivideOpRx = /(-?\d+(?:\.\d+)?) +([*\/]) +(-?\d+(?:\.\d+)?)/
   AddSubtractOpRx = /(-?\d+(?:\.\d+)?) +([+\-]) +(-?\d+(?:\.\d+)?)/