resolves #2063 rewrite guide that explains how to create a CJK theme (PR #2064)

2 files changed, 101 insertions, 31 deletions

diff --git a/docs/modules/theme/pages/cjk.adoc b/docs/modules/theme/pages/cjk.adoc
index 2f497b9a..2f18bf25 100644
--- a/docs/modules/theme/pages/cjk.adoc
+++ b/docs/modules/theme/pages/cjk.adoc
@@ -1,50 +1,96 @@
 = Create a CJK Theme
 
-You also have to option of creating your own theme gem that uses fonts of your choice.
-For example, if you want to use the `asciidoctor-pdf-cjk-kai_gen_gothic` gem to fetch fonts, but then use them in your own theme, here's how you'd do it.
+If you're writing in a CJK language such as Simplified Chinese, you'll likely need to bring your own font by providing a custom theme.
+That's because it's not possible for Asciidoctor PDF to bundle the necessary fonts since they are too large.
+Fortunately, creating a theme to override the fonts requires very few steps, so you should be up and running with your own font in no time.
 
-. Install the `asciidoctor-pdf-cjk-kai_gen_gothic` gem:
+== Obtain the TTF fonts
 
- $ gem install asciidoctor-pdf-cjk-kai_gen_gothic
+The first step in creating a CJK theme is to obtain the fonts.
+It's important that the fonts are TTF since that's the only font format Asciidoctor PDF (via ttfunk) supports reliably.
 
-. Download / install the fonts:
+Unfortunately, good quality TTF fonts for CJK languages are hard to come by.
+We recommend starting with the https://github.com/googlefonts/noto-cjk/tree/main/Sans#ttf[Noto Sans Variable Fonts for CJK] provided by the noto-cjk project (Noto Sans and Noto Sans Mono).
+Just make sure you download the TTF variant.
 
- $ asciidoctor-pdf-cjk-kai_gen_gothic-install
+Once you have downloaded the fonts, place the files into the directory where you are going to create your theme.
+For the purpose of this guide, we'll assume you are working with the following font files:
 
-. Create a theme file named [.path]_cjk-theme.yml_ that extends the default theme to override the fonts:
-+
-[source,yml]
+* https://github.com/googlefonts/noto-cjk/raw/main/Sans/Variable/TTF/NotoSansCJKsc-VF.ttf[NotoSansCJKsc-VF.ttf]
+* https://github.com/googlefonts/noto-cjk/raw/main/Sans/Variable/TTF/NotoSansCJKsc-VF.ttf[NotoSansMonoCJKsc-VF.ttf]
+
+If you'd like to use different fonts, refer to the https://en.wikipedia.org/wiki/List_of_CJK_fonts[list of notable CJK fonts on Wikipedia].
+With that information, you can search for the TTF font on any font service.
+You can also find the Kai Gen Gothic fonts for CJK languages in TTF format on the https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic/releases[releases page] for the now deprecated asciidoctor-pdf-cjk-kai_gen_gothic project.
+
+== Create the theme file
+
+Now that you've obtained the TTF font files, you can create a new theme to use them.
+
+Create a theme file named [.path]_cjk-theme.yml_ where you can override the fonts:
+
+[,yaml]
 ----
 extends: default
 font:
   catalog:
     merge: true
-    KaiGen Gothic CN:
-      normal: KaiGenGothicCN-Regular.ttf
-      bold: KaiGenGothicCN-Bold.ttf
-      italic: KaiGenGothicCN-Regular-Italic.ttf
-      bold_italic: KaiGenGothicCN-Bold-Italic.ttf
+    Noto Sans CN: NotoSansCJKsc-VF.ttf
+    Noto Sans Mono CN: NotoSansMonoCJKsc-VF.ttf
   fallbacks:
-  - KaiGen Gothic CN
+  - Noto Serif
 base:
-  font-family: KaiGen Gothic CN
+  align: left
+  font-family: Noto Sans CN
+codespan:
+  font-family: Noto Sans Mono CN
+kbd:
+  font-family: $codespan-font-family
+code:
+  font-family: $codespan-font-family
+----
+
+This theme does several things:
+
+. Registers the Noto Sans CN and Noto Sans Mono CN fonts in the font catalog provided by the default theme
+. Sets the built-in Noto Serif font as the fallback font in cases when a glyph is not provided by the CJK font
+. Configures Noto Sans CN as the base font, which is used for all variable-width text in the document
+. Sets the default text alignment to left since text justification isn't well-suited for CJK languages
+. Configures Noto Sans Mono CN as the monospaced font, which is used for all monospaced text in the document
+
+If you're using different fonts for normal, bold, italic, and bold italic, you'll need to configure them using separate keys.
+Refer to xref:font.adoc#extend-catalog[Extending the font catalog] for details.
+
+TIP: When using your own fonts, be sure to consult the xref:prepare-custom-font.adoc[] to find recommended modifications.
+
+You may also want to darken the font color since the Noto Sans SC font has a thin weight.
+
+[,yaml]
+----
+...
+base:
+  align: left
+  font-color: #000000
+  font-family: Noto Sans CN
 heading:
