source: x/installing/tuning-fontconfig.xml@ 9d8ea23

12.1 12.2 gimp3 ken/TL2024 ken/tuningfonts lazarus plabs/newcss python3.11 rahul/power-profiles-daemon trunk xry111/for-12.3 xry111/llvm18 xry111/spidermonkey128
Last change on this file since 9d8ea23 was 9d8ea23, checked in by Ken Moffat <ken@…>, 10 months ago

tuningfonts: Add lings to navigate, some more command examples.

  • Property mode set to 100644
File size: 36.2 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6]>
7
8<sect1 id="tuning-fontconfig">
9 <?dbhtml filename="tuning-fontconfig.html"?>
10
11
12 <title>Tuning Fontconfig</title>
13
14 <indexterm zone="tuning-fontconfig">
15 <primary sortas="g-tuning-fontconfig">Tuning Fontconfig</primary>
16 </indexterm>
17
18 <sect2 id='fontconfig-overview' xreflabel="Overview of Fontconfig">
19 <title>Overview of Fontconfig</title>
20
21<!-- do not add individual indexterm entries for items within this page, they
22 all belong in section G (others) and not only do they add noise in longindex,
23 the links all point to the top of the page. -->
24
25 <para>
26 If you only read text in English, and are happy with the common libre
27 fonts listed on the next page, you may never need to worry about the
28 details of how <application>fontconfig</application> works. But there are
29 many things which can be altered if they do not suit your needs.
30 </para>
31
32 <para>
33 Although this page is long, it barely scratches the surface and you will
34 be able to find many alternative views on the web (but please remember
35 that some things have changed over the years, for example the autohinter
36 is no longer the default). The aim here is to give you enough information
37 to understand the changes you are making.
38 </para>
39
40 <para>The following links are to assist navigation in this page.</para>
41 <itemizedlist>
42 <listitem>
43 <para><xref linkend="xft-font-protocol"/></para>
44 </listitem>
45 <listitem>
46 <para><xref linkend="useful-commands"/></para>
47 </listitem>
48 <listitem>
49 <para><xref linkend="the-various-files"/></para>
50 </listitem>
51 <listitem>
52 <para><xref linkend="rules-to-choose-a-font"/></para>
53 </listitem>
54 <listitem>
55 <para><xref linkend="hinting-and-antialiasing"/></para>
56 </listitem>
57 <listitem>
58 <para><xref linkend="disabling-bitmap-fonts"/></para>
59 </listitem>
60 <listitem>
61 <para><xref linkend="adding-extra-directories"/></para>
62 </listitem>
63 <listitem>
64 <para><xref linkend="preferring-certain-fonts"/></para>
65 </listitem>
66 <listitem>
67 <para><xref linkend="fontconfig-user-docs"/></para>
68 </listitem>
69 <listitem>
70 <para><xref linkend="prefer-a-specific-font"/></para>
71 </listitem>
72 <listitem>
73 <para><xref linkend="prefer-chosen-CJK-fonts"/></para>
74 </listitem>
75 <listitem>
76 <para><xref linkend="editing-old-style-conf-files"/></para>
77 </listitem>
78 <listitem>
79 <para><xref linkend="see-also"/></para>
80 </listitem>
81 </itemizedlist>
82
83 </sect2>
84
85 <sect2 role="configuration" id="xft-font-protocol" xreflabel="The Xft Font Protocol">
86 <title>The Xft Font Protocol</title>
87
88 <para>
89 The Xft font protocol provides antialiased font rendering through
90 <application>freetype</application>, and fonts are controlled from the
91 client side using <application>fontconfig</application> (except for
92 <xref linkend="rxvt-unicode"/> which can use fonts listed in
93 <filename>~/.Xresources</filename>, and <xref linkend="abiword"/> which
94 only uses the specified font). The default search path is <filename
95 class="directory">/usr/share/fonts</filename> and <filename
96 class="directory">~/.local/share/fonts</filename>, although for the moment
97 the old and deprecated location <filename
98 class="directory">~/.fonts</filename> still works.
99 <application>Fontconfig</application> searches directories in its path
100 recursively and maintains a cache of the font characteristics in each
101 directory. If the cache appears to be out of date, it is ignored, and
102 information is fetched from the fonts themselves (that can take a few
103 seconds if you have a lot of fonts installed).
104 </para>
105
106 <para>
107 If you've installed <application>Xorg</application> in any prefix
108 other than <filename class="directory">/usr</filename>, any
109 <application>X</application> fonts were not installed in a
110 location known to <application>Fontconfig</application>. Symlinks were
111 <!-- fonts-misc-ethiopic installs an OTF directory ! -->
112 created from the <filename class="directory">OTF</filename> and <filename
113 class="directory">TTF</filename> <application>X</application> font
114 directories to <filename
115 class="directory">/usr/share/fonts/X11-{OTF,TTF}</filename>. This allows
116 <application>Fontconfig</application> to use the OpenType and TrueType
117 fonts provided by <application>X</application>, although many people will
118 prefer to use more modern fonts.
119 </para>
120
121 <para>
122 <application>Fontconfig</application> uses names to define fonts.
123 Applications generally use generic font names such as "Monospace", "Sans"
124 and "Serif". <application>Fontconfig</application> resolves these names
125 to a font that has all characters that cover the orthography of the
126 language indicated by the locale settings.
127 </para>
128
129 </sect2>
130
131 <sect2 role="configuration" id="useful-commands" xreflabel="Useful Commands">
132 <title>Useful Commands</title>
133
134 <para>
135 The following commands may be helpful when working with fontconfig,
136 particularly if you are interested in overriding which font will be
137 chosen. 'TYPE' should be one of serif, sans-serif or monospace.
138 </para>
139
140 <para>
141 <command>fc-list | less</command> : shows a list of all available fonts
142 (/path/to/filename: Font Name:style). If you installed a font more than
143 30 seconds ago but it does not show, then it or one of its directories is
144 not readable by your user.
145 </para>
146
147 <para>
148 <command>fc-match 'Font Name'</command> : tells you which font will
149 be used if the named font is requested. Typically you would use this to
150 see what happens if a font you have not installed is requested, but you
151 can also use it if the system is giving you a different font from
152 what you expected (perhaps because <application>fontconfig</application>
153 does not think that the font supports your language).
154 </para>
155
156 <para>
157 <command>fc-match -a <replaceable>Type</replaceable> | less</command> :
158 provides a list of all fonts which can be used for that type (Monospace,
159 Sans Sasn-serif, Serif <emphasis>(capital letters optional)</emphasis>).
160 Note that in-extremis <application>fontconfig</application> will take a
161 glyph from any available font, even if it is not of the specified type,
162 and unless it knows about the font's type it will assume it is Sans.
163 </para>
164
165 <para>
166 <command>fc-match 'Serif :lang=ja:weight=bold'</command> will tell you
167 which font and weight will be chosen for Japanese text in bold weight.
168 It does not mean that the reported font will necessarily be able to show
169 Japanese ideograms, so a fallback might be used, or some glyphs may be
170 missing. For language codes use ISO-639 value such as 'fr', 'ja', 'zh-cn'.
171 Note that an unrecognized value such as just 'zh' will not return any
172 match. To illustrate the fallback, on a system wherei both Noto Sans Mono
173 and DejaVu Sans Mono are installed, <command>fc-match 'monospace
174 :lang=en</command> shows Noto Sans Mono will be used, but if the lang is
175 changed to 'ar' (arabic) DejaVu Sans will be used.
176 </para>
177
178 <para>
179 If you wish to know which font will be used for a string of text
180 (i.e. one or more glyphs, preceded by a space), paste the following
181 command and replace the <literal>xyz</literal> by the text you care
182 about:
183 </para>
184
185 <para>
186 <command>FC_DEBUG=4 pango-view --font=monospace -t xyz | grep
187 family</command> : this requires <xref linkend="pango"/> and <xref
188 linkend="imagemagick"/> - it will invoke <xref linkend="display"/>
189 to show the text in a tiny window, and after closing that the last
190 line of the output will show which font was chosen. This is
191 particularly useful for CJK languages, and you can also pass a
192 language, e.g. PANGO_LANGUAGE=en;ja (English, then assume Japanese)
193 or just zh-cn (or other variants such as zh-sg or zh-tw).
194 </para>
195
196 </sect2>
197
198 <sect2 role="configuration" id="the-various-files" xreflabel="The configuration files">
199 <title>The configuation files</title>
200
201 <para>
202 The main files are in <filename class="directory">/etc/fonts/conf.d/</filename>,
203 which was intended to be a directory populated by symlinks to some of the files
204 in <filename class="directory">/usr/share/fontconfig/conf.avail/</filename>.
205 But many people, and some packages, create the files directly. Each file name
206 must be in the form of two digits, a dash, somename.conf and they are read in
207 sequence.
208 </para>
209
210 <para>
211 By convention, the numbers are assigned as follows:
212 </para>
213
214 <itemizedlist>
215 <listitem>
216 <para>
217 00-09 extra font directories
218 </para>
219 </listitem>
220 <listitem>
221 <para>
222 10-19 system rendering defaults (such as antialiasing)
223 </para>
224 </listitem>
225 <listitem>
226 <para>
227 20-29 font rendering options
228 </para>
229 </listitem>
230 <listitem>
231 <para>
232 30-39 family substitution
233 </para>
234 </listitem>
235 <listitem>
236 <para>
237 40-49 map family to generic type
238 </para>
239 </listitem>
240 <listitem>
241 <para>
242 50-59 load alternate config files
243 </para>
244 </listitem>
245 <listitem>
246 <para>
247 60-69 generic aliases, map generic to family
248 </para>
249 </listitem>
250 <listitem>
251 <para>
252 70-79 adjust which fonts are available
253 </para>
254 </listitem>
255 <listitem>
256 <para>
257 80-89 match target scan (modify scanned patterns)
258 </para>
259 </listitem>
260 <listitem>
261 <para>
262 90-99 font synthesis
263 </para>
264 </listitem>
265 </itemizedlist>
266
267 <para>
268 You can also have a personal <filename>fonts.conf</filename> in
269 $XDG_CONFIG_HOME (which is <filename
270 class="directory">~/.config/fontconfig/</filename>).
271 </para>
272
273 </sect2>
274
275 <sect2 role="configuration" id="rules-to-choose-a-font" xreflabel="The rules to choose a font">
276 <title>The rules to choose a font</title>
277
278 <para>
279 If the requested font is installed, and provided it contains the
280 codepoints <emphasis>required</emphasis> for the current language (in the
281 source, see the .orth files in the <filename
282 class="directory">fc-lang/</filename> directory), it will be used.
283 </para>
284
285 <note>
286 <para>
287 In fontconfig-2.14 the defaults were changed to Noto fonts. Some of the
288 detail here is out of date and will be revised.
289 </para>
290 </note>
291
292 <para>
293 However, if the document or page requested a font which is not installed
294 (or, occasionally, does not contain all the required codepoints) the
295 following rules come into play: First,
296 <filename>30-metric-aliases.conf</filename> is used to map aliases for
297 some fonts with the same metrics (same size, etc). Note that there are
298 both weak and strong aliases so that aliases for one form such as
299 Helvetica or Times New Roman can be stisfied by the other style, i.e.
300 anything which is an alias of Arial or Times in those examples.
301 After that, an unknown font will be searched for in
302 <filename>45-latin.conf</filename>:
303 'Latin' covers Cyrillic and Greek, and now also maps system-ui fonts which
304 are used for User Interface messages in other alphabets. If the font
305 is found it will be mapped as serif, sans-serif, monospace, fantasy,
306 cursive, or system-ui. Otherwise, 49-sansserif.conf will assume it is
307 Sans.
308 </para>
309 <para>
310 Then <filename>60-latin.conf</filename>
311 provides ordered lists of the fallbacks - <xref linkend="noto-fonts"/>
312 will be used if you installed them. Cyrillic and Greek appear to be
313 treated in the same way. There are similar files with a 65- prefix for
314 Persian and other writing systems. All of these files prefer
315 commercial fonts if they are present, although modern libre fonts are
316 often at least equal. Finally, if a codepoint is still not found it can
317 be taken from any available system font. The following details only
318 mention freely available fonts.
319 </para>
320
321 <para>
322 Before fontconfig-2.14, the first preferred font family was Bitstream
323 Vera. In practice that was rarely used because it covered so little. After
324 that, DejaVu was the next preferred family, so people were recommended to
325 install that. That has now changed, Bitstream Vera has been replaced by the
326 relevant Noto fonts (Serif, Sans, Sans Mono), so these will be preferred if
327 they have been installed, followed by DejaVu.
328 </para>
329
330 <para>
331 For serif, Times New Roman could have been aliased from Liberation Serif or
332 Tinos, and Times from TeX Gyre Termes, so although the named fonts are not
333 free, the metric-compatilbe fonts can be used. Ignoring other non-free fonts,
334 the remaining order for serif is: Times New Roman, Luxi Serif, Nimbus Roman
335 No9 L, Times. In practice, that means those fonts at the end of the list
336 are unlikely to be used unless a web page asks for them.
337 </para>
338
339 <para>
340 For sans-serif, the remaining order is anything mapped to Arial, Luxi Sans,
341 Nimbus Sans L, anything mapped to Helvetica.
342 </para>
343
344 <para>
345 The remaining alternatives for monospace are Inconsolata, anything mapped
346 to Courier New, Luxi Mono, Nimbus Mono, anything mapped to Courier.
347 </para>
348
349 <para>
350 For 'fantasy' there are no free fonts, so fontconfig will fall back to
351 sans-serif.
352 </para>
353
354 <para>
355 For 'cursive', the only free font is TeX Gyre Chorus as an alias for
356 ITC Zapf chancery, otherwise fontconfig will again fall back to sans-serif.
357 </para>
358
359 <para>
360 The system-ui category is unusual. It is for interface messages, so some
361 scripts need special versions to fit in the available space. For Latin,
362 Greek and Cyrillic a normal sans font should fit without problems. However,
363 the first preferred font is Cantarell, followed by Noto Sans UI. Cantarell
364 started as a Latin sans-serif font, that has been forked in Gnome under
365 the same name but they only provide the source. The Noto Sans UI fonts are
366 for other languages.
367 </para>
368
369 <para>
370 Since fontconfig-2.12.5, there is also generic family matching for some
371 emoji and math fonts, please see {45,60}-generic.conf.
372 </para>
373
374 <para>
375 In the rare cases where a font does not contain all the expected
376 codepoints, see 'Trial the First:' at <xref
377 linkend="I-stared-into-the-fontconfig"/> for the long details.
378 </para>
379
380 </sect2>
381
382 <sect2 role="configuration" id="hinting-and-antialiasing" xreflabel="Hinting and Anti-aliasing">
383 <title>Hinting and Anti-aliasing</title>
384
385 <para>
386 It is possible to change how, or if, fonts are hinted. The following
387 example file contains the default settings, but with comments. The
388 settings are very much down to the user's preferences and to the choice
389 of fonts, so a change which improves some pages may worsen others. The
390 preferred location for this file is:
391 <filename>~/.config/fontconfig/fonts.conf</filename>
392 </para>
393
394 <para>
395 To try out different settings, you may need to exit from Xorg and then
396 run <command>startx</command> again so that all applications use the new
397 settings. If you use GNOME, KDE, or LXQt, their desktops can override
398 these changes. To explore the possibilities, create a file for your user:
399 </para>
400
401<screen><userinput>mkdir -pv ~/.config/fontconfig &amp;&amp;
402cat > ~/.config/fontconfig/fonts.conf &lt;&lt; "EOF"
403<literal>&lt;?xml version='1.0'?&gt;
404&lt;!DOCTYPE fontconfig SYSTEM 'fonts.dtd'&gt;
405&lt;fontconfig&gt;
406
407 &lt;match target="font" &gt;
408 &lt;!-- autohint was the old automatic hinter when hinting was patent
409 protected, so turn it off to ensure any hinting information in the font
410 itself is used, this is the default --&gt;
411 &lt;edit mode="assign" name="autohint"&gt; &lt;bool&gt;false&lt;/bool&gt;&lt;/edit&gt;
412
413 &lt;!-- hinting is enabled by default --&gt;
414 &lt;edit mode="assign" name="hinting"&gt; &lt;bool&gt;true&lt;/bool&gt;&lt;/edit&gt;
415
416 &lt;!-- for the lcdfilter see https://www.spasche.net/files/lcdfiltering/ --&gt;
417 &lt;edit mode="assign" name="lcdfilter"&gt; &lt;const&gt;lcddefault&lt;/const&gt;&lt;/edit&gt;
418
419 &lt;!-- options for hintstyle:
420 hintfull: is supposed to give a crisp font that aligns well to the
421 character-cell grid but at the cost of its proper shape.
422
423 hintmedium: poorly documented, maybe a synonym for hintfull.
424 hintslight is the default: - supposed to be more fuzzy but retains shape.
425
426 hintnone: seems to turn hinting off.
427 The variations are marginal and results vary with different fonts --&gt;
428 &lt;edit mode="assign" name="hintstyle"&gt; &lt;const&gt;hintslight&lt;/const&gt;&lt;/edit&gt;
429
430 &lt;!-- antialiasing is on by default and really helps for faint characters
431 and also for 'xft:' fonts used in rxvt-unicode --&gt;
432 &lt;edit mode="assign" name="antialias"&gt; &lt;bool&gt;true&lt;/bool&gt;&lt;/edit&gt;
433
434 &lt;!-- subpixels are usually rgb, see
435 http://www.lagom.nl/lcd-test/subpixel.php --&gt;
436 &lt;edit mode="assign" name="rgba"&gt; &lt;const&gt;rgb&lt;/const&gt;&lt;/edit&gt;
437
438 &lt;!-- thanks to the Arch wiki for the lcd and subpixel links --&gt;
439 &lt;/match&gt;
440
441&lt;/fontconfig&gt;</literal>
442EOF</userinput></screen>
443
444 <para>
445 You will now need to edit the file in your preferred editor.
446 </para>
447
448 <para>
449 For more examples see the blfs-support thread which started at <ulink
450 url="https://lists.linuxfromscratch.org/sympa/arc/blfs-support/2016-09/msg00128.html">2016-09/00128</ulink>,
451 particularly <ulink
452 url="https://lists.linuxfromscratch.org/sympa/arc/blfs-support/2016-09/msg00137.html">2016-09/00137</ulink>,
453 and the original poster's preferred solution at <ulink
454 url="https://lists.linuxfromscratch.org/sympa/arc/blfs-support/2016-09/msg00147.html">2016-09/00147</ulink>.
455 There are other examples in <xref linkend="arch-fontconfig"/> and <xref
456 linkend="gentoo-fontconfig"/>.
457 </para>
458
459 </sect2>
460
461 <sect2 role="configuration" id="disabling-bitmap-fonts" xreflabel="Disabling Bitmap fonts">
462 <title>Disabling Bitmap Fonts</title>
463
464 <para>
465 In previous versions of BLFS, the ugly old Xorg bitmap fonts were
466 installed. Now, many people will not need to install any of them. But if
467 for some reason you have installed one or more bitmap fonts, you can
468 prevent them from being used by <application>fontconfig</application> by
469 creating the following file as the &root; user :
470 </para>
471
472<screen role="root"><userinput>cat > /etc/fonts/conf.d/70-no-bitmaps.conf &lt;&lt; "EOF"
473<literal>&lt;?xml version='1.0'?&gt;
474&lt;!DOCTYPE fontconfig SYSTEM 'fonts.dtd'&gt;
475&lt;fontconfig&gt;
476&lt;!-- Reject bitmap fonts --&gt;
477 &lt;selectfont&gt;
478 &lt;rejectfont&gt;
479 &lt;pattern&gt;
480 &lt;patelt name="scalable"&gt;&lt;bool&gt;false&lt;/bool&gt;&lt;/patelt&gt;
481 &lt;/pattern&gt;
482 &lt;/rejectfont&gt;
483 &lt;/selectfont&gt;
484&lt;/fontconfig&gt;</literal>
485EOF</userinput></screen>
486
487 </sect2>
488
489 <sect2 role="configuration" id="adding-extra-directories" xreflabel="Adding extra font directories">
490 <title>Adding extra font directories</title>
491
492 <para>
493 Normally, system fonts and user fonts are installed in directories beneath
494 the locations specified in <xref linkend="xft-font-protocol"/> and there
495 is no obvious reason to put them elsewhere. However, a full BLFS install
496 of <xref linkend="texlive"/> puts many fonts in <filename
497 class="directory">/opt/texlive/&texlive-year;/texmf-dist/fonts/</filename>
498 in the <filename class="directory">opentype/</filename> and <filename
499 class="directory">truetype/</filename> subdirectories. Although pulling in
500 all of these files may appear useful (it allows you to use them in non
501 <application>TeX</application> programs), there are several problems with
502 such an approach:
503 </para>
504
505 <orderedlist>
506 <listitem>
507 <para>
508 There are hundreds of files, which makes selecting fonts difficult.
509 </para>
510 </listitem>
511 <listitem>
512 <para>
513 Some of the files do odd things, such as displaying semaphore flags
514 instead of ASCII letters, or mapping cyrillic codepoints to character
515 forms appropriate to Old Church Slavonic instead of the expected
516 current shapes: fine if that is what you need, but painful for normal
517 use.
518 </para>
519 </listitem>
520 <listitem>
521 <para>
522 Several fonts have multiple sizes and impenetrable short names, which
523 both make selecting the correct font even more difficult.
524 </para>
525 </listitem>
526 <listitem>
527 <para>
528 When a font is added to CTAN, it is accompanied by TeX packages to use
529 it in the old engines (<application>xelatex</application> does not
530 normally need this), and then the version is often frozen whilst the
531 font is separately maintained. Some of these fonts such as <xref
532 linkend="dejavu-fonts"/> are probably already installed on your BLFS
533 system in a newer version, and if you have multiple versions of a font
534 it is unclear which one will be used by
535 <application>fontconfig</application>.
536 </para>
537 </listitem>
538 </orderedlist>
539
540 <para>
541 However, it is sometimes useful to look at these fonts in non-TeX
542 applications, if only to see whether you wish to install a current
543 version. If you have installed all of <application>texlive</application>,
544 the following example will make one of the Arkandis Open Type fonts
545 available to other applications, and all three of the ParaType TrueType
546 fonts. Adjust or repeat the lines as desired, to either make all the
547 <filename class="directory">opentype/</filename> or <filename
548 class="directory">truetype</filename>fonts available, or to select
549 different font directories. As the <systemitem
550 class="username">root</systemitem> user:
551 </para>
552
553<screen role="root"><userinput>cat > /etc/fonts/conf.d/09-texlive.conf &lt;&lt; "EOF"
554<literal>&lt;?xml version='1.0'?&gt;
555&lt;!DOCTYPE fontconfig SYSTEM 'fonts.dtd'&gt;
556&lt;fontconfig&gt;
557 &lt;dir&gt;/opt/texlive/&texlive-year;/texmf-dist/fonts/opentype/arkandis/berenisadf&lt;/dir&gt;
558 &lt;dir&gt;/opt/texlive/&texlive-year;/texmf-dist/fonts/truetype/paratype&lt;/dir&gt;
559&lt;/fontconfig&gt;</literal>
560EOF</userinput></screen>
561
562 <para>
563 If you do this, remember to change all instances of the year in that file
564 when you upgrade <application>texlive</application> to a later release.
565 </para>
566
567 </sect2>
568
569 <sect2 role="configuration" id="preferring-certain-fonts" xreflabel="Preferring certain fonts">
570 <title>Preferring certain fonts</title>
571
572 <para>
573 With the exception of web pages which use WOFF fonts and either supply
574 them or link to google to download them, web pages have traditionally
575 suggested a list of preferred font family names if they cared (e.g.
576 Times New Roman, Serif). There are many reasons why people may wish to
577 have pages which specify a preferred font use a different font, or
578 prefer specific fonts in Monospace or Sans or Serif. As you will expect,
579 there a number of different ways of achieving this.
580 </para>
581
582 <bridgehead renderas="sect3" id="fontconfig-user-docs"
583 xreflabel="fontconfig-user-docs">Fontconfig user docs</bridgehead>
584
585 <para>
586 <application>Fontconfig</application> installs user documentation that
587 includes an example 'User configuration file' which among other things
588 prefers <xref linkend="wenquanyi-zenhei"/> (a Sans font) if a
589 <emphasis>Serif</emphasis> font is requested for Chinese (this part
590 might be anachronistic unless you have non-free Chinese fonts, because
591 in <filename>65-nonlatin.conf</filename> this font is already among the
592 preferred fonts when Serif is specified for Chinese) and to prefer the
593 modern <xref linkend="VLGothic"/> font if a Sans font is specified on a
594 Japanese page (otherwise a couple of other fonts would be preferred if
595 they have been installed).
596 </para>
597
598 <para>
599 If you have installed the current version, the user documentation is
600 available in HTML, PDF, and text versions at <filename
601 class="directory">/usr/share/doc/fontconfig-&fontconfig-version;/</filename>
602 : change the version if you installed a different one.
603 </para>
604
605 <bridgehead renderas="sect3" id="prefer-a-specific-font"
606 xreflabel="prefer-specific-font">Prefer a specific font</bridgehead>
607
608 <para>
609 As an example, if for some reason you wished to use the <ulink
610 url="https://www.fontsquirrel.com/fonts/nimbus-roman-no9-l">Nimbus Roman
611 No9 L</ulink> font wherever Times New Roman is referenced (it is
612 metrically similar, and preferred for Times Roman, but the Serif font
613 from <xref linkend="liberation-fonts"/> will be preferred for the Times
614 <emphasis>New</emphasis> Roman font if installed), as an individual user
615 you could install the font and then create the following file:
616 </para>
617
618<screen><userinput>mkdir -pv ~/.config/fontconfig/conf.d &amp;&amp;
619cat > ~/.config/fontconfig/conf.d/35-prefer-nimbus-for-timesnew.conf &lt;&lt; "EOF"
620<literal>&lt;?xml version='1.0'?&gt;
621&lt;!DOCTYPE fontconfig SYSTEM 'fonts.dtd'&gt;
622&lt;fontconfig&gt;
623&lt;!-- prefer Nimbus Roman No9 L for Times New Roman as well as for Times,
624 without this Tinos and Liberation Serif take precedence for Times New Roman
625 before fontconfig falls back to whatever matches Times --&gt;
626 &lt;alias binding="same"&gt;
627 &lt;family&gt;Times New Roman&lt;/family&gt;
628 &lt;accept&gt;
629 &lt;family&gt;Nimbus Roman No9 L&lt;/family&gt;
630 &lt;/accept&gt;
631 &lt;/alias&gt;
632&lt;/fontconfig&gt;</literal>
633EOF</userinput></screen>
634
635 <para>
636 This is something you would normally do in an individual user's
637 settings, but the file in this case has been prefixed '35-' so that it
638 could, if desired, be used system-wide in <filename
639 class="directory">/etc/fonts/conf.d/</filename>.
640 </para>
641
642 <bridgehead renderas="sect3" id="prefer-chosen-CJK-fonts"
643 xreflabel="Prefer chosen CJK fonts">Prefer chosen CJK fonts</bridgehead>
644
645 <para>
646 The following example of a local configuration (i.e. one that applies
647 for all users of the machine) does several things. It is particularly
648 appropriate where no language is specified, or for reading CJK text
649 in a non-CJK locale, and where the Japanese forms of the codepoints
650 shared with Chinese are preferred. In particular, alternative
651 approaches would be to specify a Chinese font ahead of the Japanese
652 font, meaning that only Kana symbols will be used from the Japanese
653 font, or to not specify DejaVu so that the first font in each set
654 of preferences is preferred for text using Latin alphabets.
655 </para>
656
657 <orderedlist>
658 <listitem>
659 <para>
660 If a Serif font is specified, it prefers <xref linkend="dejavu-fonts"/>.
661 If Han codepoints are found, or the Japanese language is specified,
662 the Mincho font from <xref linkend="IPAex"/> will be used. If Hangul
663 codepoints are found or the Korean language is specified, UnBatang
664 (see <xref linkend="Korean-fonts"/>) will be used: Change that line
665 If you installed a different Korean serif font. After that,
666 <xref linkend="wenquanyi-zenhei"/> (Sans, but a default for Serif
667 and monospace) is used. A previous version of this page mentioned
668 using UMing which is a traditional-style chinese font that ships
669 with an old conf file preferring it for zh-tw and zh-hk language
670 codes (and for sans-serif and monospace). But without the conf file,
671 fontconfig will only treat it as suitable for zh-hk.
672 The conf file needs to be edited to current style and will then be
673 prepended, so specifying UMing does not belong in this
674 <filename>local.conf</filename> file.
675 </para>
676 </listitem>
677 <listitem>
678 <para>
679 For Sans Serif preferences again start with <xref linkend="dejavu-fonts"/>,
680 then <xref linkend="VLGothic"/> for Japanese before falling back to
681 WenQuanYi Zen Hei which is Sans and covers both Chinese and Korean
682 Hangul.
683 </para>
684 </listitem>
685 <listitem>
686 <para>
687 The Monospace fonts are forced to the preferred Sans fonts. If the
688 text is in Chinese or Korean then <xref
689 linkend="wenquanyi-zenhei"/> will be used.
690 </para>
691 </listitem>
692 </orderedlist>
693
694 <para>
695 In a non-CJK locale, the result is that suitable fonts will be used for
696 all variants of Chinese, Japanese and Hangul Korean (but Japanese variants
697 of the glyphs shared with Chinese Han will be used). All other languages
698 should already work if a font is present. As the <systemitem
699 class="username">root</systemitem> user:
700 </para>
701
702<screen role="root"><userinput>cat > /etc/fonts/local.conf &lt;&lt; "EOF"
703<literal>&lt;?xml version='1.0'?&gt;
704&lt;!DOCTYPE fontconfig SYSTEM 'fonts.dtd'&gt;
705&lt;fontconfig&gt;
706 &lt;alias&gt;
707 &lt;family&gt;serif&lt;/family&gt;
708 &lt;prefer&gt;
709 &lt;family&gt;DejaVu Serif&lt;/family&gt;
710 &lt;family&gt;IPAexMincho&lt;/family&gt;
711 &lt;!-- WenQuanYi is preferred as Serif in 65-nonlatin.conf,
712 override that so a real Korean font can be used for Serif --&gt;
713 &lt;family&gt;UnBatang&lt;/family&gt;
714 &lt;/prefer&gt;
715 &lt;/alias&gt;
716 &lt;alias&gt;
717 &lt;family&gt;sans-serif&lt;/family&gt;
718 &lt;prefer&gt;
719 &lt;family&gt;DejaVu Sans&lt;/family&gt;
720 &lt;family&gt;VL Gothic&lt;/family&gt;
721 &lt;!-- This assumes WenQuanYi is good enough for Korean Sans --&gt;
722 &lt;/prefer&gt;
723 &lt;/alias&gt;
724 &lt;alias&gt;
725 &lt;family&gt;monospace&lt;/family&gt;
726 &lt;prefer&gt;
727 &lt;family&gt;DejaVu Sans Mono&lt;/family&gt;
728 &lt;family&gt;VL Gothic&lt;/family&gt;
729 &lt;!-- This assumes WenQuanYi is good enough for Korean Monospace --&gt;
730 &lt;/prefer&gt;
731 &lt;/alias&gt;
732&lt;/fontconfig&gt;</literal>
733EOF</userinput></screen>
734
735 </sect2>
736
737
738 <sect2 role="configuration" id="editing-old-style-conf-files"
739 xreflabel="Editing Old-Style conf files">
740 <title>Editing Old-Style conf files</title>
741
742 <para>
743 Some fonts, particularly Chinese fonts, ship with conf files which can be
744 installed in <filename class="directory">/etc/fonts/conf.d</filename>.
745 However, if you do that and then use a terminal to run any command which
746 uses <application>fontconfig</application> you may see error messages such
747 as :
748 </para>
749
750 <para>
751 <literal>Fontconfig warning: "/etc/fonts/conf.d/69-odofonts.conf", line
752 14: Having multiple &lt;family&gt; in &lt;alias&gt; isn't supported and
753 may not work as expected</literal>.
754 </para>
755
756 <para>
757 In practice, these old rules do not work. For non-CJK users,
758 <application>fontconfig</application> will usually do a good job
759 <emphasis>without</emphasis> these rules. Their origin dates back to when
760 CJK users needed handcrafted bitmaps to be legible at small sizes, and
761 those looked ugly next to antialiased Latin glyphs - they preferred to
762 use the same CJK font for the Latin glyphs. There is a side-effect of
763 doing this : the (Serif) font is often also used for Sans, and in such a
764 situation the (English) text in <application>Gtk</application> menus will
765 use this font - compared to system fonts, as well as being serif it is
766 both faint and rather small. That can make it uncomfortable to read.
767 </para>
768
769 <para>
770 Nevertheless, these old conf files can be fixed if you wish to use them.
771 The following example is the first part of
772 <filename>64-arphic-uming.conf</filename> from <xref linkend="UMing"/> -
773 there are many more similar items which also need changing :
774 </para>
775
776 <para>
777 <literallayout>
778 &lt;match target="pattern"&gt;
779 &lt;test qual="any" name="lang" compare="contains"&gt;
780 &lt;string&gt;zh-cn&lt;/string&gt;
781 &lt;string&gt;zh-sg&lt;/string&gt;
782 &lt;/test&gt;
783 &lt;test qual="any" name="family"&gt;
784 &lt;string&gt;serif&lt;/string&gt;
785 &lt;/test&gt;
786 &lt;edit name="family" mode="prepend" binding="strong"&gt;
787 &lt;string&gt;AR PL UMing CN&lt;/string&gt;
788 &lt;/edit&gt;
789 &lt;/match&gt;</literallayout>
790 </para>
791
792 <para>
793 The process to correct this is straightforward but tedious - for every
794 item which produces an error message, using your editor (as the &root;
795 user), edit the installed
796 file to repeat the whole block as many times as there are multiple
797 variables, then reduce each example to have only one of them. You may
798 wish to work on one error at a time, save the file after each fix, and
799 from a separate term run a command such as <command>fc-list 2>&amp;1 |
800 less</command> to see that the fix worked. For the block above, the fixed
801 version will be :
802 </para>
803
804 <para>
805 <literallayout>
806 &lt;match target="pattern"&gt;
807 &lt;test qual="any" name="lang" compare="contains"&gt;
808 &lt;string&gt;zh-cn&lt;/string&gt;
809 &lt;/test&gt;
810 &lt;test qual="any" name="family"&gt;
811 &lt;string&gt;serif&lt;/string&gt;
812 &lt;/test&gt;
813 &lt;edit name="family" mode="prepend" binding="strong"&gt;
814 &lt;string&gt;AR PL UMing CN&lt;/string&gt;
815 &lt;/edit&gt;
816 &lt;/match&gt;
817 &lt;match target="pattern"&gt;
818 &lt;test qual="any" name="lang" compare="contains"&gt;
819 &lt;string&gt;zh-sg&lt;/string&gt;
820 &lt;/test&gt;
821 &lt;test qual="any" name="family"&gt;
822 &lt;string&gt;serif&lt;/string&gt;
823 &lt;/test&gt;
824 &lt;edit name="family" mode="prepend" binding="strong"&gt;
825 &lt;string&gt;AR PL UMing CN&lt;/string&gt;
826 &lt;/edit&gt;
827 &lt;/match&gt;</literallayout>
828 </para>
829
830 </sect2>
831
832
833 <sect2 role="configuration" id="see-also" xreflabel="See Also">
834 <title>See Also</title>
835
836 <bridgehead renderas="sect3" id="I-stared-into-the-fontconfig"
837 xreflabel="I stared into the fontconfig">I stared into the fontconfig ...</bridgehead>
838
839 <para>
840 The blog entries by <ulink
841 url="https://eev.ee/blog/2015/05/20/i-stared-into-the-fontconfig-and-the-fontconfig-stared-back-at-me/">Eevee</ulink>
842 are particularly useful if <application>fontconfig</application> does not
843 think your chosen font supports your language, and for preferring some
844 non-MS Japanese fonts when an ugly MS font is already installed.
845 </para>
846
847 <bridgehead renderas="sect3" id="arch-fontconfig"
848 xreflabel="Fontconfig in the Arch wiki">Fontconfig in the Arch wiki</bridgehead>
849
850 <para>
851 Arch has a lot of information in its wiki at <ulink
852 url="https://wiki.archlinux.org/index.php/font_configuration">font_configuration</ulink>.
853 </para>
854
855 <bridgehead renderas="sect3" id="gentoo-fontconfig"
856 xreflabel="Fontconfig in the Gentoo wiki">Fontconfig in the Gentoo wiki</bridgehead>
857
858 <para>
859 Gentoo has some information in its wiki at <ulink
860 url="https://wiki.gentoo.org/wiki/Fontconfig">Fontconfig</ulink> although
861 a lot of the details (what to enable, and Infinality) are specific to
862 Gentoo.
863 </para>
864
865 </sect2>
866
867</sect1>
Note: See TracBrowser for help on using the repository browser.