document support for relative font sizes in theme

27 files changed, 75 insertions, 46 deletions

diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
index 07be5e7c..8e75fe3f 100644
--- a/CHANGELOG.adoc
+++ b/CHANGELOG.adoc
@@ -16,7 +16,7 @@ Enhancements::
 * don't force page break after TOC with automatic placement in article if `title-page` attribute is set and value of `toc-break-after` theme key is `auto` (#1768)
 * add `--theme` option to CLI as shorthand for `-a pdf-theme` (#2250)
 * add `--sourcemap` option to CLI to enable `:sourcemap` option on processor (#2265)
-* broaden support for relative font sizes in theme to more than just inline elements
+* broaden support for relative font sizes in theme to more than just inline elements; document support for relative font sizes
 
 Improvements::
 
diff --git a/docs/modules/theme/pages/abstract.adoc b/docs/modules/theme/pages/abstract.adoc
index 635e08f5..dea0ba4c 100644
--- a/docs/modules/theme/pages/abstract.adoc
+++ b/docs/modules/theme/pages/abstract.adoc
@@ -20,7 +20,7 @@ abstract:
   font-color: #5C6266
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: `13.5`)
 |[source]
 abstract:
@@ -143,7 +143,7 @@ abstract:
     font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: `$base-font-size`)
 |[source]
 abstract:
diff --git a/docs/modules/theme/pages/admonition.adoc b/docs/modules/theme/pages/admonition.adoc
index 41cf3734..c6b2c9db 100644
--- a/docs/modules/theme/pages/admonition.adoc
+++ b/docs/modules/theme/pages/admonition.adoc
@@ -92,7 +92,7 @@ admonition:
   font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 admonition:
@@ -154,7 +154,7 @@ admonition:
     font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 admonition:
@@ -253,7 +253,7 @@ admonition:
       font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 admonition:
diff --git a/docs/modules/theme/pages/block-image.adoc b/docs/modules/theme/pages/block-image.adoc
index f608e6e1..1f1b5092 100644
--- a/docs/modules/theme/pages/block-image.adoc
+++ b/docs/modules/theme/pages/block-image.adoc
@@ -129,7 +129,7 @@ image:
     font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 image:
diff --git a/docs/modules/theme/pages/button.adoc b/docs/modules/theme/pages/button.adoc
index 88ebe78e..1963f225 100644
--- a/docs/modules/theme/pages/button.adoc
+++ b/docs/modules/theme/pages/button.adoc
@@ -69,7 +69,7 @@ button:
   font-family: M+ 1mn
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 button:
diff --git a/docs/modules/theme/pages/callout.adoc b/docs/modules/theme/pages/callout.adoc
index 786f22e8..7c110d21 100644
--- a/docs/modules/theme/pages/callout.adoc
+++ b/docs/modules/theme/pages/callout.adoc
@@ -37,7 +37,7 @@ callout-list:
   font-kerning: none
 
 |<<inherit,font-size>>
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 callout-list:
@@ -120,7 +120,7 @@ conum:
   font-kerning: none
 
 |<<inherit,font-size>>
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 conum:
diff --git a/docs/modules/theme/pages/caption.adoc b/docs/modules/theme/pages/caption.adoc
index 3cbf8204..8e4a3247 100644
--- a/docs/modules/theme/pages/caption.adoc
+++ b/docs/modules/theme/pages/caption.adoc
@@ -49,7 +49,7 @@ caption:
   font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 caption:
diff --git a/docs/modules/theme/pages/code.adoc b/docs/modules/theme/pages/code.adoc
index a9c37fe5..5c18aa68 100644
--- a/docs/modules/theme/pages/code.adoc
+++ b/docs/modules/theme/pages/code.adoc
@@ -62,7 +62,7 @@ code:
   font-family: M+ 1mn
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: `10.8`)
 |[source]
 code:
diff --git a/docs/modules/theme/pages/codespan.adoc b/docs/modules/theme/pages/codespan.adoc
index c119b89a..67ab3e76 100644
--- a/docs/modules/theme/pages/codespan.adoc
+++ b/docs/modules/theme/pages/codespan.adoc
@@ -61,8 +61,8 @@ codespan:
 codespan:
   font-family: M+ 1mn
 
-|<<font-size,font-size>>
-|xref:language.adoc#values[Number] +
+|font-size
+|<<font-size,Font size>> +
 (default: _inherit_)
 |[source]
 codespan:
@@ -95,3 +95,4 @@ It does not affect the distance between the formatted phrase and the phrases tha
 You're strongly encouraged to set the value of the `font-size` key to a relative font size using the `em` units (e.g., `0.9em`).
 A code phrase with a fixed font size will not be scaled when the font size of the parent element (e.g., table, caption, etc.) is specified.
 However, by using a relative value, the font size will be computed relative to the size of the text that surrounds it, giving you effectively the same result.
+See xref:text.adoc#font-size[Font size] for more information about relative font sizes.
diff --git a/docs/modules/theme/pages/description-list.adoc b/docs/modules/theme/pages/description-list.adoc
index 8c214129..6600d921 100644
--- a/docs/modules/theme/pages/description-list.adoc
+++ b/docs/modules/theme/pages/description-list.adoc
@@ -41,7 +41,7 @@ description-list:
   term-font-kerning: none
 
 |term-font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 description-list:
