source: x/installing/tuning-fontconfig.xml@ abbf9a3

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;
]>

<sect1 id="tuning-fontconfig">
  <?dbhtml filename="tuning-fontconfig.html"?>


  <title>Tuning Fontconfig</title>

  <indexterm zone="tuning-fontconfig">
    <primary sortas="g-tuning-fontconfig">Tuning Fontconfig</primary>
  </indexterm>

    <sect2 id='fontconfig-overview' xreflabel="Overview of Fontconfig">
    <title>Overview of Fontconfig</title>

<!-- do not add individual indexterm entries for items within this page, they
 all belong in section G (others) and not only do they add noise in longindex,
 the links all point to the top of the page. -->

    <para>
      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 <application>fontconfig</application> works. But there are
      many things which can be altered if they do not suit your needs.
    </para>

    <para>
      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, why they may not always work,
      and to identify online information which is no-longer appropriate.
    </para>

    <para>
      Unfortunately, some of the terminology is ambiguous (e.g. 'font face' can
      mean a name known to fontconfig, <emphasis>or</emphasis> the normal, italic
      condensed, etc variations of a font).
    </para>

    <para>The following links are to assist navigation in this page.</para>
    <itemizedlist>
      <listitem>
        <para><xref linkend="xft-font-protocol"/></para>
      </listitem>
      <listitem>
        <para><xref linkend="useful-commands"/></para>
      </listitem>
      <listitem>
        <para><xref linkend="the-various-files"/></para>
      </listitem>
      <listitem>
        <para><xref linkend="rules-to-choose-a-font"/></para>
      </listitem>
      <listitem>
        <para><xref linkend="hinting-and-antialiasing"/></para>
      </listitem>
      <listitem>
        <para><xref linkend="disabling-bitmap-fonts"/></para>
      </listitem>
      <listitem>
        <para><xref linkend="adding-extra-directories"/></para>
      </listitem>
      <listitem>
        <para><xref linkend="preferring-certain-fonts"/></para>
      </listitem>
      <listitem>
        <para><xref linkend="fontconfig-user-docs"/></para>
      </listitem>
      <listitem>
        <para><xref linkend="prefer-a-specific-font"/></para>
      </listitem>
      <listitem>
        <para><xref linkend="prefer-chosen-CJK-fonts"/></para>
      </listitem>
      <listitem>
        <para><xref linkend="editing-old-style-conf-files"/></para>
      </listitem>
      <listitem>
        <para><xref linkend="items-which-can-override-fontconfig"/></para>
      </listitem>
      <listitem>
        <para><xref linkend="see-also"/></para>
      </listitem>
    </itemizedlist>

    </sect2>

    <sect2 role="configuration" id="xft-font-protocol" xreflabel="The Xft Font Protocol">
    <title>The Xft Font Protocol</title>

    <para>
      The Xft font protocol provides antialiased font rendering through
      <application>freetype</application>, and fonts are controlled from the
      client side using <application>fontconfig</application> (except for
      <xref linkend="rxvt-unicode"/> which can use fonts listed in
      <filename>~/.Xresources</filename>, and <xref linkend="abiword"/> which
      only uses the specified font). The default search path is <filename
      class="directory">/usr/share/fonts</filename> and <filename
      class="directory">~/.local/share/fonts</filename>, although for the moment
      the old and deprecated location <filename
      class="directory">~/.fonts</filename> still works.
      <application>Fontconfig</application> 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).
    </para>

    <para>
      If you've installed <application>Xorg</application> in any prefix
      other than <filename class="directory">/usr</filename>, any
      <application>X</application> fonts were not installed in a
      location known to <application>Fontconfig</application>. Symlinks were
       <!-- fonts-misc-ethiopic installs an OTF directory ! -->
      created from the <filename class="directory">OTF</filename> and <filename
      class="directory">TTF</filename> <application>X</application> font
      directories to <filename
      class="directory">/usr/share/fonts/X11-{OTF,TTF}</filename>. This allows
      <application>Fontconfig</application> to use the OpenType and TrueType
      fonts provided by <application>X</application>, although many people will
      prefer to use more modern fonts.
    </para>

    <para>
      <application>Fontconfig</application> uses names to define fonts.
      Applications generally use generic font names such as "Monospace", "Sans"
      and "Serif". <application>Fontconfig</application> resolves these names
      to a font that has all characters that cover the orthography of the
      language indicated by the locale settings.
    </para>

    </sect2>

    <sect2 role="configuration" id="useful-commands" xreflabel="Useful Commands">
    <title>Useful Commands</title>

    <para>
      The following commands may be helpful when working with fontconfig,
      particularly if you are interested in overriding which font will be
      chosen. 'TYPE' should be one of serif, sans-serif or monospace.
    </para>

    <para>
      <command>fc-list | less</command> : 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.
    </para>

    <para>
      <command>fc-match 'Font Name'</command> : 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 <application>fontconfig</application>
      does not think that the font supports your language).
    </para>

    <para>
      <command>fc-match -a <replaceable>Type</replaceable> | less</command> :
      provides a list of all fonts which can be used for that type (Monospace,
      Sans Sasn-serif, Serif <emphasis>(capital letters optional)</emphasis>).
      Note that in-extremis <application>fontconfig</application> 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.
    </para>

    <para>
      <command>fc-match 'Serif :lang=ja:weight=bold'</command> 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. For language codes use  ISO-639 value such as 'fr', 'ja', 'zh-cn'.
      Note that an unrecognized value such as just 'zh' will not return any
      match. To illustrate the fallback, on a system wherei both Noto Sans Mono
      and DejaVu Sans Mono are installed, <command>fc-match 'monospace
      :lang=en</command> shows Noto Sans Mono will be used, but if the lang is
      changed to 'ar' (arabic) DejaVu Sans will be used.
    </para>

    <para>
      If you want to determine if a font file has hinting (many older fonts do not,
      because it was patented) use <command>fc-query
      <replaceable>/path/to/fontfile</replaceable> | grep 'fonthashint:'</command>:
      which will report 'True(s)' or 'False(s)'.
    </para>

    <para>
      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 <literal>xyz</literal> by the text you care
      about:
    </para>

    <para>
      <command>FC_DEBUG=4 pango-view --font=monospace -t xyz | grep
      family</command> : this requires <xref linkend="pango"/> and <xref
      linkend="imagemagick"/> - it will invoke <xref linkend="display"/>
      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 such as zh-sg or zh-tw).
    </para>

    </sect2>

    <sect2 role="configuration" id="the-various-files" xreflabel="The configuration files">
    <title>The configuation files</title>

    <para>
      The main files are in <filename class="directory">/etc/fonts/conf.d/</filename>,
      which was intended to be a directory populated by symlinks to some of the files
      in <filename class="directory">/usr/share/fontconfig/conf.avail/</filename>.
      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.
    </para>

    <para>
      By convention, the numbers are assigned as follows:
    </para>

    <itemizedlist>
      <listitem>
        <para>
          00-09 extra font directories
        </para>
      </listitem>
      <listitem>
        <para>
          10-19 system rendering defaults (such as antialiasing)
        </para>
      </listitem>
      <listitem>
        <para>
          20-29 font rendering options
        </para>
      </listitem>
      <listitem>
        <para>
          30-39 family substitution
        </para>
      </listitem>
      <listitem>
        <para>
          40-49 map family to generic type
        </para>
      </listitem>
      <listitem>
        <para>
          50-59 load alternate config files
        </para>
      </listitem>
      <listitem>
        <para>
          60-69 generic aliases, map generic to family
        </para>
      </listitem>
      <listitem>
        <para>
          70-79 adjust which fonts are available
        </para>
      </listitem>
      <listitem>
        <para>
          80-89 match target scan (modify scanned patterns)
        </para>
      </listitem>
      <listitem>
        <para>
          90-99 font synthesis
        </para>
      </listitem>
    </itemizedlist>

    <para>
      You can also have a personal <filename>fonts.conf</filename> in
      $XDG_CONFIG_HOME (which is <filename
      class="directory">~/.config/fontconfig/</filename>).
    </para>

  </sect2>

  <sect2 role="configuration" id="rules-to-choose-a-font" xreflabel="The rules to choose a font">
  <title>The rules to choose a font</title>

    <para>
      If the requested font is installed, and provided it contains the
      codepoints <emphasis>required</emphasis> for the current language (in the
      source, see the .orth files in the <filename
    class="directory">fc-lang/</filename> directory), it will be used.
    </para>

    <note>
      <para>
        In fontconfig-2.14 the defaults were changed to Noto fonts. Some of the
        detail here is out of date and will be revised.
      </para>
    </note>

    <para>
      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,
      <filename>30-metric-aliases.conf</filename> 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
      <filename>45-latin.conf</filename>:
      '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.
    </para>
    <para>
      Then <filename>60-latin.conf</filename>
      provides ordered lists of the fallbacks - <xref linkend="noto-fonts"/>
      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.
    </para>

    <para>
      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.
    </para>

    <para>
      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.
    </para>

    <para>
      For sans-serif, the remaining order is anything mapped to Arial, Luxi Sans,
      Nimbus Sans L, anything mapped to Helvetica.
    </para>

    <para>
      The remaining alternatives for monospace are Inconsolata, anything mapped
      to Courier New, Luxi Mono, Nimbus Mono, anything mapped to Courier.
    </para>

    <para>
      For 'fantasy' there are no free fonts, so fontconfig will fall back to
      sans-serif.
    </para>

    <para>
      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.
    </para>

    <para>
      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.
    </para>

    <para>
      Since fontconfig-2.12.5, there is also generic family matching for some
      emoji and math fonts, please see {45,60}-generic.conf.
    </para>

    <para>
      In the rare cases where a font does not contain all the expected
      codepoints, see 'Trial the First:' at <xref
      linkend="I-stared-into-the-fontconfig"/> for the long details.
    </para>

  </sect2>

  <sect2 role="configuration" id="hinting-and-antialiasing" xreflabel="Hinting and Anti-aliasing">
  <title>Hinting and Anti-aliasing</title>

    <para>
      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:
     <filename>~/.config/fontconfig/fonts.conf</filename>
    </para>

    <para>
      To try out different settings, you may need to exit from Xorg and then
      run <command>startx</command> again so that all applications use the new
      settings. Several things can override the fontconfig settings, see
      <xref linkend="items-which-can-override-fontconfig"/> below. To explore
      the possibilities, create a file for your user:
    </para>

