add subsections to the Custom Fonts section in the theming guide and rearrange content to fit

1 files changed, 48 insertions, 30 deletions

diff --git a/docs/theming-guide.adoc b/docs/theming-guide.adoc
index e36ecd3b..c8c8d3ae 100644
--- a/docs/theming-guide.adoc
+++ b/docs/theming-guide.adoc
@@ -760,8 +760,13 @@ To do so, you can either a) prefix the path of the bundled font in the theme fil
 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.
 
+IMPORTANT: In order for a third-party font to work properly with Prawn (and hence Asciidoctor PDF), several modifications are required.
+See <<Preparing a Custom Font>> to learn how to prepare your font for use with Asciidoctor PDF.
+
+==== Selecting Your Font
+
 To start, find the TTF file collection for the font you want to use.
-A collection typically consists of all four font styles:
+A collection typically consists of four font styles:
 
 * normal
 * italic
@@ -769,12 +774,10 @@ A collection typically consists of all four font styles:
 * bold_italic
 
 You'll need all four variants to support AsciiDoc content properly.
-Otherwise, the converter will likely crash.
-If you don't have one of the variants, you can simply reuse the normal variant in its place.
-_Asciidoctor PDF cannot italicize a font dynamically like a browser can, so the italic styles are required._
+Otherwise, the converter will either crash or revert to the fallback font, depending on how your theme is configured.
+If one of the variants is missing from your collection, you can simply reuse the normal variant in its place.
 
-In order for a third-party font to work properly with Prawn (and hence Asciidoctor PDF), several modifications are required.
-See <<Preparing a Custom Font>> to learn how to prepare your font for use with Asciidoctor PDF.
+WARNING: 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 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.
@@ -787,6 +790,8 @@ Rename the files as follows:
 * roboto-bold.ttf (_originally Roboto-Bold.ttf_)
 * roboto-bold_italic.ttf (_originally Roboto-BoldItalic.ttf_)
 
+==== Declaring Your Font
+
 Next, declare the font under the `font-catalog` key at the top of your theme file, giving it a unique key (e.g., `Roboto`).
 
 [source,yaml]
@@ -803,6 +808,25 @@ font:
 CAUTION: You must declare all four variants.
 If you're missing the font file for one of the variants, configure it to use the same font file as the normal variant.
 
+You can add any number of fonts to the catalog.
+Each font must be assigned a unique key, as shown here:
+
+[source,yaml]
+----
+font:
+  catalog:
+    Roboto:
+      normal: roboto-normal.ttf
+      italic: roboto-italic.ttf
+      bold: roboto-bold.ttf
+      bold_italic: roboto-bold_italic.ttf
+    Roboto Light:
+      normal: roboto-light-normal.ttf
+      italic: roboto-light-italic.ttf
+      bold: roboto-light-bold.ttf
+      bold_italic: roboto-light-bold_italic.ttf
+----
+
 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 example, to use the Roboto font for all headings (section titles and discrete headings), use:
 
@@ -810,8 +834,22 @@ For example, to use the Roboto font for all headings (section titles and discret
 ----
 heading:
   font-family: Roboto
+  font-style: bold
 ----
 
+The font name and font style are used to locate an entry in the font catalog.
+
+.About Fonts in SVGs
+****
+Fonts defined for text in SVGs will be mapped to the font catalog from your theme.
+So if you have an SVG that requires a specific font, you'll need to declare that font in the font catalog in 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.
+****
+
+==== Configuring the Font Search Path
+
 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
@@ -832,36 +870,16 @@ When running Asciidoctor PDF on the JVM (perhaps using AsciidoctorJ PDF), you ca
 
  $ asciidoctorj -b pdf -a pdf-theme=basic-theme.yml -a pdf-fontsdir="uri:classloader:/path/to/fonts;GEM_FONTS_DIR" document.adoc
 
-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.
+==== Subsetting Your Font
+
+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 is 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:
-
-[source,yaml]
-----
-font:
-  catalog:
-    Roboto:
-      normal: roboto-normal.ttf
-      italic: roboto-italic.ttf
-      bold: roboto-bold.ttf
-      bold_italic: roboto-bold_italic.ttf
-    Roboto Light:
-      normal: roboto-light-normal.ttf
-      italic: roboto-light-italic.ttf
-      bold: roboto-light-bold.ttf
-      bold_italic: roboto-light-bold_italic.ttf
-----
-
-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 or emoji, you can have Asciidoctor PDF look for the character in a fallback font.