Tuning Fontconfig

%general-entities; ]> Tuning Fontconfig Tuning Fontconfig Overview of Fontconfig If you only read text in English, and are happy with the common libre fonts listed on the next page, you may never need to worry about the details of how fontconfig works. But there are many things which can be altered if they do not suit your needs. Although this page is long, it barely scratches the surface and you will be able to find many alternative views on the web (but please remember that some things have changed over the years, for example the autohinter is no longer the default). The aim here is to give you enough information to understand the changes you are making. The Xft Font Protocol The Xft font protocol provides antialiased font rendering through freetype, and fonts are controlled from the client side using fontconfig (except for which can use fonts listed in ~/.Xresources, and which only uses the specified font). The default search path is /usr/share/fonts and ~/.local/share/fonts, although for the moment the old and deprecated location ~/.fonts still works. Fontconfig searches directories in its path recursively and maintains a cache of the font characteristics in each directory. If the cache appears to be out of date, it is ignored, and information is fetched from the fonts themselves (that can take a few seconds if you have a lot of fonts installed). If you've installed Xorg in any prefix other than /usr, any X fonts were not installed in a location known to Fontconfig. Symlinks were created from the OTF and TTF X font directories to /usr/share/fonts/X11-{OTF,TTF}. This allows Fontconfig to use the OpenType and TrueType fonts provided by X, although many people will prefer to use more modern fonts. Fontconfig uses names to define fonts. Applications generally use generic font names such as "Monospace", "Sans" and "Serif". Fontconfig resolves these names to a font that has all characters that cover the orthography of the language indicated by the locale settings. Useful Commands The following commands may be helpful when working with fontconfig: fc-list | less : shows a list of all available fonts (/path/to/filename: Font Name:style). If you installed a font more than 30 seconds ago but it does not show, then it or one of its directories is not readable by your user. fc-match 'Font Name' : tells you which font will be used if the named font is requested. Typically you would use this to see what happens if a font you have not installed is requested, but you can also use it if the system is giving you a different font from what you expected (perhaps because fontconfig does not think that the font supports your language). fc-match -a 'Type' | less : provides a list of all fonts which can be used for that type (Monospace, Sans, Serif). Note that in-extremis fontconfig will take a glyph from any available font, even if it is not of the specified type, and unless it knows about the font's type it will assume it is Sans. fc-match 'Serif :lang=ja:weight=bold' will tell you which font and weight will be chosen for Japanese text in bold weight. It does not mean that the reported font will necessarily be able to show Japanese ideograms, so a fallback might be used, or some glyphs may be missing. If you wish to know which font will be used for a string of text (i.e. one or more glyphs, preceded by a space), paste the following command and replace the xyz by the text you care about: FC_DEBUG=4 pango-view --font=monospace -t xyz | grep family : this requires and - it will invoke to show the text in a tiny window, and after closing that the last line of the output will show which font was chosen. This is particularly useful for CJK languages, and you can also pass a language, e.g. PANGO_LANGUAGE=en;ja (English, then assume Japanese) or just zh-cn (or other variants - 'zh' on its own is not valid). The various files The main files are in /etc/fonts/conf.d/, which was intended to be a directory populated by symlinks to some of the files in /usr/share/fontconfig/conf.avail/. But many people, and some packages, create the files directly. Each file name must be in the form of two digits, a dash, somename.conf and they are read in sequence. By convention, the numbers are assigned as follows: 00-09 extra font directories 10-19 system rendering defaults (such as antialiasing) 20-29 font rendering options 30-39 family substitution 40-49 map family to generic type 50-59 load alternate config files 60-69 generic aliases, map generic to family 70-79 adjust which fonts are available 80-89 match target scan (modify scanned patterns) 90-99 font synthesis You can also have a personal fonts.conf in $XDG_CONFIG_HOME (which is ~/.config/fontconfig/). The rules to choose a font If the requested font is installed, and provided it contains the codepoints required for the current language (in the source, see the .orth files in the fc-lang/ directory), it will be used. In fontconfig-2.14 the defaults were changed to Noto fonts. Some of the detail here is out of date and will be revised. However, if the document or page requested a font which is not installed (or, occasionally, does not contain all the required codepoints) the following rules come into play: First, 30-metric-aliases.conf is used to map aliases for some fonts with the same metrics (same size, etc). Note that there are both weak and strong aliases so that aliases for one form such as Helvetica or Times New Roman can be stisfied by the other style, i.e. anything which is an alias of Arial or Times in those examples. After that, an unknown font will be searched for in 45-latin.conf: 'Latin' covers Cyrillic and Greek, and now also maps system-ui fonts which are used for User Interface messages in other alphabets. If the font is found it will be mapped as serif, sans-serif, monospace, fantasy, cursive, or system-ui. Otherwise, 49-sansserif.conf will assume it is Sans. Then 60-latin.conf provides ordered lists of the fallbacks - will be used if you installed them. Cyrillic and Greek appear to be treated in the same way. There are similar files with a 65- prefix for Persian and other writing systems. All of these files prefer commercial fonts if they are present, although modern libre fonts are often at least equal. Finally, if a codepoint is still not found it can be taken from any available system font. The following details only mention freely available fonts. Before fontconfig-2.14, the first preferred font family was Bitstream Vera. In practice that was rarely used because it covered so little. After that, DejaVu was the next preferred family, so people were recommended to install that. That has now changed, Bitstream Vera has been replaced by the relevant Noto fonts (Serif, Sans, Sans Mono), so these will be preferred if they have been installed, followed by DejaVu. For serif, Times New Roman could have been aliased from Liberation Serif or Tinos, and Times from TeX Gyre Termes, so although the named fonts are not free, the metric-compatilbe fonts can be used. Ignoring other non-free fonts, the remaining order for serif is: Times New Roman, Luxi Serif, Nimbus Roman No9 L, Times. In practice, that means those fonts at the end of the list are unlikely to be used unless a web page asks for them. For sans-serif, the remaining order is anything mapped to Arial, Luxi Sans, Nimbus Sans L, anything mapped to Helvetica. The remaining alternatives for monospace are Inconsolata, anything mapped to Courier New, Luxi Mono, Nimbus Mono, anything mapped to Courier. For 'fantasy' there are no free fonts, so fontconfig will fall back to sans-serif. For 'cursive', the only free font is TeX Gyre Chorus as an alias for ITC Zapf chancery, otherwise fontconfig will again fall back to sans-serif. The system-ui category is unusual. It is for interface messages, so some scripts need special versions to fit in the available space. For Latin, Greek and Cyrillic a normal sans font should fit without problems. However, the first preferred font is Cantarell, followed by Noto Sans UI. Cantarell started as a Latin sans-serif font, that has been forked in Gnome under the same name but they only provide the source. The Noto Sans UI fonts are for other languages. Since fontconfig-2.12.5, there is also generic family matching for some emoji and math fonts, please see {45,60}-generic.conf. In the rare cases where a font does not contain all the expected codepoints, see 'Trial the First:' at for the long details. Hinting and Anti-aliasing It is possible to change how, or if, fonts are hinted. The following example file contains the default settings, but with comments. The settings are very much down to the user's preferences and to the choice of fonts, so a change which improves some pages may worsen others. The preferred location for this file is: ~/.config/fontconfig/fonts.conf To try out different settings, you may need to exit from Xorg and then run startx again so that all applications use the new settings. If you use GNOME, KDE, or LXQt, their desktops can override these changes. To explore the possibilities, create a file for your user: mkdir -pv ~/.config/fontconfig && cat > ~/.config/fontconfig/fonts.conf << "EOF" <?xml version='1.0'?> <!DOCTYPE fontconfig SYSTEM 'fonts.dtd'> <fontconfig> <match target="font" >  <edit mode="assign" name="autohint"> <bool>false</bool></edit>  <edit mode="assign" name="hinting"> <bool>true</bool></edit>  <edit mode="assign" name="lcdfilter"> <const>lcddefault</const></edit>  <edit mode="assign" name="hintstyle"> <const>hintslight</const></edit>  <edit mode="assign" name="antialias"> <bool>true</bool></edit>  <edit mode="assign" name="rgba"> <const>rgb</const></edit>  </match> </fontconfig> EOF You will now need to edit the file in your preferred editor. For more examples see the blfs-support thread which started at 2016-09/00128, particularly 2016-09/00137, and the original poster's preferred solution at 2016-09/00147. There are other examples in and . Disabling Bitmap Fonts In previous versions of BLFS, the ugly old Xorg bitmap fonts were installed. Now, many people will not need to install any of them. But if for some reason you have installed one or more bitmap fonts, you can prevent them from being used by fontconfig by creating the following file as the &root; user : cat > /etc/fonts/conf.d/70-no-bitmaps.conf << "EOF" <?xml version='1.0'?> <!DOCTYPE fontconfig SYSTEM 'fonts.dtd'> <fontconfig>  <selectfont> <rejectfont> <pattern> <patelt name="scalable"><bool>false</bool></patelt> </pattern> </rejectfont> </selectfont> </fontconfig> EOF Adding extra font directories Normally, system fonts and user fonts are installed in directories beneath the locations specified in and there is no obvious reason to put them elsewhere. However, a full BLFS install of puts many fonts in /opt/texlive/&texlive-year;/texmf-dist/fonts/ in the opentype/ and truetype/ subdirectories. Although pulling in all of these files may appear useful (it allows you to use them in non TeX programs), there are several problems with such an approach: There are hundreds of files, which makes selecting fonts difficult. Some of the files do odd things, such as displaying semaphore flags instead of ASCII letters, or mapping cyrillic codepoints to character forms appropriate to Old Church Slavonic instead of the expected current shapes: fine if that is what you need, but painful for normal use. Several fonts have multiple sizes and impenetrable short names, which both make selecting the correct font even more difficult. When a font is added to CTAN, it is accompanied by TeX packages to use it in the old engines (xelatex does not normally need this), and then the version is often frozen whilst the font is separately maintained. Some of these fonts such as are probably already installed on your BLFS system in a newer version, and if you have multiple versions of a font it is unclear which one will be used by fontconfig. However, it is sometimes useful to look at these fonts in non-TeX applications, if only to see whether you wish to install a current version. If you have installed all of texlive, the following example will make one of the Arkandis Open Type fonts available to other applications, and all three of the ParaType TrueType fonts. Adjust or repeat the lines as desired, to either make all the opentype/ or truetypefonts available, or to select different font directories. As the root user: cat > /etc/fonts/conf.d/09-texlive.conf << "EOF" <?xml version='1.0'?> <!DOCTYPE fontconfig SYSTEM 'fonts.dtd'> <fontconfig> <dir>/opt/texlive/&texlive-year;/texmf-dist/fonts/opentype/arkandis/berenisadf</dir> <dir>/opt/texlive/&texlive-year;/texmf-dist/fonts/truetype/paratype</dir> </fontconfig> EOF If you do this, remember to change all instances of the year in that file when you upgrade texlive to a later release. Preferring certain fonts With the exception of web pages which use WOFF fonts and either supply them or link to google to download them, web pages have traditionally suggested a list of preferred font family names if they cared (e.g. Times New Roman, Serif). There are many reasons why people may wish to have pages which specify a preferred font use a different font, or prefer specific fonts in Monospace or Sans or Serif. As you will expect, there a number of different ways of achieving this. Fontconfig user docs Fontconfig installs user documentation that includes an example 'User configuration file' which among other things prefers (a Sans font) if a Serif font is requested for Chinese (this part might be anachronistic unless you have non-free Chinese fonts, because in 65-nonlatin.conf this font is already among the preferred fonts when Serif is specified for Chinese) and to prefer the modern font if a Sans font is specified on a Japanese page (otherwise a couple of other fonts would be preferred if they have been installed). If you have installed the current version, the user documentation is available in HTML, PDF, and text versions at /usr/share/doc/fontconfig-&fontconfig-version;/ : change the version if you installed a different one. Prefer a specific font As an example, if for some reason you wished to use the Nimbus Roman No9 L font wherever Times New Roman is referenced (it is metrically similar, and preferred for Times Roman, but the Serif font from will be preferred for the Times New Roman font if installed), as an individual user you could install the font and then create the following file: mkdir -pv ~/.config/fontconfig/conf.d && cat > ~/.config/fontconfig/conf.d/35-prefer-nimbus-for-timesnew.conf << "EOF" <?xml version='1.0'?> <!DOCTYPE fontconfig SYSTEM 'fonts.dtd'> <fontconfig>  <alias binding="same"> <family>Times New Roman</family> <accept> <family>Nimbus Roman No9 L</family> </accept> </alias> </fontconfig> EOF This is something you would normally do in an individual user's settings, but the file in this case has been prefixed '35-' so that it could, if desired, be used system-wide in /etc/fonts/conf.d/. Prefer chosen CJK fonts The following example of a local configuration (i.e. one that applies for all users of the machine) does several things. It is particularly appropriate where no language is specified, or for reading CJK text in a non-CJK locale, and where the Japanese forms of the codepoints shared with Chinese are preferred. In particular, alternative approaches would be to specify a Chinese font ahead of the Japanese font, meaning that only Kana symbols will be used from the Japanese font, or to not specify DejaVu so that the first font in each set of preferences is preferred for text using Latin alphabets. If a Serif font is specified, it prefers . If Han codepoints are found, or the Japanese language is specified, the Mincho font from will be used. If Hangul codepoints are found or the Korean language is specified, UnBatang (see ) will be used: Change that line If you installed a different Korean serif font. After that, (Sans, but a default for Serif and monospace) is used. A previous version of this page mentioned using UMing which is a traditional-style chinese font that ships with an old conf file preferring it for zh-tw and zh-hk language codes (and for sans-serif and monospace). But without the conf file, fontconfig will only treat it as suitable for zh-hk. The conf file needs to be edited to current style and will then be prepended, so specifying UMing does not belong in this local.conf file. For Sans Serif preferences again start with , then for Japanese before falling back to WenQuanYi Zen Hei which is Sans and covers both Chinese and Korean Hangul. The Monospace fonts are forced to the preferred Sans fonts. If the text is in Chinese or Korean then will be used. In a non-CJK locale, the result is that suitable fonts will be used for all variants of Chinese, Japanese and Hangul Korean (but Japanese variants of the glyphs shared with Chinese Han will be used). All other languages should already work if a font is present. As the root user: cat > /etc/fonts/local.conf << "EOF" <?xml version='1.0'?> <!DOCTYPE fontconfig SYSTEM 'fonts.dtd'> <fontconfig> <alias> <family>serif</family> <prefer> <family>DejaVu Serif</family> <family>IPAexMincho</family>  <family>UnBatang</family> </prefer> </alias> <alias> <family>sans-serif</family> <prefer> <family>DejaVu Sans</family> <family>VL Gothic</family>  </prefer> </alias> <alias> <family>monospace</family> <prefer> <family>DejaVu Sans Mono</family> <family>VL Gothic</family>  </prefer> </alias> </fontconfig> EOF Editing Old-Style conf files Some fonts, particularly Chinese fonts, ship with conf files which can be installed in /etc/fonts/conf.d. However, if you do that and then use a terminal to run any command which uses fontconfig you may see error messages such as : Fontconfig warning: "/etc/fonts/conf.d/69-odofonts.conf", line 14: Having multiple <family> in <alias> isn't supported and may not work as expected. In practice, these old rules do not work. For non-CJK users, fontconfig will usually do a good job without these rules. Their origin dates back to when CJK users needed handcrafted bitmaps to be legible at small sizes, and those looked ugly next to antialiased Latin glyphs - they preferred to use the same CJK font for the Latin glyphs. There is a side-effect of doing this : the (Serif) font is often also used for Sans, and in such a situation the (English) text in Gtk menus will use this font - compared to system fonts, as well as being serif it is both faint and rather small. That can make it uncomfortable to read. Nevertheless, these old conf files can be fixed if you wish to use them. The following example is the first part of 64-arphic-uming.conf from - there are many more similar items which also need changing : <match target="pattern"> <test qual="any" name="lang" compare="contains"> <string>zh-cn</string> <string>zh-sg</string> </test> <test qual="any" name="family"> <string>serif</string> </test> <edit name="family" mode="prepend" binding="strong"> <string>AR PL UMing CN</string> </edit> </match> The process to correct this is straightforward but tedious - for every item which produces an error message, using your editor (as the &root; user), edit the installed file to repeat the whole block as many times as there are multiple variables, then reduce each example to have only one of them. You may wish to work on one error at a time, save the file after each fix, and from a separate term run a command such as fc-list 2>&1 | less to see that the fix worked. For the block above, the fixed version will be : <match target="pattern"> <test qual="any" name="lang" compare="contains"> <string>zh-cn</string> </test> <test qual="any" name="family"> <string>serif</string> </test> <edit name="family" mode="prepend" binding="strong"> <string>AR PL UMing CN</string> </edit> </match> <match target="pattern"> <test qual="any" name="lang" compare="contains"> <string>zh-sg</string> </test> <test qual="any" name="family"> <string>serif</string> </test> <edit name="family" mode="prepend" binding="strong"> <string>AR PL UMing CN</string> </edit> </match> See Also I stared into the fontconfig ... The blog entries by Eevee are particularly useful if fontconfig does not think your chosen font supports your language, and for preferring some non-MS Japanese fonts when an ugly MS font is already installed. Fontconfig in the Arch wiki Arch has a lot of information in its wiki at font_configuration. Fontconfig in the Gentoo wiki Gentoo has some information in its wiki at Fontconfig although a lot of the details (what to enable, and Infinality) are specific to Gentoo.