<screen><userinput>mkdir -pv ~/.config/fontconfig &amp;&amp;
cat > ~/.config/fontconfig/fonts.conf &lt;&lt; "EOF"
<literal>&lt;?xml version='1.0'?&gt;
&lt;!DOCTYPE fontconfig SYSTEM 'fonts.dtd'&gt;
&lt;fontconfig&gt;

  &lt;match target="font" &gt;
    &lt;!-- autohint was the old automatic hinter when hinting was patent
    protected, so turn it off to ensure any hinting information in the font
    itself is used, this is the default --&gt;
    &lt;edit mode="assign" name="autohint"&gt;  &lt;bool&gt;false&lt;/bool&gt;&lt;/edit&gt;

    &lt;!-- hinting is enabled by default --&gt;
    &lt;edit mode="assign" name="hinting"&gt;   &lt;bool&gt;true&lt;/bool&gt;&lt;/edit&gt;

    &lt;!-- for the lcdfilter see https://www.spasche.net/files/lcdfiltering/ --&gt;
    &lt;edit mode="assign" name="lcdfilter"&gt; &lt;const&gt;lcddefault&lt;/const&gt;&lt;/edit&gt;

    &lt;!-- options for hintstyle:
    hintfull: is supposed to give a crisp font that aligns well to the
    character-cell grid but at the cost of its proper shape. However, anything
    using Pango >= 1.44 will not support full hinting, Pango now uses harfbuzz
    for hinting. Apps which use Skia (e.g. Chromium, Firefox) should not be
    affected by this. <!-- https://github.com/harfbuzz/harfbuzz/issues/2394 -->

    hintmedium: is reported to be broken.
    hintslight is the default: - supposed to be more fuzzy but retains shape.

    hintnone: seems to turn hinting off.
    The variations are marginal and results vary with different fonts --&gt;
    &lt;edit mode="assign" name="hintstyle"&gt; &lt;const&gt;hintslight&lt;/const&gt;&lt;/edit&gt;

    &lt;!-- antialiasing is on by default and really helps for faint characters
    and also for 'xft:' fonts used in rxvt-unicode --&gt;
    &lt;edit mode="assign" name="antialias"&gt; &lt;bool&gt;true&lt;/bool&gt;&lt;/edit&gt;

    &lt;!-- subpixels are usually rgb, see
    http://www.lagom.nl/lcd-test/subpixel.php --&gt;
    &lt;edit mode="assign" name="rgba"&gt;      &lt;const&gt;rgb&lt;/const&gt;&lt;/edit&gt;

    &lt;!-- thanks to the Arch wiki for the lcd and subpixel links --&gt;
  &lt;/match&gt;