-  font-family: $base-font-family
-abstract:
-  title:
-    font-family: $heading-font-family
-sidebar:
-  title:
-    font-family: $heading-font-family
+  font-color: #000000
+...
 ----
 
-. Load your theme when running Asciidoctor PDF:
+You may need to adjust the font color on other keys as well.
+
+== Load your theme
+
+Now that you've created the theme, you can put it to use.
+Since the theme provides custom fonts, you'll need to specify both the location of the theme file and the location of the fonts when calling Asciidoctor PDF.
+
+Let's assume that your theme is located in the [.path]_themes_ directory relative to your document.
+Here's how you specify the path to the theme and the fonts it uses:
 
- $ asciidoctor-pdf -a scripts=cjk -a pdf-theme=./cjk-theme.yml -a pdf-fontsdir=GEM_FONTS_DIR,`ruby -r asciidoctor-pdf-cjk-kai_gen_gothic -e "print File.expand_path '../fonts', (Gem.datadir 'asciidoctor-pdf-cjk-kai_gen_gothic')"` document.adoc
+ $ asciidoctor-pdf -a scripts=cjk -a pdf-theme=./themes/cjk-theme.yml -a pdf-fontsdir=./themes document.adoc
 
-The `-a pdf-fontsdir` option is important to tell Asciidoctor PDF where to find your custom fonts.
-//TODO This sentence and related example above need to be evaluated to remove PDF 1.5 references.
-(Note that the inclusion of GEM_FONTS_DIR in the value is only required when using Asciidoctor PDF 1.5).
+The `-a pdf-fontsdir` option is important because it tells Asciidoctor PDF where to look for the fonts specified in the theme.
+Alternately, the theme could specify the location of these fonts using an absolute path.
+The `scripts` option enables CJK support within Asciidoctor, which allows lines to break anywhere instead of at word boundaries.
 
-Rather than using the installer from the `asciidoctor-pdf-cjk-kai_gen_gothic` gem, you can download fonts whatever way you choose.
-When using your own fonts, be sure to consult the xref:prepare-custom-font.adoc[] to find recommended modifications.
+If you've followed the instructions correctly, you should see that there are few (if any) missing glyphs in your PDF document.
diff --git a/docs/modules/theme/pages/font-support.adoc b/docs/modules/theme/pages/font-support.adoc
index f0919a74..de575996 100644
--- a/docs/modules/theme/pages/font-support.adoc
+++ b/docs/modules/theme/pages/font-support.adoc
@@ -5,7 +5,7 @@
 :url-w1252: https://en.wikipedia.org/wiki/Windows-1252
 :url-prawn-afm: https://github.com/prawnpdf/prawn/blob/master/CHANGELOG.md#vastly-improved-handling-of-encodings-for-pdf-built-in-afm-fonts
 
-You can select from <<built-in,built-in fonts>>, <<bundled,fonts bundled with Asciidoctor PDF>> or xref:custom-font.adoc[custom fonts] loaded from TrueType (TTF) or OpenType (OTF) font files.
+You can select from <<built-in,built-in fonts>>, <<bundled,fonts bundled with Asciidoctor PDF>>, or xref:custom-font.adoc[custom fonts] loaded from TrueType (TTF) or OpenType (OTF) font files.
 If you want to use custom fonts, you must first declare them in your theme file.
 
 IMPORTANT: Asciidoctor has no challenge working with Unicode.
@@ -99,3 +99,27 @@ TIP: The default themes refer to the bundled fonts using the `GEM_FONTS_DIR` pre
 That means you can extend a default theme and not have to worry about how the bundled fonts get resolved.
 If you redeclare the bundled fonts in your custom theme, be sure to prefix the path with the `GEM_FONTS_DIR` token.
 An alternative approach is to include `GEM_FONT_DIR` in the value of the `pdf-fontsdir` attribute separated by the location of your custom fonts using a comma (e.g., `path/to/your/fonts,GEM_FONTS_DIR`) or a semicolon (e.g., `path/to/your/fonts;GEM_FONTS_DIR`).
+
+== Support for non-Latin languages
+
+Asciidoctor PDF can process the full range of characters in the UTF-8 character set.
+That means you can write your document in any language, save the file with UTF-8 encoding (_that's important!_), and expect Asciidoctor PDF to convert the text properly.
+But you still need a font that provides the glyphs for those characters.
+
+When converting a document with Asciidoctor PDF, you may notice that some glyphs for certain languages, such as Simplified Chinese, are missing from the PDF.
+PDF is a "`bring your own font`" kind of system.
+In other words, the font you provide must provide glyphs for all the characters used.
+There's no single font that supports all the world's languages (though some, like Noto Sans and Noto Serif, certainly come close).
+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.
+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
+
+Notice the `-a scripts=cjk` option.
+That's important.
+It tells the converter to insert break opportunities between CJK characters so that lines wrap properly when mixing English and a CJK language like Japanese.
+
+If the built-in theme with the fallback font doesn't go far enough, you'll need create a xref:cjk.adoc[custom CJK theme].