resolves #2163 rename theme suffix with-fallback-font to with-font-fa…

…llbacks; add built-in default-sans theme (PR #2168)

CHANGELOG.adoc

@@ -22,9 +22,12 @@ Enhancements::
 * configure `typeset_text` and `ink_prose` to return remaining fragments when `:height` option is specified
 * add support for `:indent_paragraphs` option to formatted text box (#353)
 * if `float` attribute is set on block image, set max width on caption to `fit-content` if max width not already set to a `fit-content` value
+* add built-in default-sans theme
 
 Improvements::
 
+* rename theme suffix with-fallback-font to with-font-fallbacks
+* rename sans-with-fallback-font theme to default-sans-with-font-fallbacks
 * configure spacing around thematic break using `thematic-break-padding` key instead of margin top and bottom (#2164)
 * rename `convert_listing_or_literal` to `convert_code` and alias old name
 * reify convert handler for STEM blocks (`convert_stem`)

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

@@ -1,3 +1,2 @@
-extends:
-- default-for-print
-- default-with-fallback-font
+# DEPRECATED
+extends: default-for-print-with-font-fallbacks

data/themes/default-for-print-with-font-fallbacks-theme.yml

@@ -0,0 +1,3 @@
+extends:
+- default-with-font-fallbacks
+- default-for-print

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

@@ -1,4 +1,4 @@
-extends: default-with-fallback-font
+extends: default
 font:
   catalog:
     merge: true

data/themes/default-sans-with-font-fallbacks-theme.yml

@@ -0,0 +1,3 @@
+extends:
+- default-with-font-fallbacks
+- default-sans

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

@@ -1,9 +1,2 @@
-extends: default
-font:
-  catalog:
-    merge: true
-    # 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: GEM_FONTS_DIR/mplus1p-regular-fallback.ttf
-    Noto Emoji: GEM_FONTS_DIR/notoemoji-subset.ttf
-  fallbacks: [M+ 1p Fallback, Noto Emoji]
+# DEPRECATED
+extends: default-with-font-fallbacks

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

@@ -0,0 +1,9 @@
+extends: default
+font:
+  catalog:
+    merge: true
+    # 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: GEM_FONTS_DIR/mplus1p-regular-fallback.ttf
+    Noto Emoji: GEM_FONTS_DIR/notoemoji-subset.ttf
+  fallbacks: [M+ 1p Fallback, Noto Emoji]

docs/modules/theme/pages/fallback-font.adoc

@@ -11,7 +11,7 @@ IMPORTANT: The fallback font only gets used when the primary font is a TrueType
 Any glyph missing from an AFM font is simply replaced with the "`not`" glyph (`¬`).
 
 CAUTION: The `default` theme does not use a fallback font.
-However, the built-in `default-with-fallback-font` theme does.
+However, the built-in `default-with-font-fallbacks` theme does.
 In fact, it provides two.
 One for general writing in non-Latin languages (M+ 1p) and another for emoji (Noto Emoji).
 Using the fallback font slows down PDF generation slightly because it has to analyze every single character.
@@ -83,7 +83,7 @@ Here's another example that shows how to use an alternative emoji font (Symbola)
 
 [,yaml]
 ----
-extends: default-with-fallback-font
+extends: default-with-font-fallbacks
 font:
   catalog:
     merge: true

docs/modules/theme/pages/font-support.adoc

@@ -95,11 +95,11 @@ A serif font that can be styled as `normal`, `italic`, `bold`, or `bold_italic`.
 {url-mplus-onep}[M+ 1p^]::
 A sans-serif font that provides a very complete set of Unicode glyphs.
 M+ 1p can only be styled as `normal`.
-This font is used as the fallback font in the `default-with-fallback-font` theme.
+This font is used as the fallback font in the `default-with-font-fallbacks` theme.
 
-{url-noto-emoji}[Noto Emoji^]:: A font of emojis used as a fallback font in the `default-with-fallback-font` theme.
+{url-noto-emoji}[Noto Emoji^]:: A font of emojis used as a fallback font in the `default-with-font-fallbacks` theme.
 
-{url-noto-sans}[Noto Sans^]:: A sans font that is used as the fallback font in the `sans-with-fallback-font` theme.
+{url-noto-sans}[Noto Sans^]:: A sans font that is used as the fallback font in the `default-sans-with-font-fallbacks` theme.
 It can be styled as `normal`, `italic`, `bold`, or `bold_italic`.
 
 TIP: The default themes refer to the bundled fonts using the `GEM_FONTS_DIR` prefix.
@@ -120,10 +120,10 @@ There's no single font that supports all the world's languages (though some, lik
 Even if there were such a font, bundling that font with the main gem would make it *enormous*.
 It would also severely limit the style choices in the default theme, which caters to Latin-based languages.
 
-If you're writing in a CJK language, such as Japanese, Asciidoctor PDF provides a built-in theme named `default-with-fallback-font` that provides a broad range of characters in the CJK charsets.
+If you're writing in a CJK language, such as Japanese, Asciidoctor PDF provides a built-in theme named `default-with-font-fallbacks` that provides a broad range of characters in the CJK charsets.
 You can start with that theme to see how far it gets you:
 
- $ asciidoctor-pdf -a scripts=cjk -a pdf-theme=default-with-fallback-font document.adoc
+ $ asciidoctor-pdf -a scripts=cjk -a pdf-theme=default-with-font-fallbacks document.adoc
 
 Notice the `-a scripts=cjk` option.
 That's important.

spec/converter_spec.rb

@@ -264,6 +264,19 @@
         (expect pdf.find_text font_color: '000000').to have_size pdf.text.size
       end
 
+      it 'should set font family to Noto Sans when default-sans themme is specified' do
+        pdf = to_pdf <<~EOS, analyze: true
+        = Document Title
+        :pdf-theme: default-sans
+
+        We don't like those _pesky_ serifs in these here parts.
+        EOS
+
+        text = pdf.text
+        sans_text = text.select {|it| it[:font_name].start_with? 'NotoSans' }
+        (expect sans_text).to have_size text.size
+      end
+
       it 'should use theme passed in through :pdf_theme option' do
         theme = Asciidoctor::PDF::ThemeLoader.load_theme 'custom', fixtures_dir
         theme.base_font_size = 14

spec/fixtures/glyph-font-test.adoc

@@ -35,7 +35,7 @@ in⁠divisible
 almost touching
 // no-break hyphen
 fast‑approaching
-ifeval::["{pdf-theme}"=="default-with-fallback-font"]
+ifeval::["{pdf-theme}"=="default-with-font-fallbacks"]
 // check mark
 ✓ done
 // upside down e

spec/font_spec.rb

@@ -10,6 +10,7 @@
       (expect to_file).to visually_match 'font-i18n-default.pdf'
     end
 
+    # intentionally use the deprecated alias for this test
     it 'should apply fallback font when using default theme with fallback font', visual: true do
       input_file = Pathname.new fixture_file 'i18n-font-test.adoc'
       (expect do
@@ -26,24 +27,24 @@
 
     it 'should include expected glyphs in bundled default font with fallback font', visual: true do
       input_file = Pathname.new fixture_file 'glyph-font-test.adoc'
-      to_file = to_pdf_file input_file, 'font-glyph-default-with-fallback.pdf', attribute_overrides: { 'pdf-theme' => 'default-with-fallback-font' }
+      to_file = to_pdf_file input_file, 'font-glyph-default-with-fallback.pdf', attribute_overrides: { 'pdf-theme' => 'default-with-font-fallbacks' }
       (expect to_file).to visually_match 'font-glyph-default-with-fallback.pdf'
     end
 
     it 'should include expected glyphs in fallback font', visual: true do
       input_file = Pathname.new fixture_file 'glyph-font-test.adoc'
-      to_file = to_pdf_file input_file, 'font-glyph-fallback-only.pdf', pdf_theme: { extends: 'default-with-fallback-font', base_font_family: 'M+ 1p Fallback' }, attribute_overrides: { 'pdf-theme' => 'default-with-fallback-font' }
+      to_file = to_pdf_file input_file, 'font-glyph-fallback-only.pdf', pdf_theme: { extends: 'default-with-font-fallbacks', base_font_family: 'M+ 1p Fallback' }, attribute_overrides: { 'pdf-theme' => 'default-with-font-fallbacks' }
       (expect to_file).to visually_match 'font-glyph-fallback-only.pdf'
     end
 
     it 'should use notdef from original font of glyph not found in any fallback font', visual: true do
       input = ?\u0278 * 10
-      to_file = to_pdf_file input, 'font-notdef-glyph.pdf', attribute_overrides: { 'pdf-theme' => 'default-with-fallback-font' }
+      to_file = to_pdf_file input, 'font-notdef-glyph.pdf', attribute_overrides: { 'pdf-theme' => 'default-with-font-fallbacks' }
       (expect to_file).to visually_match 'font-notdef-glyph.pdf'
     end
 
     it 'should use glyph from fallback font if not present in primary font', visual: true do
-      to_file = to_pdf_file '*を*', 'font-fallback-font.pdf', attribute_overrides: { 'pdf-theme' => 'default-with-fallback-font' }
+      to_file = to_pdf_file '*を*', 'font-fallback-font.pdf', attribute_overrides: { 'pdf-theme' => 'default-with-font-fallbacks' }
       (expect to_file).to visually_match 'font-fallback-font.pdf'
     end
 
@@ -80,7 +81,7 @@
     end
 
     it 'should render emoji when using default theme with fallback font', visual: true do
-      to_file = to_pdf_file <<~'EOS', 'font-emoji.pdf', attribute_overrides: { 'pdf-theme' => 'default-with-fallback-font' }
+      to_file = to_pdf_file <<~'EOS', 'font-emoji.pdf', attribute_overrides: { 'pdf-theme' => 'default-with-font-fallbacks' }
       Don't 😢 over spilled 🍺.
 
       Asciidoctor is 👍.
@@ -90,7 +91,7 @@
     end
 
     it 'should use sans base font when using sans theme with fallback font', visual: true do
-      to_file = to_pdf_file <<~'EOS', 'font-sans-emoji.pdf', attribute_overrides: { 'pdf-theme' => 'sans-with-fallback-font' }
+      to_file = to_pdf_file <<~'EOS', 'font-sans-emoji.pdf', attribute_overrides: { 'pdf-theme' => 'default-sans-with-font-fallbacks' }
       == Lessons
 
       Don't 😢 over spilled 🍺.
@@ -105,7 +106,7 @@
       (expect do
         input_lines = [%(Bitcoin (\u20bf) is a cryptocurrency.), %(The currency is represented using the symbol \u20bf.)]
         input = input_lines.join %(\n\n)
-        pdf = to_pdf input, attribute_overrides: { 'pdf-theme' => 'default-with-fallback-font' }, analyze: true
+        pdf = to_pdf input, attribute_overrides: { 'pdf-theme' => 'default-with-font-fallbacks' }, analyze: true
         (expect pdf.lines).to eql input_lines
       end).to log_message severity: :WARN, message: %(Could not locate the character `\u20bf' (\\u20bf) in the following fonts: Noto Serif, M+ 1p Fallback, Noto Emoji), using_log_level: :INFO
     end
@@ -309,7 +310,7 @@
     it 'should break line on any CJK character if value of scripts attribute is cjk' do
       pdf = to_pdf <<~'EOS', analyze: true
       :scripts: cjk
-      :pdf-theme: default-with-fallback-font
+      :pdf-theme: default-with-font-fallbacks
 
       AsciiDoc 是一个人类可读的文件格式，语义上等同于 DocBook 的 XML，但使用纯文本标记了约定。可以使用任何文本编辑器创建文件把 AsciiDoc 和阅读“原样”，或呈现为HTML 或由 DocBook 的工具链支持的任何其他格式，如 PDF，TeX 的，Unix 的手册页，电子书，幻灯片演示等。
 
@@ -324,6 +325,7 @@
       (expect lines[4]).to start_with 'して'
     end
 
+    # intentionally use the deprecated alias for this test
     it 'should not break line immediately before an ideographic full stop' do
       pdf = to_pdf <<~'EOS', analyze: true
       :scripts: cjk

spec/image_spec.rb

@@ -1544,7 +1544,7 @@
     end
 
     it 'should only render inline image once if alt text is chunked to apply a fallback font' do
-      pdf = to_pdf <<~'EOS', attribute_overrides: { 'imagesdir' => examples_dir, 'pdf-theme' => 'default-with-fallback-font' }, analyze: :image
+      pdf = to_pdf <<~'EOS', attribute_overrides: { 'imagesdir' => examples_dir, 'pdf-theme' => 'default-with-font-fallbacks' }, analyze: :image
       How many wolpertingers do you see? +
       image:wolpertinger.jpg[チのデータレプリケーションです。]
       EOS

spec/list_spec.rb

@@ -250,7 +250,7 @@
 
     it 'should reserve enough space for marker that is not found in any font' do
       pdf_theme = {
-        extends: 'default-with-fallback-font',
+        extends: 'default-with-font-fallbacks',
         ulist_marker_disc_content: ?\u2055,
       }
       pdf = to_pdf <<~'EOS', pdf_theme: pdf_theme, analyze: true
@@ -486,7 +486,7 @@
     end
 
     it 'should use glyph from fallback font if not present in main font', visual: true do
-      pdf_theme = build_pdf_theme({ ulist_marker_checked_content: ?\u303c }, 'default-with-fallback-font')
+      pdf_theme = build_pdf_theme({ ulist_marker_checked_content: ?\u303c }, 'default-with-font-fallbacks')
 
       to_file = to_pdf_file <<~'EOS', 'list-checked-glyph-fallback.pdf', pdf_theme: pdf_theme
       * [x] done

spec/table_spec.rb

@@ -2779,7 +2779,7 @@
     it 'should break line on any CJK character if value of scripts attribute is cjk' do
       pdf = to_pdf <<~'EOS', analyze: true
       :scripts: cjk
-      :pdf-theme: default-with-fallback-font
+      :pdf-theme: default-with-font-fallbacks
 
       |===
       | AsciiDoc 是一个人类可读的文件格式，语义上等同于 DocBook 的 XML，但使用纯文本标记了约定。可以使用任何文本编辑器创建文件把 AsciiDoc 和阅读“原样”，或呈现为HTML 或由 DocBook 的工具链支持的任何其他格式，如 PDF，TeX 的，Unix 的手册页，电子书，幻灯片演示等。