&lt;/fontconfig&gt;</literal>
EOF</userinput></screen>

    <para>
      You will now need to edit the file in your preferred editor. Many of the
      different settings give very subtle differences and the results may differ
      for some of the fonts you use.
    </para>

    <note>
      <para>
        Hinting, if enabled, is done in <application>FreeType</application>.
        Since FreeType-2.7 the default TrueType interpreter is v40. The
        original v35 hinter could be enabled by an environment variable, but
        is only really appropriate to original Microsoft TTF fonts (Arial, etc).
        The v38 hinter (Infinality) is not built by default and all the options
        to tune it have been removed. For full details see <xref
        linkend="subpixel-hinting"/> (Spoiler: there is NO sub-pixel hinting,
        the code simply ignores <emphasis>all</emphasis> horizontal hinting
        instructions.
      </para>

      <para>
        Xorg assumes screens have 96 dots per inch (DPI). Most LCD screens are
        close to this, but some people detect colour fringing if their screen
        diverges from that size. See <xref linkend="calc-dpi"/>.
      </para>

      <para>
        If you have a High DPI screen (often described as '4K' or larger) you
        will probably use larger font sizes and benefit from disabling hinting.
      </para>
    </note>

    <para>
      For more examples see the blfs-support thread which started at <ulink
      url="https://lists.linuxfromscratch.org/sympa/arc/blfs-support/2016-09/msg00128.html">2016-09/00128</ulink>,
      particularly <ulink
      url="https://lists.linuxfromscratch.org/sympa/arc/blfs-support/2016-09/msg00137.html">2016-09/00137</ulink>,
      and the original poster's preferred solution at <ulink
      url="https://lists.linuxfromscratch.org/sympa/arc/blfs-support/2016-09/msg00147.html">2016-09/00147</ulink>.
      There are other examples in <xref linkend="arch-fontconfig"/> and <xref
      linkend="gentoo-fontconfig"/>.
    </para>

  </sect2>

  <sect2 role="configuration" id="disabling-bitmap-fonts" xreflabel="Disabling Bitmap fonts">
  <title>Disabling Bitmap Fonts</title>

    <para>
      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 <application>fontconfig</application> by
      creating the following file as the &root; user :
    </para>

<screen role="root"><userinput>cat > /etc/fonts/conf.d/70-no-bitmaps.conf &lt;&lt; "EOF"
<literal>&lt;?xml version='1.0'?&gt;
&lt;!DOCTYPE fontconfig SYSTEM 'fonts.dtd'&gt;
&lt;fontconfig&gt;
&lt;!-- Reject bitmap fonts --&gt;
 &lt;selectfont&gt;
  &lt;rejectfont&gt;
   &lt;pattern&gt;
     &lt;patelt name="scalable"&gt;&lt;bool&gt;false&lt;/bool&gt;&lt;/patelt&gt;
   &lt;/pattern&gt;
  &lt;/rejectfont&gt;
 &lt;/selectfont&gt;
&lt;/fontconfig&gt;</literal>
EOF</userinput></screen>

  </sect2>

  <sect2 role="configuration" id="adding-extra-directories" xreflabel="Adding extra font directories">
  <title>Adding extra font directories</title>

    <para>
      Normally, system fonts and user fonts are installed in directories beneath
      the locations specified in <xref linkend="xft-font-protocol"/> and there
      is no obvious reason to put them elsewhere. However, a full BLFS install
      of <xref linkend="texlive"/> puts many fonts in <filename
      class="directory">/opt/texlive/&texlive-year;/texmf-dist/fonts/</filename>
      in the <filename class="directory">opentype/</filename> and <filename
      class="directory">truetype/</filename> subdirectories. Although pulling in
      all of these files may appear useful (it allows you to use them in non
      <application>TeX</application> programs), there are several problems with
      such an approach:
    </para>

    <orderedlist>
      <listitem>
        <para>
          There are hundreds of files, which makes selecting fonts difficult.
        </para>
      </listitem>
      <listitem>
        <para>
          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.
        </para>
      </listitem>
      <listitem>
        <para>
          Several fonts have multiple sizes and impenetrable short names, which
          both make selecting the correct font even more difficult.
        </para>
      </listitem>
      <listitem>
        <para>
          When a font is added to CTAN, it is accompanied by TeX packages to use
          it in the old engines (<application>xelatex</application> does not
          normally need this), and then the version is often frozen whilst the
          font is separately maintained. Some of these fonts such as <xref
          linkend="dejavu-fonts"/> 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
          <application>fontconfig</application>.
        </para>
      </listitem>
    </orderedlist>

    <para>
      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 <application>texlive</application>,
      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
      <filename class="directory">opentype/</filename> or <filename
      class="directory">truetype</filename>fonts available, or to select
      different font directories. As the <systemitem
      class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>cat > /etc/fonts/conf.d/09-texlive.conf &lt;&lt; "EOF"
<literal>&lt;?xml version='1.0'?&gt;
&lt;!DOCTYPE fontconfig SYSTEM 'fonts.dtd'&gt;
&lt;fontconfig&gt;
  &lt;dir&gt;/opt/texlive/&texlive-year;/texmf-dist/fonts/opentype/arkandis/berenisadf&lt;/dir&gt;
  &lt;dir&gt;/opt/texlive/&texlive-year;/texmf-dist/fonts/truetype/paratype&lt;/dir&gt;
&lt;/fontconfig&gt;</literal>
EOF</userinput></screen>

    <para>
      If you do this, remember to change all instances of the year in that file
      when you upgrade <application>texlive</application> to a later release.
    </para>

  </sect2>

  <sect2 role="configuration" id="preferring-certain-fonts" xreflabel="Preferring certain fonts">
  <title>Preferring certain fonts</title>

    <para>
      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.
    </para>

    <bridgehead renderas="sect3" id="fontconfig-user-docs"
    xreflabel="Fontconfig user documentation">Fontconfig user documentation</bridgehead>

      <para>
        <application>Fontconfig</application> installs user documentation that
        includes an example 'User configuration file' which among other things
        prefers <xref linkend="wenquanyi-zenhei"/> (a Sans font) if a
        <emphasis>Serif</emphasis> font is requested for Chinese (this part
        might be anachronistic unless you have non-free Chinese fonts, because
        in <filename>65-nonlatin.conf</filename> this font is already among the
        preferred fonts when Serif is specified for Chinese) and to prefer the
        modern <xref linkend="VLGothic"/> 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).
      </para>

      <para>
        If you have installed the current version, the user documentation is
        available in HTML, PDF, and text versions at <filename
        class="directory">/usr/share/doc/fontconfig-&fontconfig-version;/</filename>
        : change the version if you installed a different one.
      </para>

    <bridgehead renderas="sect3" id="prefer-a-specific-font"
    xreflabel="Prefer a specific font">Prefer a specific font</bridgehead>

      <para>
        As an example, if for some reason you wished to use the <ulink
        url="https://www.fontsquirrel.com/fonts/nimbus-roman-no9-l">Nimbus Roman
        No9 L</ulink> font wherever Times New Roman is referenced (it is
        metrically similar, and preferred for Times Roman, but the Serif font
        from <xref linkend="liberation-fonts"/> will be preferred for the Times
        <emphasis>New</emphasis> Roman font if installed), as an individual user
        you could install the font and then create the following file:
      </para>