diff --git a/docs/modules/theme/pages/example.adoc b/docs/modules/theme/pages/example.adoc
index 5105665a..ac41cf62 100644
--- a/docs/modules/theme/pages/example.adoc
+++ b/docs/modules/theme/pages/example.adoc
@@ -66,7 +66,7 @@ example:
   font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 example:
diff --git a/docs/modules/theme/pages/footnotes.adoc b/docs/modules/theme/pages/footnotes.adoc
index c6f018c5..d570f100 100644
--- a/docs/modules/theme/pages/footnotes.adoc
+++ b/docs/modules/theme/pages/footnotes.adoc
@@ -19,7 +19,7 @@ footnotes:
   font-color: #CCCCCC
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: `9`)
 |[source]
 footnotes:
diff --git a/docs/modules/theme/pages/heading.adoc b/docs/modules/theme/pages/heading.adoc
index 4f0a006d..aaaef929 100644
--- a/docs/modules/theme/pages/heading.adoc
+++ b/docs/modules/theme/pages/heading.adoc
@@ -167,7 +167,7 @@ heading:
   h3-font-kerning: none
 
 |<<font-size,font-size>>
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: h1=`24`; h2=`18`; h3=`16`; h4=`14`; <h5=`12`; h6=`10`)
 |[source]
 heading:
diff --git a/docs/modules/theme/pages/keyboard.adoc b/docs/modules/theme/pages/keyboard.adoc
index 09cd3e73..0c3a1ce5 100644
--- a/docs/modules/theme/pages/keyboard.adoc
+++ b/docs/modules/theme/pages/keyboard.adoc
@@ -63,7 +63,7 @@ kbd:
   font-family: $base-font-family
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 kbd:
diff --git a/docs/modules/theme/pages/language.adoc b/docs/modules/theme/pages/language.adoc
index 30fdc113..cf39bc42 100644
--- a/docs/modules/theme/pages/language.adoc
+++ b/docs/modules/theme/pages/language.adoc
@@ -49,7 +49,7 @@ The value of a key may be one of the following types:
 ** _empty_ (i.e., no value specified)
 ** null
 ** ~
-* Number (integer or float) with optional units (default unit is points)
+* Number (integer or float) with optional fixed units (default unit is points)
 * Array
 ** Color as RGB array (e.g., [51, 51, 51])
 ** Color as CMYK array (e.g., [50, 100, 0, 0])
diff --git a/docs/modules/theme/pages/link.adoc b/docs/modules/theme/pages/link.adoc
index 3081465f..710a6881 100644
--- a/docs/modules/theme/pages/link.adoc
+++ b/docs/modules/theme/pages/link.adoc
@@ -38,7 +38,7 @@ link:
   font-family: Roboto
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 link:
diff --git a/docs/modules/theme/pages/list.adoc b/docs/modules/theme/pages/list.adoc
index 4ed51d77..13d530ac 100644
--- a/docs/modules/theme/pages/list.adoc
+++ b/docs/modules/theme/pages/list.adoc
@@ -62,7 +62,7 @@ ulist:
     font-family: Noto Serif
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 ulist:
@@ -114,7 +114,7 @@ ulist:
       font-family: fas
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 ulist:
diff --git a/docs/modules/theme/pages/menu.adoc b/docs/modules/theme/pages/menu.adoc
index a70514b3..3b24ba37 100644
--- a/docs/modules/theme/pages/menu.adoc
+++ b/docs/modules/theme/pages/menu.adoc
@@ -33,7 +33,7 @@ menu:
   font-family: M+ 1mn
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 menu:
diff --git a/docs/modules/theme/pages/quote.adoc b/docs/modules/theme/pages/quote.adoc
index 2ae1f161..826482a2 100644
--- a/docs/modules/theme/pages/quote.adoc
+++ b/docs/modules/theme/pages/quote.adoc
@@ -76,7 +76,7 @@ quote:
   font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 quote:
@@ -120,7 +120,7 @@ The keys in the `quote-cite` category control the arrangement and style of the c
 |Key |Value Type |Example
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 quote:
diff --git a/docs/modules/theme/pages/role.adoc b/docs/modules/theme/pages/role.adoc
index a5c8f962..8c6f7279 100644
--- a/docs/modules/theme/pages/role.adoc
+++ b/docs/modules/theme/pages/role.adoc
@@ -74,7 +74,7 @@ role:
     font-family: M+ 1mn
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 role:
diff --git a/docs/modules/theme/pages/running-content.adoc b/docs/modules/theme/pages/running-content.adoc
index 68e5f7e2..02d9c67b 100644
--- a/docs/modules/theme/pages/running-content.adoc
+++ b/docs/modules/theme/pages/running-content.adoc
@@ -116,7 +116,7 @@ header:
   font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 header:
@@ -344,7 +344,7 @@ footer:
   font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 footer:
