1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
= Fonts
:url-noto-serif: https://fonts.google.com/noto/specimen/Noto+Serif
:url-mplus-onemn: https://mplus-fonts.osdn.jp/mplus-outline-fonts/design/index-en.html#mplus_1mn
:url-mplus-onep: https://mplus-fonts.osdn.jp/mplus-outline-fonts/design/index-en.html#mplus_1p
:url-noto-sans: https://fonts.google.com/noto/specimen/Noto+Sans
:url-noto-emoji: https://fonts.google.com/noto/specimen/Noto+Emoji/about
: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.
If you want to use custom fonts, you must first declare them in your theme file.
IMPORTANT: Asciidoctor has no challenge working with Unicode.
In fact, it prefers Unicode and considers the entire range.
However, once you convert to PDF, you have to meet the font requirements of PDF in order to preserve Unicode characters.
That means you need to provide a font (at least a fallback font) that contains glyphs for all the characters you want to use.
If you don't, you may notice that characters are missing (usually replaced with a box).
There's nothing Asciidoctor can do to convince PDF to work with extended characters without the right fonts in play.
To see which characters are missing from the font, enable verbose mode (`-v`) when running Asciidoctor PDF.
[#built-in]
== Built-In (AFM) fonts
The names of the built-in fonts (for general-purpose text) are as follows:
[width=33.33%]
|===
|Font Name |Font Family
|Helvetica
|sans-serif
|Times-Roman
|serif
|Courier
|monospace
|===
Using a built-in font requires no additional files.
You can use the key anywhere a `font-family` property is accepted in the theme file.
For example:
[,yaml]
----
base:
font-family: Times-Roman
----
However, when you use a built-in font, the characters you can use in your document are limited to the characters in the WINANSI ({url-w1252}[Windows-1252^]) code set.
WINANSI includes most of the characters needed for writing in Western languages (English, French, Spanish, etc).
For anything outside of that, PDF is BYOF (Bring Your Own Font).
Even though the built-in fonts require the content to be encoded in WINANSI, _you still type your AsciiDoc document in UTF-8_.
Asciidoctor PDF encodes the content into WINANSI when building the PDF.
WARNING: Built-in (AFM) fonts do not use the xref:fallback-font.adoc[fallback fonts].
In order for the fallback font to kick in, you must use a TrueType font anywhere you want the fallback font to be used (e.g., the base font family, the code font family, etc).
.WINANSI Encoding Behavior
****
When using the built-in PDF (AFM) fonts on a block of content in your AsciiDoc document, any character that cannot be encoded to WINANSI is replaced with a logic "`not`" glyph (`¬`) and you'll see the following warning in your console:
The following text could not be fully converted to the Windows-1252 character set:
| <string with unknown glyph>
This behavior differs from the default behavior in Prawn, which is to simply crash.
You'll often see this warning if you're using callouts in your document and you haven't specified a TrueType font in your theme.
To prevent this warning, you need to specify a TrueType font.
When using a TrueType font, you will get no warning for a missing glyph.
That's a consequence of how Prawn works and is outside of Asciidoctor PDF's control.
However, you'll likely see it substituted with a box (guaranteed if you're using one of the bundled fonts).
For more information about how Prawn handles character encodings for built-in fonts, see {url-prawn-afm}[this note in the Prawn CHANGELOG^].
****
[#bundled]
== Bundled fonts
Asciidoctor PDF bundles several fonts that are used by the default theme or a fallback font theme that extends the default theme.
You can also declare these fonts in your custom theme.
These fonts provide more characters than the built-in PDF fonts, but still only a subset of UTF-8 (to reduce the size of the gem).
The family names of the fonts bundled with Asciidoctor PDF are as follows:
{url-mplus-onemn}[M+ 1mn^]::
A monospaced font that maps different thicknesses to the styles `normal`, `italic`, `bold`, and `bold_italic`.
M+ 1mn also provides the circled numbers used for callouts and callout lists.
{url-noto-serif}[Noto Serif^]::
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-font-fallbacks` 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 `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.
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`).
== Custom Fonts
To learn how to use a custom font in your theme alongside or in place of built-in or bundled fonts, refer to xref:custom-font.adoc[].
== 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-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-font-fallbacks 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 to create a xref:cjk.adoc[custom CJK theme].
|