<screen><userinput>mkdir -pv ~/.config/fontconfig/conf.d &amp;&amp;
cat >  ~/.config/fontconfig/conf.d/35-prefer-nimbus-for-timesnew.conf &lt;&lt; "EOF"
<literal>&lt;?xml version='1.0'?&gt;
&lt;!DOCTYPE fontconfig SYSTEM 'fonts.dtd'&gt;
&lt;fontconfig&gt;
&lt;!-- prefer Nimbus Roman No9 L for Times New Roman as well as for Times,
 without this Tinos and Liberation Serif take precedence for Times New Roman
 before fontconfig falls back to whatever matches Times --&gt;
    &lt;alias binding="same"&gt;
        &lt;family&gt;Times New Roman&lt;/family&gt;
        &lt;accept&gt;
            &lt;family&gt;Nimbus Roman No9 L&lt;/family&gt;
        &lt;/accept&gt;
    &lt;/alias&gt;
&lt;/fontconfig&gt;</literal>
EOF</userinput></screen>

      <para>
        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 <filename
        class="directory">/etc/fonts/conf.d/</filename>.
      </para>

    <bridgehead renderas="sect3" id="prefer-chosen-CJK-fonts"
    xreflabel="Prefer chosen CJK fonts">Prefer chosen CJK fonts</bridgehead>

      <para>
        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.
      </para>

      <orderedlist>
        <listitem>
          <para>
            If a Serif font is specified, it prefers <xref linkend="dejavu-fonts"/>.
            If Han codepoints are found, or the Japanese language is specified,
            the Mincho font from <xref linkend="IPAex"/> will be used. If Hangul
            codepoints are found or the Korean language is specified, UnBatang
            (see <xref linkend="Korean-fonts"/>) will be used: Change that line
            If you installed a different Korean serif font. After that,
            <xref linkend="wenquanyi-zenhei"/>  (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
            <filename>local.conf</filename> file.
          </para>
        </listitem>
        <listitem>
          <para>
            For Sans Serif preferences again start with <xref linkend="dejavu-fonts"/>,
            then <xref linkend="VLGothic"/> for Japanese before falling back to
            WenQuanYi Zen Hei which is Sans and covers both Chinese and Korean
            Hangul.
          </para>
        </listitem>
        <listitem>
          <para>
            The Monospace fonts are forced to the preferred Sans fonts. If the
            text is in Chinese or Korean then <xref
            linkend="wenquanyi-zenhei"/> will be used.
          </para>
        </listitem>
      </orderedlist>

      <para>
        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 <systemitem
        class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>cat > /etc/fonts/local.conf &lt;&lt; "EOF"
<literal>&lt;?xml version='1.0'?&gt;
&lt;!DOCTYPE fontconfig SYSTEM 'fonts.dtd'&gt;
&lt;fontconfig&gt;
    &lt;alias&gt;
        &lt;family&gt;serif&lt;/family&gt;
        &lt;prefer&gt;
            &lt;family&gt;DejaVu Serif&lt;/family&gt;
            &lt;family&gt;IPAexMincho&lt;/family&gt;
            &lt;!-- WenQuanYi is preferred as Serif in 65-nonlatin.conf,
            override that so a real Korean font can be used for Serif --&gt;
            &lt;family&gt;UnBatang&lt;/family&gt;
        &lt;/prefer&gt;
    &lt;/alias&gt;
    &lt;alias&gt;
         &lt;family&gt;sans-serif&lt;/family&gt;
         &lt;prefer&gt;
             &lt;family&gt;DejaVu Sans&lt;/family&gt;
             &lt;family&gt;VL Gothic&lt;/family&gt;
         &lt;!-- This assumes WenQuanYi is good enough for Korean Sans --&gt;
         &lt;/prefer&gt;
    &lt;/alias&gt;
    &lt;alias&gt;
         &lt;family&gt;monospace&lt;/family&gt;
         &lt;prefer&gt;
             &lt;family&gt;DejaVu Sans Mono&lt;/family&gt;
             &lt;family&gt;VL Gothic&lt;/family&gt;
         &lt;!-- This assumes WenQuanYi is good enough for Korean Monospace --&gt;
         &lt;/prefer&gt;
    &lt;/alias&gt;
&lt;/fontconfig&gt;</literal>
EOF</userinput></screen>

  </sect2>


  <sect2 role="configuration" id="editing-old-style-conf-files"
  xreflabel="Editing Old-Style conf files">
  <title>Editing Old-Style conf files</title>

    <para>
      Some fonts, particularly Chinese fonts, ship with conf files which can be
      installed in <filename class="directory">/etc/fonts/conf.d</filename>.
      However, if you do that and then use a terminal to run any command which
      uses <application>fontconfig</application> you may see error messages such
      as :
    </para>

    <para>
      <literal>Fontconfig warning: "/etc/fonts/conf.d/69-odofonts.conf", line
      14: Having multiple &lt;family&gt; in &lt;alias&gt; isn't supported and
      may not work as expected</literal>.
    </para>

    <para>
      In practice, these old rules do not work. For non-CJK users,
      <application>fontconfig</application> will usually do a good job
      <emphasis>without</emphasis> 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 <application>Gtk</application> 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.
    </para>

    <para>
      Nevertheless, these old conf files can be fixed if you wish to use them.
      The following example is the first part of
      <filename>64-arphic-uming.conf</filename> from <xref linkend="UMing"/> -
      there are many more similar items which also need changing :
    </para>

    <para>
      <literallayout>
   &lt;match target="pattern"&gt;
       &lt;test qual="any" name="lang" compare="contains"&gt;
           &lt;string&gt;zh-cn&lt;/string&gt;
           &lt;string&gt;zh-sg&lt;/string&gt;
       &lt;/test&gt;
       &lt;test qual="any" name="family"&gt;
           &lt;string&gt;serif&lt;/string&gt;
       &lt;/test&gt;
       &lt;edit name="family" mode="prepend" binding="strong"&gt;
           &lt;string&gt;AR PL UMing CN&lt;/string&gt;
       &lt;/edit&gt;
    &lt;/match&gt;</literallayout>
    </para>

    <para>
      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 <command>fc-list 2>&amp;1 |
      less</command> to see that the fix worked. For the block above, the fixed
      version will be :
    </para>

    <para>
      <literallayout>
   &lt;match target="pattern"&gt;
       &lt;test qual="any" name="lang" compare="contains"&gt;
           &lt;string&gt;zh-cn&lt;/string&gt;
       &lt;/test&gt;
       &lt;test qual="any" name="family"&gt;
           &lt;string&gt;serif&lt;/string&gt;
       &lt;/test&gt;
       &lt;edit name="family" mode="prepend" binding="strong"&gt;
           &lt;string&gt;AR PL UMing CN&lt;/string&gt;
       &lt;/edit&gt;
    &lt;/match&gt;
   &lt;match target="pattern"&gt;
       &lt;test qual="any" name="lang" compare="contains"&gt;
           &lt;string&gt;zh-sg&lt;/string&gt;
       &lt;/test&gt;
       &lt;test qual="any" name="family"&gt;
           &lt;string&gt;serif&lt;/string&gt;
       &lt;/test&gt;
       &lt;edit name="family" mode="prepend" binding="strong"&gt;
           &lt;string&gt;AR PL UMing CN&lt;/string&gt;
       &lt;/edit&gt;
    &lt;/match&gt;</literallayout>
    </para>

    <bridgehead renderas="sect3" id="items-which-can-override-fontconfig"
    xreflabel="Items which can override fontconfig">Items which can override fontconfig</bridgehead>

    <para>
      Several desktop environments, as well as some programs, will use fontconfig
      to find fonts but may override certain things.
    </para>

    <para>
      GNOME: The settings in org.gnome.desktop.interface can be updated with
      <application>dconf-editor</application>. You can set the fonts to your preference
      and desired point size. To use the fonts chosen by fontconfig specify e.g.
      'Sans 12', Serif 11', 'Mono 10' as desired. Also review the antialiasing, hinting
      and rgba settings.
    </para>

    <para>
      LXQt: Change font settings as necessary to match fontconfig in
      <application>lxqt-config-appearance</application>.
    </para>

    <para>
      KDE Plasma: The settings can be adjusted in <application>System
      Settings</application> under Appearance -> Fonts. This will create or modify
      <filename>~/.config/fontconfig/fonts.conf</filename> although
      <filename>~/.config/fontconfig/fonts.conf</filename>, if installed, can
      override that.
    </para>

    <para>
      Xfce desktop: The settings can be adjusted in
      <application>Settings</application> Appearance -> Fonts. Specify your
      preferred fonts, e.g. 'Sans Regular' (to use the regular face and weight
      rather than Bold and/or Italic) and adjust the point size in the option.
      Review the Rendering and DPI options.
    </para>

    <para>
      Firefox: This browser allows you to specify its default fonts. For the 115esr
      series, use the 'Hamburger' menu to got to Preferences, General, and under Fonts
      -> Advanced select Sans Serif, Serif, Monospace as appropriate if you wish to use
      the fonts which match fontconfig.  Set the point sizes as desired. In later
      versions, the settings are at Preferences -> Fonts.
      <!-- FIXME : Ken - when merging, add note in packages to update this when next ESR
      series is used --> 
    </para>

    <para>
      Libreoffice: Tests using English text with an old Japanese font (HanaMinA)
      which supports several European languages but had only one weight and no
      italics or slant showed that although <application>Libreoffice</application>
      uses fontconfig to find the font, it created its own bold or slanted text.
      It is not clear if it will do the same where a font actually has bold weight
      or an italic face. Also, documentation shows that Libreoffice has its own
      substitution rules for when a codepoint is not found in the selected font,
      but is unclear if those rules apply on Linux using fontconfig.
    </para>

    <para>
      Pango: as noted in the example <filename>~/.config/fontconfig</filename>
      above, anything using Pango-1.44 (from 2019) or later now uses Harfbuzz for
      hinting, not FreeType, and <literal>hintfull</literal> is not supported.
    </para>

  </sect2>

  <sect2 role="configuration" id="see-also" xreflabel="See Also">
  <title>See Also</title>

    <bridgehead renderas="sect3" id="I-stared-into-the-fontconfig"
    xreflabel="I stared into the fontconfig">I stared into the fontconfig ...</bridgehead>

    <para>
      The blog entries by <ulink
      url="https://eev.ee/blog/2015/05/20/i-stared-into-the-fontconfig-and-the-fontconfig-stared-back-at-me/">Eevee</ulink>
      are particularly useful if <application>fontconfig</application> 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.
    </para>

    <bridgehead renderas="sect3" id="subpixel-hinting"
    xreflabel="subpixel-hinting">subpixel-hinting</bridgehead>

    <para>The documentation of the FreeType v40 interpreter at <ulink
      url="https://freetype.org/freetype2/docs/hinting/subpixel-hinting.html">freetype
      docs</ulink>
      explains how the current hinter works, and why the previous (slow) Infinality
      interpreter was replaced.
    </para>

    <bridgehead renderas="sect3" id="calc-dpi"
    xreflabel="calc-dpi">Calculating DPI</bridgehead>

    <para>An old answer at <ulink
      url="https://askubuntu.com/questions/197828/how-to-find-and-change-the-screen-dpi/">askubuntu</ulink>
      gives some detail on calculating a screen's dots per inch, but essentailly
      you just measure the width and height of the visible panel, convert to
      inches if using metric measurements, and divide by the number of pixels.
      You can then pass <option>-dpi <replaceable>90</replaceable></option> when
      you start Xorg, using your own value.
    </para>

    <bridgehead renderas="sect3" id="arch-fontconfig"
    xreflabel="Fontconfig in the Arch wiki">Fontconfig in the Arch wiki</bridgehead>

    <para>
      Arch has a lot of information in its wiki at <ulink
      url="https://wiki.archlinux.org/index.php/font_configuration">font_configuration</ulink>.
    </para>

    <bridgehead renderas="sect3" id="gentoo-fontconfig"
    xreflabel="Fontconfig in the Gentoo wiki">Fontconfig in the Gentoo wiki</bridgehead>

    <para>
      Gentoo has some information in its wiki at <ulink
      url="https://wiki.gentoo.org/wiki/Fontconfig">Fontconfig</ulink> although
      a lot of the details (what to enable, and Infinality) are specific to
      Gentoo.
    </para>

  </sect2>

</sect1>