diff --git a/docs/modules/theme/pages/sidebar.adoc b/docs/modules/theme/pages/sidebar.adoc
index 0f517762..f08dac03 100644
--- a/docs/modules/theme/pages/sidebar.adoc
+++ b/docs/modules/theme/pages/sidebar.adoc
@@ -69,7 +69,7 @@ sidebar:
   font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 sidebar:
@@ -131,7 +131,7 @@ sidebar:
     font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 sidebar:
diff --git a/docs/modules/theme/pages/table.adoc b/docs/modules/theme/pages/table.adoc
index e59fb011..704f2f6e 100644
--- a/docs/modules/theme/pages/table.adoc
+++ b/docs/modules/theme/pages/table.adoc
@@ -69,7 +69,7 @@ table:
   font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 table:
@@ -179,7 +179,7 @@ table:
     font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: `$table-font-size`)
 |[source]
 table:
@@ -271,7 +271,7 @@ table:
     font-family: Noto Serif
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: `$table-font-size`)
 |[source]
 table:
@@ -366,7 +366,7 @@ table:
     font-family: Noto Sans
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[font-size] +
 (default: `$table-head-font-size`)
 |[source]
 table:
diff --git a/docs/modules/theme/pages/text.adoc b/docs/modules/theme/pages/text.adoc
index 278081ae..45c0a964 100644
--- a/docs/modules/theme/pages/text.adoc
+++ b/docs/modules/theme/pages/text.adoc
@@ -32,6 +32,34 @@ underline:: A line is drawn beneath the text.
 
 When a key category allows the `text-decoration` key to be set, you can usually specify a `text-decoration-color` and `text-decoration-width`, too.
 
+[#font-size]
+== Font size
+
+The `font-size` key specifies the size of the font.
+The font size may be specified either as a fixed value (e.g., `12`) or a relative value (e.g., `0.8em`).
+Font sizes are most often specified as a fixed value, though there are important cases when a relative value is more suitable.
+The font size always resolves to a point value when text is written to the PDF.
+
+If the font size is specified as a number, or a number with a fixed unit of measurement (e.g., `px`), that value is converted to points.
+The conversion to points is done when the theme is loaded.
+The `font-size` key on the `base` category, as well as min, large, and small font size keys, must always be specified as a fixed value.
+
+The only time this value is not used as specified is when the element is inside a table.
+If the font size on the table or AsciiDoc table cell differs from the base font size, all nested content is scaled by that ratio.
+
+If the font size has relative units, `em`, `%`, or `rem`, then the value will be computed at the point of use.
+
+* If the value has the unit `em`, then that value will be multiplied by the current font size.
+* If the value has the unit `%`, then that value will be divided by 100, then multiplied by the current font size.
+* If the value has the unit `rem`, then that value will be multiplied by the base font size.
+
+For example, if the font size is `0.75em` and the current font size is `12`, then the font size will be `9`.
+
+Relative font sizes are best suited for inline elements, such as a codespan.
+Only use a relative font size when the font size should always be scaled relative to either the parent element (`em` or `%`) or base font size (`rem`).
+
+Note that fonts often contain built-in line height, so the size of the font may appear to take up more room than the number of points specified.
+
 [#font-style]
 == Font style
 
diff --git a/docs/modules/theme/pages/title-page.adoc b/docs/modules/theme/pages/title-page.adoc
index 26847260..bfc783d4 100644
--- a/docs/modules/theme/pages/title-page.adoc
+++ b/docs/modules/theme/pages/title-page.adoc
@@ -49,7 +49,7 @@ title-page:
   font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 title-page:
@@ -173,7 +173,7 @@ title-page:
     font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: `18`)
 |[source]
 title-page:
@@ -279,7 +279,7 @@ title-page:
     font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: `14`)
 |[source]
 title-page:
@@ -388,7 +388,7 @@ title-page:
     font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 title-page:
@@ -483,7 +483,7 @@ title-page:
     font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 title-page:
diff --git a/docs/modules/theme/pages/toc.adoc b/docs/modules/theme/pages/toc.adoc
index 6175a22d..69e9574c 100644
--- a/docs/modules/theme/pages/toc.adoc
+++ b/docs/modules/theme/pages/toc.adoc
@@ -41,7 +41,7 @@ toc:
   font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 toc:
@@ -144,7 +144,7 @@ toc:
   h3-font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 toc:
@@ -199,7 +199,7 @@ toc:
     font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: `$heading-h2-font-size`)
 |[source]
 toc:
@@ -257,7 +257,7 @@ toc:
     font-color: #999999
 
 |<<font-properties,font-size>>
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 toc:
diff --git a/docs/modules/theme/pages/verse.adoc b/docs/modules/theme/pages/verse.adoc
index d6227d0b..f330f25a 100644
--- a/docs/modules/theme/pages/verse.adoc
+++ b/docs/modules/theme/pages/verse.adoc
@@ -76,7 +76,7 @@ verse:
   font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 verse:
@@ -150,7 +150,7 @@ verse:
     font-kerning: none
 
 |font-size
-|xref:language.adoc#values[Number] +
+|xref:text.adoc#font-size[Font size] +
 (default: _inherit_)
 |[source]
 verse: