clarify in theming guide how and when to redeclare the bundled fonts [skip ci]

1 files changed, 49 insertions, 10 deletions

diff --git a/docs/theming-guide.adoc b/docs/theming-guide.adoc
index 0cda382a..f0091218 100644
--- a/docs/theming-guide.adoc
+++ b/docs/theming-guide.adoc
@@ -28,19 +28,18 @@ ifdef::backend-pdf[:conum-guard-yaml: # #]
 Topics remaining to document:
 * line height and line height length (and what that all means)
 * title page layout / title page images (logo & background)
-* document that unicode escape sequences can be used inside double-quoted strings
 ////
 
 [.lead]
 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.
+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.
 
 TIP: The quickest way to create your own theme is to <<Extends,extend the default theme>>.
-This not only gives you a set of foundation styles to build on, it also provides a collection of <<Bundled Fonts,bundled fonts>>.
-If you want to replace the bundled fonts with your own, you must declare the name and location of each font in the <<Custom Fonts,font catalog>>.
-To reuse the bundled fonts, you can either extend the default theme and/or redeclare the bundled fonts in the font catalog.
+This gives you a set of foundation styles to build on and provides a collection of <<Bundled Fonts,bundled fonts>> (which you don't have to redeclare).
+If you want to use your own fonts, you must declare the name and location of each font in the <<Custom Fonts,font catalog>>.
+If you want to combine your own fonts with the bundled fonts, you can either extend the font catalog (by setting `merge: true`) or <<Extending the Font Catalog,redeclare the bundled fonts>> alongside your own.
 
-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.
+WARNING: If the theme doesn't specify any fonts (nor are they being inherited), 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.
 
@@ -1014,10 +1013,6 @@ If the filename is absolute, it's used as is.
 If the filename begins with `./`, it's resolved as a theme file relative to the current theme file.
 Otherwise, the filename is resolved as a theme file in the normal way (relative to the value of the `pdf-themesdir` attribute).
 
-CAUTION: If you define the <<Custom fonts,font catalog>> in a theme that extends from `default`, you either have to redeclare any built-in font that on which the combined theme depends, or you need to set `merge: true` above your font definitions.
-You can find the built-in definitions in default theme.
-If you are referring to a bundled font, you'll need to prefix the path with `GEM_FONTS_DIR` or add it to the value of the `pdf-fontsdir` attribute so the converter can find and register them.
-
 Currently, the base theme is always loaded first.
 Then, the files referenced by the extends key are loaded in order.
 Finally, the keys in the current file are loaded.
@@ -1035,6 +1030,50 @@ Each time a theme is loaded, the keys are overlaid onto the keys from the previo
 - ./brand-theme.yml
 |===
 
+=== Extending the Font Catalog
+
+If you define a <<Custom fonts,font catalog>> in a theme that extends from `default`, and you want to continue to use the bundled fonts in your theme, you either have to redeclare the bundled fonts:
+
+.Redeclaring the bundle fonts in a custom theme
+[source,yaml]
+----
+extends: default
+font:
+  catalog:
+    Noto Serif:
+      normal: GEM_FONTS_DIR/notoserif-regular-subset.ttf
+      bold: GEM_FONTS_DIR/notoserif-bold-subset.ttf
+      italic: GEM_FONTS_DIR/notoserif-italic-subset.ttf
+      bold_italic: GEM_FONTS_DIR/notoserif-bold_italic-subset.ttf
+    M+ 1mn:
+      normal: GEM_FONTS_DIR/mplus1mn-regular-subset.ttf
+      bold: GEM_FONTS_DIR/mplus1mn-bold-subset.ttf
+      italic: GEM_FONTS_DIR/mplus1mn-italic-subset.ttf
+      bold_italic: GEM_FONTS_DIR/mplus1mn-bold_italic-subset.ttf
+    Your Font:
+      normal: /path/to/your/font.ttf
+heading:
+  font-family: Your Font
+----
+
+or you need to set `merge: true` above your font definitions:
+
+.Merging with the inherited font catalog
+[source,yaml]
+----
+extends: default
+font:
+  catalog:
+    merge: true
+    Your Font:
+      normal: /path/to/your/font.ttf
+heading:
+  font-family: Your Font
+----
+
+If you're referring to a bundled font, you'll need to prefix the path with `GEM_FONTS_DIR` (or add it to the value of the `pdf-fontsdir` attribute) so the converter can find and register it.
+You can find the bundle font definitions in default theme.
+
 [#keys-role]
 === Role