Difference between revisions of "Font configuration"

From ArchWiki
Jump to: navigation, search
(Infinality)
(Calibri, Cambria, Monaco, etc. not rendering properly: mention alternative to disabling bitmaps, re Talk:Croscore Fonts)
 
(215 intermediate revisions by 77 users not shown)
Line 1: Line 1:
 
[[Category:Fonts]]
 
[[Category:Fonts]]
[[it:Font Configuration]]
+
[[it:Font configuration]]
[[ru:Font Configuration]]
+
[[ja:フォント設定]]
[[sr:Font Configuration]]
+
[[ru:Font configuration]]
[[tr:Yazıtipi_yapılandırması]]
+
[[sr:Font configuration]]
[[zh-CN:Font Configuration]]
+
[[tr:Yazıtipi yapılandırması]]
{{Article summary start}}
+
[[zh-cn:Font configuration]]
{{Article summary text|An overview of font configuration options and various techniques for improving the readability of fonts}}
+
{{Related articles start}}
{{Article summary heading|Related}}
+
{{Related|Fonts}}
{{Article summary wiki|Fonts}}: Information on adding fonts and font recommendations
+
{{Related|Font configuration/Examples}}
{{Article summary wiki|Java Runtime Environment Fonts}}: Fonts specific to Sun's Java machine
+
{{Related|Infinality}}
{{Article summary wiki|MS Fonts}}: Adding Microsoft fonts and mimicking Windows' font settings
+
{{Related|Java Runtime Environment Fonts}}
{{Article summary wiki|Font Configuration/fontconfig Examples}}
+
{{Related|MS Fonts}}
{{Article summary end}}
+
{{Related|X Logical Font Description}}
 +
{{Related articles end}}
  
Fontconfig is a library designed to provide a list of available [[fonts]] to applications, and also for configuration for how fonts get rendered.  See package {{Pkg|fontconfig}} and [[Wikipedia:Fontconfig]]. The Free type library ({{Pkg|freetype2}} package) renders the fonts, based on this configuration.
+
[http://www.freedesktop.org/wiki/Software/fontconfig/ Fontconfig] is a library designed to provide a list of available [[fonts]] to applications, and also for configuration for how fonts get rendered: see [[Wikipedia:Fontconfig]]. The FreeType library {{Pkg|freetype2}} renders the fonts, based on this configuration.
  
Though Fontconfig is the standard in today's Linux, some applications still rely on the original method of font categorization: the Xorg server configuration.
+
Though Fontconfig is the standard in modern Linux, some applications rely on the original method of font selection and display, the [[X Logical Font Description]].
  
The font rendering packages on Arch Linux includes support for ''freetype2'' with the bytecode interpreter (BCI) enabled. Patched packages exist for better font rendering, especially with an LCD monitor.  See [[#Patched packages]] below.  The [[#Infinality]] package allows both auto-hinting and subpixel rendering, allows the LCD filter to be tweaked without recompiling, and allows the auto-hinter to work well with bold fonts.
+
The font rendering packages on Arch Linux includes support for ''freetype2'' with the bytecode interpreter (BCI) enabled. For better font rendering, especially with an LCD monitor, see [[#Fontconfig configuration]] and [[Font configuration/Examples]].
  
==Font paths==
+
== Font paths ==
  
 
For fonts to be known to applications, they must be cataloged for easy and quick access.
 
For fonts to be known to applications, they must be cataloged for easy and quick access.
  
The font paths initially known to Fontconfig are: {{ic|/usr/share/fonts/}} and {{ic|~/.fonts/}} (of which Fontconfig will scan recursively). For ease of organization and installation, it is recommended to use these font paths when [[Fonts#Installation|adding fonts]].
+
The font paths initially known to Fontconfig are: {{ic|/usr/share/fonts/}}, {{ic|~/.local/share/fonts}} (and {{ic|~/.fonts/}}, now deprecated). Fontconfig will scan these directories recursively. For ease of organization and installation, it is recommended to use these font paths when [[adding fonts]].
  
 
To see a list of known Fontconfig fonts:
 
To see a list of known Fontconfig fonts:
 
  $ fc-list : file
 
  $ fc-list : file
  
See {{ic|man fc-list}} for more out put format.
+
See {{ic|man fc-list}} for more output formats.
  
 
Check for Xorg's known font paths by reviewing its log:
 
Check for Xorg's known font paths by reviewing its log:
$ grep /fonts /var/log/Xorg.0.log
 
  
{{Tip|You can also check the list of [[Xorg]]'s known font paths using the command {{ic|xset q}}.}}
+
$ grep /fonts ~/.local/share/xorg/Xorg.0.log
 +
 
 +
{{Tip|
 +
* You can also check the list of [[Xorg]]'s known font paths using the command {{ic|xset q}}.
 +
* Use {{ic|/var/log/Xorg.0.log}} if Xorg is run with root privileges.
 +
}}
  
 
Keep in mind that Xorg does not search recursively through the {{ic|/usr/share/fonts/}} directory like Fontconfig does.  To add a path, the full path must be used:
 
Keep in mind that Xorg does not search recursively through the {{ic|/usr/share/fonts/}} directory like Fontconfig does.  To add a path, the full path must be used:
Line 47: Line 52:
 
To see a list of known Xorg fonts use {{ic|xlsfonts}}, from the {{Pkg|xorg-xlsfonts}} package.
 
To see a list of known Xorg fonts use {{ic|xlsfonts}}, from the {{Pkg|xorg-xlsfonts}} package.
  
==Fontconfig configuration==
+
== Fontconfig configuration ==
  
Fontconfig is documented in the [http://fontconfig.org/fontconfig-user.html fonts.conf] man page.
+
Fontconfig is documented in the [http://www.freedesktop.org/software/fontconfig/fontconfig-user.html fonts-conf] man page.
  
 
Configuration can be done per-user through {{ic|$XDG_CONFIG_HOME/fontconfig/fonts.conf}}, and globally with {{ic|/etc/fonts/local.conf}}.  The settings in the per-user configuration have precedence over the global configuration.  Both these files use the same syntax.
 
Configuration can be done per-user through {{ic|$XDG_CONFIG_HOME/fontconfig/fonts.conf}}, and globally with {{ic|/etc/fonts/local.conf}}.  The settings in the per-user configuration have precedence over the global configuration.  Both these files use the same syntax.
{{Note|Configuration files and directories: {{ic|~/.fonts.conf}}, {{ic|~/.fonts.conf.d}} and {{ic|~/.fontconfig/*.cache-*}} are deprecated since fontconfig 2.10.1 ([http://cgit.freedesktop.org/fontconfig/commit/?id=8c255fb185d5651b57380b0a9443001e8051b29d upstream commit]) and will not be read by default in the future versions of package. Use instead {{ic|$XDG_CONFIG_HOME/fontconfig/fonts.conf}}, {{ic|$XDG_CONFIG_HOME/fontconfig/conf.d}} and {{ic|$XDG_CACHE_HOME/fontconfig/*.cache-*}} respectively.}}
+
{{Note|Configuration files and directories: {{ic|~/.fonts.conf/}}, {{ic|~/.fonts.conf.d/}} and {{ic|~/.fontconfig/*.cache-*}} are deprecated since {{Pkg|fontconfig}} 2.10.1 ([http://cgit.freedesktop.org/fontconfig/commit/?id=8c255fb185d5651b57380b0a9443001e8051b29d upstream commit]) and will not be read by default in the future versions of the package. New paths are {{ic|$XDG_CONFIG_HOME/fontconfig/fonts.conf}}, {{ic|$XDG_CONFIG_HOME/fontconfig/conf.d/NN-name.conf}} and {{ic|$XDG_CACHE_HOME/fontconfig/*.cache-*}} respectively. If using the second location, make sure the naming is valid (where {{ic|NN}} is a two digit number like {{ic|00}}, {{ic|10}}, or {{ic|99}}).}}
  
Fontconfig gathers all its configurations in a central file ({{ic|/etc/fonts/fonts.conf}}).  This file is replaced during fontconfig updates and shouldn't be edited.  Fontconfig-aware applications source this file to know available fonts and how they get rendered.  This file is a conglomeration of rules from the global configuration ({{ic|/etc/fonts/local.conf}}), the configured presets in {{ic|/etc/fonts/conf.d/}}, and the user configuration file ({{ic|$XDG_CONFIG_HOME/fontconfig/fonts.conf}}).
+
Fontconfig gathers all its configurations in a central file ({{ic|/etc/fonts/fonts.conf}}).  This file is replaced during fontconfig updates and should not be edited.  Fontconfig-aware applications source this file to know available fonts and how they get rendered.  This file is a conglomeration of rules from the global configuration ({{ic|/etc/fonts/local.conf}}), the configured presets in {{ic|/etc/fonts/conf.d/}}, and the user configuration file ({{ic|$XDG_CONFIG_HOME/fontconfig/fonts.conf}}). {{ic|fc-cache}} can be used to rebuild fontconfig's configuration, although changes will only be visible in newly launched applications.
  
 
{{Note|For some desktop environments (such as [[GNOME]] and [[KDE]]) using the ''Font Control Panel'' will automatically create or overwrite the user font configuration file.  For these desktop environments, it is best to match your already defined font configurations to get the expected behavior.}}
 
{{Note|For some desktop environments (such as [[GNOME]] and [[KDE]]) using the ''Font Control Panel'' will automatically create or overwrite the user font configuration file.  For these desktop environments, it is best to match your already defined font configurations to get the expected behavior.}}
Line 72: Line 77:
 
The configuration examples in this article omit these tags.
 
The configuration examples in this article omit these tags.
  
===Presets===
+
=== Presets ===
  
 
There are presets installed in the directory {{ic|/etc/fonts/conf.avail}}.  They can be enabled by creating [[Wikipedia:Symbolic link|symbolic link]]s to them, both per-user and globally, as described in {{ic|/etc/fonts/conf.d/README}}.  These presets will override matching settings in their respective configuration files.
 
There are presets installed in the directory {{ic|/etc/fonts/conf.avail}}.  They can be enabled by creating [[Wikipedia:Symbolic link|symbolic link]]s to them, both per-user and globally, as described in {{ic|/etc/fonts/conf.d/README}}.  These presets will override matching settings in their respective configuration files.
Line 86: Line 91:
 
  $ ln -s /etc/fonts/conf.avail/10-sub-pixel-rgb.conf $XDG_CONFIG_HOME/fontconfig/conf.d
 
  $ ln -s /etc/fonts/conf.avail/10-sub-pixel-rgb.conf $XDG_CONFIG_HOME/fontconfig/conf.d
  
===Anti-aliasing===
+
=== Anti-aliasing ===
  
[[Wikipedia:Font rasterization|Font rasterization]] converts vector font data to bitmap data so that it can be displayed. The result can appear jagged due to [[Wikipedia:Aliasing|aliasing]]. [[Wikipedia:Anti-aliasing|anti-aliasing]] is enabled by default and increases the apparent resolution of font edges.
+
[[Wikipedia:Font rasterization|Font rasterization]] converts vector font data to bitmap data so that it can be displayed. The result can appear jagged due to [[Wikipedia:Aliasing|aliasing]]. [[Wikipedia:Anti-aliasing|anti-aliasing]] is '''enabled''' by default and increases the apparent resolution of font edges. To disable it:
  
 
{{bc|<nowiki>
 
{{bc|<nowiki>
 
   <match target="font">
 
   <match target="font">
 
     <edit name="antialias" mode="assign">
 
     <edit name="antialias" mode="assign">
       <bool>true</bool>
+
       <bool>false</bool>
 
     </edit>
 
     </edit>
 
   </match>
 
   </match>
 
</nowiki>}}
 
</nowiki>}}
  
===Hinting===
+
{{Note|Some applications, like [[GNOME]] may [[#Troubleshooting|override default anti-aliasing settings]].}}
  
[[Wikipedia:Font hinting|Font hinting]] (also known as instructing) is the use of mathematical instructions to adjust the display of an outline font so that it lines up with a rasterized grid, such as the pixel grid in a display. Fonts will not line up correctly without hinting until displays have 300 [[Wikipedia:Dots per inch|DPI]] or greater. Two types of hinting are available.
+
=== Hinting ===
  
====Byte-Code Interpreter (BCI)====
+
[[Wikipedia:Font hinting|Font hinting]] (also known as instructing) is the use of mathematical instructions to adjust the display of an outline font so that it lines up with a rasterized grid, (i.e. the pixel grid of the display). Its intended effect is to make fonts appear more crisp so that they are more readable. Fonts will line up correctly without hinting when displays have around 300 [[Wikipedia:Dots per inch|DPI]].
Using normal hinting, TrueType hinting instructions in the font are interpreted by freetype's Byte-Code Interpreter. This works best for fonts with good hinting instructions.
+
  
To enable normal hinting:
+
==== Byte-Code Interpreter (BCI) ====
 +
 
 +
Using BCI hinting, instructions in TrueType fonts are rendered according to FreeTypes's interpreter. BCI hinting works well with fonts with good hinting instructions. Hinting is '''enabled''' by default. To disable it:
  
 
{{bc|<nowiki>
 
{{bc|<nowiki>
 
   <match target="font">
 
   <match target="font">
 
     <edit name="hinting" mode="assign">
 
     <edit name="hinting" mode="assign">
       <bool>true</bool>
+
       <bool>false</bool>
 
     </edit>
 
     </edit>
 
   </match>
 
   </match>
 
</nowiki>}}
 
</nowiki>}}
  
====Autohinter====
+
==== Autohinter ====
Auto-discovery for hinting. This looks worse than normal hinting for fonts with good instructions, but better for those with poor or no instructions. The autohinter and subpixel rendering are not designed to work together and should not be used in combination.
+
  
To enable auto-hinting:
+
The autohinter attempts to do automatic hinting and disregards any existing hinting information. Originally it was the default because TrueType2 fonts were patent-protected but now that these patents have expired there is very little reason to use it. It does work better with fonts that have broken or no hinting information but it will be strongly sub-optimal for fonts with good hinting information. Generally common fonts are of the later kind so autohinter will not be useful. Autohinter is '''disabled''' by default. To enable it:
  
 
{{bc|<nowiki>
 
{{bc|<nowiki>
Line 128: Line 133:
 
</nowiki>}}
 
</nowiki>}}
  
====Hint style====
+
==== Hintstyle ====
  
Hint style is the amount of influence the hinting mode has.  Hinting can be set to: {{ic|hintfull}}, {{ic|hintmedium}}, {{ic|hintslight}} and {{ic|hintnone}}. With BCI hinting, hintfull should work best for most fonts. With the autohinter, hintslight is recommended.
+
Hintstyle is the amount of font reshaping done to line up to the grid.  Hinting values are: {{ic|hintnone}}, {{ic|hintslight}}, {{ic|hintmedium}}, and {{ic|hintfull}}. {{ic|hintslight}} will make the font more fuzzy to line up to the grid but will be better in retaining font shape, while {{ic|hintfull}} will be a crisp font that aligns well to the pixel grid but will lose a greater amount of font shape. '''{{ic|hintslight}}''' is the default setting. To change it:
  
 
{{bc|<nowiki>
 
{{bc|<nowiki>
 
   <match target="font">
 
   <match target="font">
 
     <edit name="hintstyle" mode="assign">
 
     <edit name="hintstyle" mode="assign">
       <const>hintfull</const>
+
       <const>hintnone</const>
 
     </edit>
 
     </edit>
 
   </match>
 
   </match>
 
</nowiki>}}
 
</nowiki>}}
  
===Subpixel rendering===
+
{{Note|Some applications, like [[GNOME]] may [[#Troubleshooting|override default hinting settings.]]}}
  
Subpixel rendering effectively triples the horizontal (or vertical) resolution for fonts by making use of subpixels. The autohinter and subpixel rendering are not designed to work together and should not be used in combination without the [[#Infinality]] patch set.
+
=== Subpixel rendering ===
  
Most monitors manufactured today use the Red, Green, Blue (RGB) specification. Fontconfig will need to know your monitor type to be able to display your fonts correctly.
+
Most monitors manufactured today use the Red, Green, Blue (RGB) specification. Fontconfig will need to know your monitor type to be able to display your fonts correctly. Monitors are either: '''RGB''' (most common), '''BGR''', '''V-RGB''' (vertical), or '''V-BGR'''.  A monitor test can be found [http://www.lagom.nl/lcd-test/subpixel.php here].
 
+
''RGB (most common), BGR, V-RGB (vertical), or V-BGR''
+
  
 
To enable subpixel rendering:
 
To enable subpixel rendering:
Line 158: Line 161:
 
</nowiki>}}
 
</nowiki>}}
  
If you notice unusual colors around font's borders, the wrong subpixel arrangement might be configured. The [http://www.lagom.nl/lcd-test/subpixel.php Lagom subpixel layout test] web page can help identify it.
+
{{Note|1=Subpixel rendering effectively triples the horizontal (or vertical) resolution for fonts by making use of subpixels. The default autohinter and subpixel rendering are not designed to work together, hence you will want to enable the subpixel autohinter by Infinality, et al. Freetype2 is compiled with [https://projects.archlinux.org/svntogit/packages.git/tree/trunk/0003-Enable-subpixel-hinting.patch?h=9867afd the <tt>TT_CONFIG_OPTION_SUBPIXEL_HINTING</tt> macro]. However, it must be enabled by setting the FT2_SUBPIXEL_HINTING [[environment variable]] to any value.{{Bug|35274}}}}
  
====LCD filter====
+
==== LCD filter ====
  
 
When using subpixel rendering, you should enable the LCD filter, which is designed to reduce colour fringing.  This is described under [http://www.freetype.org/freetype2/docs/reference/ft2-lcd_filtering.html LCD filtering] in the FreeType 2 API reference.  Different options are described under [http://www.freetype.org/freetype2/docs/reference/ft2-lcd_filtering.html#FT_LcdFilter FT_LcdFilter], and are illustrated by this [http://www.spasche.net/files/lcdfiltering/ LCD filter test] page.
 
When using subpixel rendering, you should enable the LCD filter, which is designed to reduce colour fringing.  This is described under [http://www.freetype.org/freetype2/docs/reference/ft2-lcd_filtering.html LCD filtering] in the FreeType 2 API reference.  Different options are described under [http://www.freetype.org/freetype2/docs/reference/ft2-lcd_filtering.html#FT_LcdFilter FT_LcdFilter], and are illustrated by this [http://www.spasche.net/files/lcdfiltering/ LCD filter test] page.
Line 168: Line 171:
 
{{bc|<nowiki>
 
{{bc|<nowiki>
 
   <match target="font">
 
   <match target="font">
     <edit mode="assign" name="lcdfilter">
+
     <edit name="lcdfilter" mode="assign">
 
       <const>lcddefault</const>
 
       <const>lcddefault</const>
 
     </edit>
 
     </edit>
Line 174: Line 177:
 
</nowiki>}}
 
</nowiki>}}
  
====Advanced LCD filter specification====
+
==== Advanced LCD filter specification ====
  
 
If the available, built-in LCD filters are not satisfactory, it is possible to tweak the font rendering very specifically by building a custom freetype2 package and modifying the hardcoded filters. The [[Arch Build System]] can be used to build and install packages from source.
 
If the available, built-in LCD filters are not satisfactory, it is possible to tweak the font rendering very specifically by building a custom freetype2 package and modifying the hardcoded filters. The [[Arch Build System]] can be used to build and install packages from source.
 +
 +
{{Tip|With the [[Infinality]] packages, the LCD filter can be modified without rebuilds.}}
  
 
First, refresh the freetype2 PKGBUILD as root:
 
First, refresh the freetype2 PKGBUILD as root:
Line 197: Line 202:
  
 
  $ makepkg -e
 
  $ makepkg -e
  $ sudo pacman -Rd freetype2
+
  # pacman -Rd freetype2
  $ sudo pacman -U freetype2-VERSION-ARCH.pkg.tar.xz
+
  # pacman -U freetype2-VERSION-ARCH.pkg.tar.xz
  
 
Reboot or restart X. The lcddefault filter should now render fonts differently.
 
Reboot or restart X. The lcddefault filter should now render fonts differently.
  
===Disable auto-hinter for bold fonts===
+
=== Disable auto-hinter for bold fonts ===
  
 
The auto-hinter uses sophisticated methods for font rendering, but often makes bold fonts too wide. Fortunately, a solution can be turning off the autohinter for bold fonts while leaving it on for the rest:
 
The auto-hinter uses sophisticated methods for font rendering, but often makes bold fonts too wide. Fortunately, a solution can be turning off the autohinter for bold fonts while leaving it on for the rest:
Line 216: Line 221:
 
  ...
 
  ...
  
=== Enable anti-aliasing only for bigger fonts ===
+
=== Replace or set default fonts ===
  
''See also [http://sharpfonts.co.cc/ sharpfonts.co.cc] for related information.''
+
The most reliable way to do this is to add an XML fragment similar to the one below. ''Using the "binding" attribute will give you better results'', for example, in Firefox where you may not want to change properties of font being replaced. This will cause Ubuntu to be used in place of Georgia:
 
+
Some users prefer the sharper rendering that anti-aliasing does not offer:
+
  
 
{{bc|<nowiki>
 
{{bc|<nowiki>
 
...
 
...
<match target="font">
+
<match target="pattern">
    <edit name="antialias" mode="assign">
+
  <test qual="any" name="family"><string>georgia</string></test>
        <bool>false</bool>
+
  <edit name="family" mode="assign" binding="same"><string>Ubuntu</string></edit>
    </edit>
+
</match>
</match>
+
...
 +
</nowiki>}}
  
<match target="font" >
+
An alternate approach is to set the "preferred" font, but ''this only works if the original font is not on the system'', in which case the one specified will be substituted:
    <test name="size" qual="any" compare="more">
+
        <double>12</double>
+
    </test>
+
    <edit name="antialias" mode="assign">
+
        <bool>true</bool>
+
    </edit>
+
</match>
+
  
<match target="font" >
+
{{bc|<nowiki>
    <test name="pixelsize" qual="any" compare="more">
+
...
        <double>16</double>
+
<!-- Replace Helvetica with Bitstream Vera Sans Mono -->
     </test>
+
<!-- Note, an alias for Helvetica should already exist in default conf files -->
     <edit name="antialias" mode="assign">
+
<alias>
        <bool>true</bool>
+
     <family>Helvetica</family>
     </edit>
+
     <prefer><family>Bitstream Vera Sans Mono</family></prefer>
</match>
+
     <default><family>fixed</family></default>
 +
</alias>
 
...
 
...
 
</nowiki>}}
 
</nowiki>}}
  
===Replace fonts===
+
Example fonts.conf which also specifies a default font for the Japanese locale (ja_JP) and keeps western style fonts for Latin letters.
  
The most reliable way to do this is to add an XML fragment similar to the one below. ''Using the "binding" attribute will give you better results'', for example, in Firefox where you may not want to change properties of font being replaced. This will cause Ubuntu to be used in place of Georgia:
+
{{bc|<nowiki>
  ...
+
<?xml version='1.0'?>
   <match target="pattern">
+
<!DOCTYPE fontconfig SYSTEM 'fonts.dtd'>
    <test qual="any" name="family"><string>georgia</string></test>
+
<fontconfig>
    <edit name="family" mode="assign" binding="same"><string>Ubuntu</string></edit>
+
 
  </match>
+
<!-- Default font (no fc-match pattern) -->
  ...
+
<match>
An alternate approach is to set the "preferred" font, but ''this only works if the original font is not on the system'', in which case the one specified will be substituted:
+
  <edit mode="prepend" name="family">
  ...
+
  <string>Noto Sans</string>
  < !-- Replace Helvetica with Bitstream Vera Sans Mono -->
+
  </edit>
  < !-- Note, an alias for Helvetica should already exist in default conf files -->
+
</match>
 +
 
 +
<!-- Default font for the ja_JP locale (no fc-match pattern) -->
 +
  <match>
 +
   <test compare="contains" name="lang">
 +
  <string>ja</string>
 +
  </test>
 +
  <edit mode="prepend" name="family">
 +
  <string>Noto Sans CJK JP</string>
 +
  </edit>
 +
</match>
 +
 
 +
<!-- Default sans-serif font -->
 +
<match target="pattern">
 +
  <test qual="any" name="family"><string>sans-serif</string></test>
 +
  <!--<test qual="any" name="lang"><string>ja</string></test>-->
 +
  <edit name="family" mode="prepend" binding="same"><string>Noto Sans</string> </edit>
 +
</match>
 +
   
 +
<!-- Default serif fonts -->
 +
<match target="pattern">
 +
  <test qual="any" name="family"><string>serif</string></test>
 +
  <edit name="family" mode="prepend" binding="same"><string>Noto Serif</string> </edit>
 +
  <edit name="family" mode="append" binding="same"><string>IPAPMincho</string> </edit>
 +
  <edit name="family" mode="append" binding="same"><string>HanaMinA</string>  </edit>
 +
</match>
 +
 
 +
<!-- Default monospace fonts -->
 +
  <match target="pattern">
 +
  <test qual="any" name="family"><string>monospace</string></test>
 +
  <edit name="family" mode="prepend" binding="same"><string>Inconsolatazi4</string></edit>
 +
  <edit name="family" mode="append" binding="same"><string>IPAGothic</string></edit>
 +
</match>
 +
 
 +
<!-- Fallback fonts preference order -->
 
  <alias>
 
  <alias>
    <family>Helvetica</family>
+
  <family>sans-serif</family>
    <prefer><family>Bitstream Vera Sans Mono</family></prefer>
+
  <prefer>
    <default><family>fixed</family></default>
+
  <family>Noto Sans</family>
 +
  <family>Open Sans</family>
 +
  <family>Droid Sans</family>
 +
  <family>Ubuntu</family>
 +
  <family>Roboto</family>
 +
  <family>NotoSansCJK</family>
 +
  <family>Source Han Sans JP</family>
 +
  <family>IPAPGothic</family>
 +
  <family>VL PGothic</family>
 +
  <family>Koruri</family>
 +
  </prefer>
 +
</alias>
 +
<alias>
 +
  <family>serif</family>
 +
  <prefer>
 +
  <family>Noto Serif</family>
 +
  <family>Droid Serif</family>
 +
  <family>Roboto Slab</family>
 +
  <family>IPAPMincho</family>
 +
  </prefer>
 +
</alias>
 +
<alias>
 +
  <family>monospace</family>
 +
  <prefer>
 +
  <family>Inconsolatazi4</family>
 +
  <family>Ubuntu Mono</family>
 +
  <family>Droid Sans Mono</family>
 +
  <family>Roboto Mono</family>
 +
  <family>IPAGothic</family>
 +
  </prefer>
 
  </alias>
 
  </alias>
...
 
  
===Disable bitmap fonts===
+
<dir>~/.fonts</dir>
 +
</fontconfig>
 +
</nowiki>}}
  
To disable bitmap fonts in fontconfig, use {{ic|70-no-bitmaps.conf}} (which is not placed by fontconfig by default):
+
=== Whitelisting and blacklisting fonts ===
  
# cd /etc/fonts/conf.d
+
The element {{ic|<selectfont>}} is used in conjunction with the {{ic|<acceptfont>}} and {{ic|<rejectfont>}} elements to selectively whitelist or blacklist fonts from the resolve list and match requests. The simplest and most typical use case it to reject one font that is needed to be installed, however is getting matched for a generic font query that is causing problems within application user interfaces.
# rm 70-yes-bitmaps.conf
+
# ln -s ../conf.avail/70-no-bitmaps.conf
+
  
You may not need to remove {{ic|70-yes-bitmaps.conf}} if it does not exist. You can choose which fonts to replace bitmaps fonts with (Helvetica, Courier and Times bitmap mapts to TTF fonts) by:
+
First obtain the Family name as listed in the font itself:
  
# cd /etc/fonts/conf.d
+
{{hc|1=$ fc-scan .fonts/lklug.ttf --format='%{family}\n'|2=
# ln -s ../conf.avail/29-replace-bitmap-fonts.conf
+
LKLUG
 +
}}
 +
 
 +
Then use that Family name in a {{ic|<rejectfont>}} stanza:
 +
 
 +
{{bc|<nowiki>
 +
<selectfont>
 +
    <rejectfont>
 +
        <pattern>
 +
            <patelt name="family" >
 +
                <string>LKLUG</string>
 +
            </patelt>
 +
        </pattern>
 +
    </rejectfont>
 +
</selectfont>
 +
</nowiki>}}
 +
 
 +
Typically when both elements are combined, {{ic|<rejectfont>}} is first used on a more general matching glob to reject a large group (such as a whole directory), then {{ic|<acceptfont>}} is used after it to whitelist individual fonts out of the larger blacklisted group.
 +
 
 +
{{bc|<nowiki>
 +
<selectfont>
 +
    <rejectfont>
 +
        <glob>/usr/share/fonts/OTF/*</glob>
 +
    </rejectfont>
 +
    <acceptfont>
 +
        <pattern>
 +
            <patelt name="family" >
 +
                <string>Monaco</string>
 +
            </patelt>
 +
        </pattern>
 +
    </acceptfont>
 +
</selectfont>
 +
</nowiki>}}
 +
 
 +
=== Disable bitmap fonts ===
 +
 
 +
Bitmap fonts are sometimes used as fallbacks for missing fonts, which may cause text to be rendered pixelated or too large. Use the {{ic|70-no-bitmaps.conf}} [[#Presets|preset]] to disable this behavior.  
 +
 
 +
<div id="EmbeddedBitmap">To disable embedded bitmap for all fonts:<div>
 +
 
 +
{{hc|~/.config/fontconfig/conf.d/20-no-embedded.conf|<nowiki>
 +
<?xml version="1.0"?>
 +
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
 +
<fontconfig>
 +
  <match target="font">
 +
    <edit name="embeddedbitmap" mode="assign">
 +
      <bool>false</bool>
 +
    </edit>
 +
  </match>
 +
</fontconfig>
 +
</nowiki>}}
  
 
To disable embedded bitmap fonts for a specific font:
 
To disable embedded bitmap fonts for a specific font:
Line 292: Line 402:
 
  </match>
 
  </match>
  
===Create bold and italic styles for incomplete fonts===
+
=== Disable scaling of bitmap fonts ===
 +
 
 +
To disable scaling of bitmap fonts (which often makes them blurry), remove {{ic|/etc/fonts/conf.d/10-scale-bitmap-fonts.conf}}.
 +
 
 +
=== Create bold and italic styles for incomplete fonts ===
  
Freetype has the ability to automatically create ''italic'' and '''bold''' styles for fonts that do not have them, but only if explicitly required by the application. Given programs rarely send these requests, this section covers manually forcing generation of missing styles.
+
FreeType has the ability to automatically create ''italic'' and '''bold''' styles for fonts that do not have them, but only if explicitly required by the application. Given programs rarely send these requests, this section covers manually forcing generation of missing styles.
  
 
Start by editing {{ic|/usr/share/fonts/fonts.cache-1}} as explained below. Store a copy of the modifications on another file, because a font update with {{ic|fc-cache}} will overwrite {{ic|/usr/share/fonts/fonts.cache-1}}.
 
Start by editing {{ic|/usr/share/fonts/fonts.cache-1}} as explained below. Store a copy of the modifications on another file, because a font update with {{ic|fc-cache}} will overwrite {{ic|/usr/share/fonts/fonts.cache-1}}.
Line 336: Line 450:
 
{{Tip| Use the value 'embolden' for existing bold fonts in order to make them even bolder.}}
 
{{Tip| Use the value 'embolden' for existing bold fonts in order to make them even bolder.}}
  
===Change rule overriding===
+
=== Change rule overriding ===
  
Fontconfig processes files in {{ic|/etc/fonts/conf.d}} in reverse numerical order. This enables rules or files to override one another, but often confuses users about what file gets parsed last.
+
{{Accuracy|{{ic|/etc/fonts/conf.d/50-user.conf}} will be created again when {{Pkg|fontconfig}} is updated}}
 +
 
 +
Fontconfig processes files in {{ic|/etc/fonts/conf.d}} in numerical order. This enables rules or files to override one another, but often confuses users about what file gets parsed last.
  
 
To guarantee that personal settings take precedence over any other rules, change their ordering:
 
To guarantee that personal settings take precedence over any other rules, change their ordering:
 
  # cd /etc/fonts/conf.d
 
  # cd /etc/fonts/conf.d
  # mv 50-user.conf 00-user.conf
+
  # mv 50-user.conf 99-user.conf
  
 
This change seems however to be unnecessary for the most of the cases, because a user is given enough control by default to set up own font preferences, hinting and antialiasing properties, alias new fonts to generic font families, etc.
 
This change seems however to be unnecessary for the most of the cases, because a user is given enough control by default to set up own font preferences, hinting and antialiasing properties, alias new fonts to generic font families, etc.
  
===Example fontconfig configurations===
+
=== Query the current settings ===
  
Example fontconfig configurations can be found on this [[Font_Configuration/fontconfig_Examples|page]].
+
To find out what settings are in effect, use {{ic|fc-match --verbose}}. eg.
  
A simple starting point:
+
$ fc-match --verbose Sans
 +
family: "DejaVu Sans"(s)
 +
hintstyle: 3(i)(s)
 +
hinting: True(s)
 +
...
  
{{hc|/etc/fonts/local.conf|<nowiki>
+
Look up the meaning of the numbers at http://www.freedesktop.org/software/fontconfig/fontconfig-user.html. Eg. 'hintstyle: 3' means 'hintfull'
<?xml version='1.0'?>
+
<!DOCTYPE fontconfig SYSTEM 'fonts.dtd'>
+
<fontconfig>
+
<match target="font">
+
 
+
  <edit mode="assign" name="rgba">
+
  <const>rgb</const>
+
  </edit>
+
  
  <edit mode="assign" name="hinting">
+
== Applications without fontconfig support ==
  <bool>true</bool>
+
  </edit>
+
  
  <edit mode="assign" name="hintstyle">
+
Some applications like [[URxvt]] will ignore fontconfig settings. You can work around this by using {{ic|~/.Xresources}}, but it is as flexible as fontconfig. Example (see [[#Fontconfig configuration]] for explanations of the options):
  <const>hintfull</const>
+
  </edit>
+
  
  <edit mode="assign" name="antialias">
+
{{hc|~/.Xresources|<nowiki>
  <bool>true</bool>
+
Xft.autohint: 0
  </edit>
+
Xft.lcdfilterlcddefault
 
+
Xft.hintstyle: hintslight
  <edit mode="assign" name="lcdfilter">
+
Xft.hinting: 1
    <const>lcddefault</const>
+
Xft.antialias: 1
  </edit>
+
Xft.rgba: rgb
   
+
</match>
+
</fontconfig>
+
 
</nowiki>}}
 
</nowiki>}}
  
==Patched packages==
+
Make sure the settings are loaded properly when X starts with {{ic|xrdb -q}} (see [[Xresources]] for more information).
  
These patched packages are available in the [[Arch User Repository|AUR]]. A few considerations:
+
== Troubleshooting ==
  
* Configuration is usually necessary.
+
=== Distorted fonts ===
* The new font rendering will not kick in until applications restart.
+
* Applications which [[Wikipedia:Static library|statically link]] to a library will not be affected by patches applied to the system library.
+
  
===Infinality===
+
{{Note|96 DPI is not a standard. You should use your monitor's actual DPI to get proper font rendering, especially when using subpixel rendering.}}
{{Note|1=Since the [http://www.archlinux.org/news/fontconfig-2101-update-manual-intervention-required/ Fontconfig 2.10.1 update], Infinality users will receive multiple warnings similar to:
+
{{ic|Fontconfig warning: "/etc/fonts/infinality/conf.d/60-group-non-tt-fonts.conf", line 483: Having multiple values in <test> isn't supported and may not works as expected}}
+
Rule adjustments are currently being worked on. See: [http://www.infinality.net/forum/viewtopic.php?f=2&t=254 this article] for more information.}}
+
  
The infinality patchset aims to greatly improve freetype2 font rendering. It adds multiple new capabilities.
+
If fonts are still unexpectedly large or small, poorly proportioned or simply rendering poorly, fontconfig may be using the incorrect DPI.
  
*[http://www.infinality.net/blog/infinality-freetype-patches/ Home page].
+
Fontconfig should be able to detect DPI parameters as discovered by the Xorg server. You can check the automatically discovered DPI with {{ic|xdpyinfo}} (provided by the {{pkg|xorg-xdpyinfo}} package):
*[http://www.infinality.net/forum/ Forum].
+
  
Infinality's settings are all configurable at runtime via environment variables in {{ic|/etc/profile.d/infinality-settings.sh}}, and include the following:
+
{{hc|<nowiki>$ xdpyinfo | grep dots</nowiki>|
 +
  resolution:    102x102 dots per inch
 +
}}
  
*'''Emboldening Enhancement''': Disables Y emboldening, producing a much nicer result on fonts without bold versions.  Works on native TT hinter and autohinter.
+
If the DPI is detected incorrectly (usually due to an incorrect monitor [[Wikipedia:Extended Display Identification Data|EDID]]), you can specify it manually in the Xorg configuration, see [[Xorg#Display size and DPI]]. This is the recommended solution, but it may not work with buggy drivers.
*'''Auto-Autohint''': Automatically forces autohint on fonts that contain no TT instructions.
+
*'''Autohint Enhancement''': Makes autohint snap horizontal stems to pixels. Gives a result that appears like a well-hinted truetype font, but is 100% patent-free (as far as I know).
+
*'''Customized FIR Filter''': Select your own [http://www.infinality.net/forum/viewtopic.php?f=2&t=19 filter values] at run-time.  Works on native TT hinter and autohinter.
+
*'''Stem Alignment''': Aligns bitmap glyphs to optimized pixel boundaries.  Works on native TT hinter and autohinter.
+
*'''Pseudo Gamma Correction''': Lighten and darken glyphs at a given value, below a given size.  Works on native TT hinter and autohinter.
+
*'''Embolden Thin Fonts''': Embolden thin or light fonts so that they are more visible.  Works on autohinter.
+
*'''Force Slight Hinting''': Force slight hinting even when programs want full hinting. If you use the local.conf I provide (included in infinality-settings fedora package) you will notice nice improvements on @font-face fonts.
+
*'''ChromeOS Style Sharpening''': ChromeOS uses a patch to sharpen the look of fonts. This is now included in the infinality patchset.
+
  
A number of presets are included and can be used by setting the USE_STYLE variable in {{ic|/etc/profile.d/infinality-settings.sh}}.
+
Fontconfig will default to the Xft.dpi variable if it is set. Xft.dpi is usually set by desktop environments (usually to Xorg's DPI setting) or manually in {{ic|~/.Xdefaults}} or {{ic|~/.Xresources}}. Use xrdb to query for the value:
  
{{Note|1=The user bohoomil maintains a very good configuration in his [https://github.com/bohoomil/fontconf github repo] which can be used as an alternative to the steps described below.}}
+
{{hc|<nowiki>$ xrdb -query | grep dpi</nowiki>|
 +
Xft.dpi: 102
 +
}}
  
{{AUR|freetype2-infinality}} can be installed from the [[Arch User Repository|AUR]]. Additionally, if you are using {{pkg|lib32-freetype2}} from [multilib], replace it with {{AUR|lib32-freetype2-infinality}} from the AUR. The AUR also contains a Git version of freetype2 that builds the latest development snapshot of freetype2 with the Infinality patchset: {{AUR|freetype2-git-infinality}}, {{AUR|lib32-freetype2-git-infinality}}.
+
Those still having problems can fall back to manually setting the DPI used by fontconfig:
  
It is recommended to also install {{AUR|fontconfig-infinality}} to enable selection of predefined font substitution styles and antialiasing settings, apart from the rendering settings of the engine itself. After doing so, you can select the font style (win7, winxp, osx, linux, ...) with:
+
...
  # infctl setstyle
+
  <!-- Setup for DPI=96 -->
 +
<match target="pattern">
 +
    <edit name="dpi" mode="assign"><double>102</double></edit>
 +
</match>
 +
...
  
If you set e.g. win7 or osx you need the corresponding fonts installed.
+
=== Calibri, Cambria, Monaco, etc. not rendering properly ===
  
{{Note|Default infinality settings can cause some programs  to display fonts at 72 DPI instead of 96. If you notice a problem open /etc/fonts/infinality/infinality.conf search for the section on DPI and change 72 to 96. This problem can specifically affect conky causing the fonts to appear smaller than they should. Thus not aligning properly with images. }}
+
Some scalable fonts have embedded bitmap versions which are rendered instead, mainly at smaller sizes.  
  
{{Note|''The README for {{AUR|fontconfig-infinality}} says that /etc/fonts/local.conf should either not exist, or have no infinality-related configurations in it. The local.conf is now obsolete and completely replaced by this configuration.''}}
+
Using [[Croscore Fonts]] can improve the rendering in these cases. You can also force using scalable fonts at all sizes by [[#EmbeddedBitmap|#Disabling embedded bitmap]], sacrificing some rendering quality.
  
for more information see this article: http://www.infinality.net/forum/viewtopic.php?f=2&t=77
+
=== Applications overriding hinting ===
  
===Ubuntu===
+
Some applications or desktop environments may override default fontconfig hinting and anti-aliasing settings. This may happen with [[GNOME]] 3, for example while you are using Qt applications like {{pkg|vlc}} or {{pkg|smplayer}}. Use the specific configuration program for the application in such cases. For GNOME, try {{pkg|gnome-tweak-tool}}.
  
Ubuntu adds extra configurations, and occasionally patches to the font rendering libraries.
+
=== Applications not picking up hinting from DE's settings ===
  
Install the patched packages from the [[Arch User Repository|AUR]], the package names are: {{AUR|freetype2-ubuntu}} {{AUR|fontconfig-ubuntu}} {{AUR|cairo-ubuntu}}.
+
For instance, under GNOME it sometimes happens that Firefox applies full hinting even when it's set to "none" in GNOME's settings, which results in sharp and widened fonts. In this case you would have to add hinting settings to your {{ic|fonts.conf}} file:
  
The global configuration will need to be added. See [[#Example fontconfig configurations]] for a starting point.
+
<?xml version='1.0'?>
 +
<!DOCTYPE fontconfig SYSTEM 'fonts.dtd'>
 +
<fontconfig>
 +
  <match target="font">
 +
  <edit mode="assign" name="hinting">
 +
    <bool>false</bool>
 +
  </edit>
 +
  </match>
 +
</fontconfig>
  
===Reverting to unpatched packages===
+
In this example, hinting is set to "grayscale".
  
To restore the unpatched packages, reinstall the originals:
+
=== Incorrect hinting in GTK applications on non-Gnome systems ===
  
# pacman -S --asdeps freetype2 libxft cairo fontconfig
+
{{Accuracy|Mentions GTK relies on fontconfig, then claims that "some" fonts get the hinting "wrong", and ends up refering to Xft (but see e.g [http://doc.opensuse.org/documentation/html/openSUSE_113/opensuse-reference/cha.fontconfig.html#sec.fontconfig.xft]). IOW, unsupported claims and unclear relations}}
  
==Applications without fontconfig support==
+
[[GNOME]] uses the XSETTINGS system to configure font rendering. Without gnome-settings-daemon, GTK applications rely on fontconfig, but some fonts get the hinting wrong causing them to look too bold or too light.
  
Some applications like [[URxvt]] will ignore fontconfig settings. This is very apparent when using the infinality patches which are heavily reliant on proper configuration. You can work around this by using {{ic|~/.Xresources}}, but it is not nearly as flexible as fontconfig. Example (see [[#Fontconfig configuration]] for explanations of the options):
+
A simple solution is using {{AUR|xsettingsd-git}} as a replacement for gnome-settings-daemon to provide the configuration, for example:
  
{{hc|~/.Xresources|<nowiki>
+
{{hc|~/.xsettingsd|
Xft.autohint: 0
+
Xft/Hinting 1
Xft.lcdfilter:  lcddefault
+
Xft/RGBA "rgb"
Xft.hintstyle:  hintfull
+
Xft/HintStyle "hintslight"
Xft.hinting: 1
+
Xft/Antialias 1
Xft.antialias: 1
+
}}
Xft.rgba: rgb
+
</nowiki>}}
+
  
Make sure the settings are loaded properly when X starts with {{ic|xrdb -q}} (see [[Xresources]] for more information).
+
Alternatively you could just write the font configuration as {{ic|Xft.*}} directives in {{ic|~/.Xresources}} without using a settings daemon.
  
==Troubleshooting==
+
=== Font problem in Generated PDFs ===
  
===Distorted fonts===
+
If the following command
{{Note|96 DPI is not a standard. You should use your monitor's actual DPI to get proper font rendering, especially when using subpixel rendering.}}
+
  
If fonts are still unexpectedly large or small, poorly proportioned or simply rendering poorly, fontconfig may be using the incorrect DPI.
+
  fc-match helvetica
 
+
Fontconfig should be able to detect DPI parameters as discovered by the Xorg server. You can check the automatically discovered DPI with {{ic|xdpyinfo}}:
+
 
+
{{hc|<nowiki>$ xdpyinfo | grep dots</nowiki>| resolution:    102x102 dots per inch}}
+
 
+
{{Note|To use the ''xdpyinfo'' command, you must install the package {{pkg|xorg-xdpyinfo}}.}}
+
 
+
If the DPI is detected incorrectly (usually due to an incorrect monitor EDID), you can specify it manually in the Xorg configuration, see [[Xorg#Display Size and DPI]]. This is the recommended solution, but it may not work with buggy drivers.
+
 
+
Fontconfig will default to the Xft.dpi variable if it is set. Xft.dpi is usually set by desktop environments (usually to Xorg's DPI setting) or manually in {{ic|~/.Xdefaults}} or {{ic|~/.Xresources}}. Use xrdb to query for the value:
+
 
+
{{hc|<nowiki>$ xrdb -query | grep dpi</nowiki>|Xft.dpi: 102}}
+
 
+
Those still having problems can fall back to manually setting the DPI used by fontconfig:
+
 
+
...
+
<!-- Setup for DPI=96 -->
+
<match target="pattern">
+
    <edit name="dpi" mode="assign"><double>102</double></edit>
+
</match>
+
...
+
  
===Older GTK and QT applications===
+
produces
  
Modern GTK apps enable Xft by default but this was not the case before version 2.2.  If it is not possible to update these applications, force Xft for old [[GNOME]] applications by adding to {{ic|~/.bashrc}}:
+
helvR12-ISO8859-1.pcf.gz: "Helvetica" "Regular"
  
export GDK_USE_XFT=1
+
then the bitmap font provided by {{Pkg|xorg-fonts-75dpi}} is likely to be embedded into PDFs generated by "Print to File" or "Export" in various applications. The bitmap font was probably installed as a consequence of installing the whole {{Grp|xorg}} group (which is usually NOT recommended). To solve the pixelized font problem, you can uninstall the package. Install {{Pkg|gsfonts}} (Type 1) or {{Pkg|tex-gyre-fonts}} (OpenType) for corresponding free subsitute of Helvetica (and other PostScript/PDF base fonts).
  
For older QT applications:
+
You may also experience similar problem when you open a PDF which requires Helvetica but does not have it embedded for viewing.
  
export QT_XFT=true
+
== See also ==
  
==See also==
+
* [http://www.freedesktop.org/software/fontconfig/fontconfig-user.html Fontconfig Users' Guide]
*[http://www.x.org/X11R6.8.2/doc/fonts.html Fonts in X11R6.8.2] - Official Xorg font information
+
* [http://www.x.org/X11R6.8.2/doc/fonts.html Fonts in X11R6.8.2] - Official Xorg font information
*[http://freetype.sourceforge.net/freetype2/ FreeType 2 Overview]
+
* [http://freetype.sourceforge.net/freetype2/ FreeType 2 overview]
*[https://forums.gentoo.org/viewtopic-t-723341.html Gentoo font-rendering thread]
+
* [https://forums.gentoo.org/viewtopic-t-723341.html Gentoo font-rendering thread]
 +
* [http://www.freetype.org/freetype2/docs/text-rendering-general.html On slight hinting]

Latest revision as of 06:38, 28 April 2016

Fontconfig is a library designed to provide a list of available fonts to applications, and also for configuration for how fonts get rendered: see Wikipedia:Fontconfig. The FreeType library freetype2 renders the fonts, based on this configuration.

Though Fontconfig is the standard in modern Linux, some applications rely on the original method of font selection and display, the X Logical Font Description.

The font rendering packages on Arch Linux includes support for freetype2 with the bytecode interpreter (BCI) enabled. For better font rendering, especially with an LCD monitor, see #Fontconfig configuration and Font configuration/Examples.

Font paths

For fonts to be known to applications, they must be cataloged for easy and quick access.

The font paths initially known to Fontconfig are: /usr/share/fonts/, ~/.local/share/fonts (and ~/.fonts/, now deprecated). Fontconfig will scan these directories recursively. For ease of organization and installation, it is recommended to use these font paths when adding fonts.

To see a list of known Fontconfig fonts:

$ fc-list : file

See man fc-list for more output formats.

Check for Xorg's known font paths by reviewing its log:

$ grep /fonts ~/.local/share/xorg/Xorg.0.log
Tip:
  • You can also check the list of Xorg's known font paths using the command xset q.
  • Use /var/log/Xorg.0.log if Xorg is run with root privileges.

Keep in mind that Xorg does not search recursively through the /usr/share/fonts/ directory like Fontconfig does. To add a path, the full path must be used:

Section "Files"
    FontPath     "/usr/share/fonts/local/"
EndSection

If you want font paths to be set on a per-user basis, you can add and remove font paths from the default by adding the following line(s) to ~/.xinitrc:

xset +fp /usr/share/fonts/local/           # Prepend a custom font path to Xorg's list of known font paths
xset -fp /usr/share/fonts/sucky_fonts/     # Remove the specified font path from Xorg's list of known font paths

To see a list of known Xorg fonts use xlsfonts, from the xorg-xlsfonts package.

Fontconfig configuration

Fontconfig is documented in the fonts-conf man page.

Configuration can be done per-user through $XDG_CONFIG_HOME/fontconfig/fonts.conf, and globally with /etc/fonts/local.conf. The settings in the per-user configuration have precedence over the global configuration. Both these files use the same syntax.

Note: Configuration files and directories: ~/.fonts.conf/, ~/.fonts.conf.d/ and ~/.fontconfig/*.cache-* are deprecated since fontconfig 2.10.1 (upstream commit) and will not be read by default in the future versions of the package. New paths are $XDG_CONFIG_HOME/fontconfig/fonts.conf, $XDG_CONFIG_HOME/fontconfig/conf.d/NN-name.conf and $XDG_CACHE_HOME/fontconfig/*.cache-* respectively. If using the second location, make sure the naming is valid (where NN is a two digit number like 00, 10, or 99).

Fontconfig gathers all its configurations in a central file (/etc/fonts/fonts.conf). This file is replaced during fontconfig updates and should not be edited. Fontconfig-aware applications source this file to know available fonts and how they get rendered. This file is a conglomeration of rules from the global configuration (/etc/fonts/local.conf), the configured presets in /etc/fonts/conf.d/, and the user configuration file ($XDG_CONFIG_HOME/fontconfig/fonts.conf). fc-cache can be used to rebuild fontconfig's configuration, although changes will only be visible in newly launched applications.

Note: For some desktop environments (such as GNOME and KDE) using the Font Control Panel will automatically create or overwrite the user font configuration file. For these desktop environments, it is best to match your already defined font configurations to get the expected behavior.

Fontconfig configuration files use XML format and need these headers:

<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<fontconfig>

  <!-- settings go here -->

</fontconfig>

The configuration examples in this article omit these tags.

Presets

There are presets installed in the directory /etc/fonts/conf.avail. They can be enabled by creating symbolic links to them, both per-user and globally, as described in /etc/fonts/conf.d/README. These presets will override matching settings in their respective configuration files.

For example, to enable sub-pixel RGB rendering globally:

# cd /etc/fonts/conf.d
# ln -s ../conf.avail/10-sub-pixel-rgb.conf

To do the same but instead for a per-user configuration:

$ mkdir $XDG_CONFIG_HOME/fontconfig/conf.d
$ ln -s /etc/fonts/conf.avail/10-sub-pixel-rgb.conf $XDG_CONFIG_HOME/fontconfig/conf.d

Anti-aliasing

Font rasterization converts vector font data to bitmap data so that it can be displayed. The result can appear jagged due to aliasing. anti-aliasing is enabled by default and increases the apparent resolution of font edges. To disable it:

  <match target="font">
    <edit name="antialias" mode="assign">
      <bool>false</bool>
    </edit>
  </match>
Note: Some applications, like GNOME may override default anti-aliasing settings.

Hinting

Font hinting (also known as instructing) is the use of mathematical instructions to adjust the display of an outline font so that it lines up with a rasterized grid, (i.e. the pixel grid of the display). Its intended effect is to make fonts appear more crisp so that they are more readable. Fonts will line up correctly without hinting when displays have around 300 DPI.

Byte-Code Interpreter (BCI)

Using BCI hinting, instructions in TrueType fonts are rendered according to FreeTypes's interpreter. BCI hinting works well with fonts with good hinting instructions. Hinting is enabled by default. To disable it:

  <match target="font">
    <edit name="hinting" mode="assign">
      <bool>false</bool>
    </edit>
  </match>

Autohinter

The autohinter attempts to do automatic hinting and disregards any existing hinting information. Originally it was the default because TrueType2 fonts were patent-protected but now that these patents have expired there is very little reason to use it. It does work better with fonts that have broken or no hinting information but it will be strongly sub-optimal for fonts with good hinting information. Generally common fonts are of the later kind so autohinter will not be useful. Autohinter is disabled by default. To enable it:

  <match target="font">
    <edit name="autohint" mode="assign">
      <bool>true</bool>
    </edit>
  </match>

Hintstyle

Hintstyle is the amount of font reshaping done to line up to the grid. Hinting values are: hintnone, hintslight, hintmedium, and hintfull. hintslight will make the font more fuzzy to line up to the grid but will be better in retaining font shape, while hintfull will be a crisp font that aligns well to the pixel grid but will lose a greater amount of font shape. hintslight is the default setting. To change it:

  <match target="font">
    <edit name="hintstyle" mode="assign">
      <const>hintnone</const>
    </edit>
  </match>
Note: Some applications, like GNOME may override default hinting settings.

Subpixel rendering

Most monitors manufactured today use the Red, Green, Blue (RGB) specification. Fontconfig will need to know your monitor type to be able to display your fonts correctly. Monitors are either: RGB (most common), BGR, V-RGB (vertical), or V-BGR. A monitor test can be found here.

To enable subpixel rendering:

  <match target="font">
    <edit name="rgba" mode="assign">
      <const>rgb</const>
    </edit>
  </match>
Note: Subpixel rendering effectively triples the horizontal (or vertical) resolution for fonts by making use of subpixels. The default autohinter and subpixel rendering are not designed to work together, hence you will want to enable the subpixel autohinter by Infinality, et al. Freetype2 is compiled with the TT_CONFIG_OPTION_SUBPIXEL_HINTING macro. However, it must be enabled by setting the FT2_SUBPIXEL_HINTING environment variable to any value.FS#35274

LCD filter

When using subpixel rendering, you should enable the LCD filter, which is designed to reduce colour fringing. This is described under LCD filtering in the FreeType 2 API reference. Different options are described under FT_LcdFilter, and are illustrated by this LCD filter test page.

The lcddefault filter will work for most users. Other filters are available that can be used in special situations: lcdlight; a lighter filter ideal for fonts that look too bold or fuzzy, lcdlegacy, the original Cairo filter; and lcdnone to disable it entirely.

  <match target="font">
    <edit name="lcdfilter" mode="assign">
      <const>lcddefault</const>
    </edit>
  </match>

Advanced LCD filter specification

If the available, built-in LCD filters are not satisfactory, it is possible to tweak the font rendering very specifically by building a custom freetype2 package and modifying the hardcoded filters. The Arch Build System can be used to build and install packages from source.

Tip: With the Infinality packages, the LCD filter can be modified without rebuilds.

First, refresh the freetype2 PKGBUILD as root:

# abs extra/freetype2

This example uses /var/abs/build as the build directory, substitute it according to your personal ABS setup. Download and extract the freetype2 package as a regular user:

$ cd /var/abs/build
$ cp -r ../extra/freetype2 .
$ cd freetype2
$ makepkg -o

Edit the file src/freetype-VERSION/src/base/ftlcdfil.c and look up the definition of the constant default_filter[5]:

static const FT_Byte  default_filter[5] =
    { 0x10, 0x40, 0x70, 0x40, 0x10 };

This constant defines a low-pass filter applied to the rendered glyph. Modify it as needed. Save the file, build and install the custom package:

$ makepkg -e
# pacman -Rd freetype2
# pacman -U freetype2-VERSION-ARCH.pkg.tar.xz

Reboot or restart X. The lcddefault filter should now render fonts differently.

Disable auto-hinter for bold fonts

The auto-hinter uses sophisticated methods for font rendering, but often makes bold fonts too wide. Fortunately, a solution can be turning off the autohinter for bold fonts while leaving it on for the rest:

...
<match target="font">
    <test name="weight" compare="more">
        <const>medium</const>
    </test>
    <edit name="autohint" mode="assign">
        <bool>false</bool>
    </edit>
</match>
...

Replace or set default fonts

The most reliable way to do this is to add an XML fragment similar to the one below. Using the "binding" attribute will give you better results, for example, in Firefox where you may not want to change properties of font being replaced. This will cause Ubuntu to be used in place of Georgia:

...
 <match target="pattern">
   <test qual="any" name="family"><string>georgia</string></test>
   <edit name="family" mode="assign" binding="same"><string>Ubuntu</string></edit>
 </match>
...

An alternate approach is to set the "preferred" font, but this only works if the original font is not on the system, in which case the one specified will be substituted:

...
<!-- Replace Helvetica with Bitstream Vera Sans Mono -->
<!-- Note, an alias for Helvetica should already exist in default conf files -->
<alias>
    <family>Helvetica</family>
    <prefer><family>Bitstream Vera Sans Mono</family></prefer>
    <default><family>fixed</family></default>
</alias>
...

Example fonts.conf which also specifies a default font for the Japanese locale (ja_JP) and keeps western style fonts for Latin letters.

<?xml version='1.0'?>
<!DOCTYPE fontconfig SYSTEM 'fonts.dtd'>
<fontconfig>

<!-- Default font (no fc-match pattern) -->
 <match>
  <edit mode="prepend" name="family">
   <string>Noto Sans</string>
  </edit>
 </match>

<!-- Default font for the ja_JP locale (no fc-match pattern) -->
 <match>
  <test compare="contains" name="lang">
   <string>ja</string>
  </test>
  <edit mode="prepend" name="family">
   <string>Noto Sans CJK JP</string>
  </edit>
 </match>

<!-- Default sans-serif font -->
 <match target="pattern">
   <test qual="any" name="family"><string>sans-serif</string></test>
   <!--<test qual="any" name="lang"><string>ja</string></test>-->
   <edit name="family" mode="prepend" binding="same"><string>Noto Sans</string>  </edit>
 </match>
 
<!-- Default serif fonts -->
 <match target="pattern">
   <test qual="any" name="family"><string>serif</string></test>
   <edit name="family" mode="prepend" binding="same"><string>Noto Serif</string>  </edit>
   <edit name="family" mode="append" binding="same"><string>IPAPMincho</string>  </edit>
   <edit name="family" mode="append" binding="same"><string>HanaMinA</string>  </edit>
 </match>

<!-- Default monospace fonts -->
 <match target="pattern">
   <test qual="any" name="family"><string>monospace</string></test>
   <edit name="family" mode="prepend" binding="same"><string>Inconsolatazi4</string></edit>
   <edit name="family" mode="append" binding="same"><string>IPAGothic</string></edit>
 </match>

<!-- Fallback fonts preference order -->
 <alias>
  <family>sans-serif</family>
  <prefer>
   <family>Noto Sans</family>
   <family>Open Sans</family>
   <family>Droid Sans</family>
   <family>Ubuntu</family>
   <family>Roboto</family>
   <family>NotoSansCJK</family>
   <family>Source Han Sans JP</family>
   <family>IPAPGothic</family>
   <family>VL PGothic</family>
   <family>Koruri</family>
  </prefer>
 </alias>
 <alias>
  <family>serif</family>
  <prefer>
   <family>Noto Serif</family>
   <family>Droid Serif</family>
   <family>Roboto Slab</family>
   <family>IPAPMincho</family>
  </prefer>
 </alias>
 <alias>
  <family>monospace</family>
  <prefer>
   <family>Inconsolatazi4</family>
   <family>Ubuntu Mono</family>
   <family>Droid Sans Mono</family>
   <family>Roboto Mono</family>
   <family>IPAGothic</family>
  </prefer>
 </alias>

 <dir>~/.fonts</dir>
</fontconfig>

Whitelisting and blacklisting fonts

The element <selectfont> is used in conjunction with the <acceptfont> and <rejectfont> elements to selectively whitelist or blacklist fonts from the resolve list and match requests. The simplest and most typical use case it to reject one font that is needed to be installed, however is getting matched for a generic font query that is causing problems within application user interfaces.

First obtain the Family name as listed in the font itself:

$ fc-scan .fonts/lklug.ttf --format='%{family}\n'
LKLUG

Then use that Family name in a <rejectfont> stanza:

<selectfont>
    <rejectfont>
        <pattern>
            <patelt name="family" >
                <string>LKLUG</string>
            </patelt>
        </pattern>
    </rejectfont>
</selectfont>

Typically when both elements are combined, <rejectfont> is first used on a more general matching glob to reject a large group (such as a whole directory), then <acceptfont> is used after it to whitelist individual fonts out of the larger blacklisted group.

<selectfont>
    <rejectfont>
        <glob>/usr/share/fonts/OTF/*</glob>
    </rejectfont>
    <acceptfont>
        <pattern>
            <patelt name="family" >
                <string>Monaco</string>
            </patelt>
        </pattern>
    </acceptfont>
</selectfont>

Disable bitmap fonts

Bitmap fonts are sometimes used as fallbacks for missing fonts, which may cause text to be rendered pixelated or too large. Use the 70-no-bitmaps.conf preset to disable this behavior.

To disable embedded bitmap for all fonts:
~/.config/fontconfig/conf.d/20-no-embedded.conf
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<fontconfig>
  <match target="font">
    <edit name="embeddedbitmap" mode="assign">
      <bool>false</bool>
    </edit>
  </match>
</fontconfig>

To disable embedded bitmap fonts for a specific font:

<match target="font">
  <test qual="any" name="family">
    <string>Monaco</string>
  </test>
  <edit name="embeddedbitmap"><bool>false</bool></edit>
</match>

Disable scaling of bitmap fonts

To disable scaling of bitmap fonts (which often makes them blurry), remove /etc/fonts/conf.d/10-scale-bitmap-fonts.conf.

Create bold and italic styles for incomplete fonts

FreeType has the ability to automatically create italic and bold styles for fonts that do not have them, but only if explicitly required by the application. Given programs rarely send these requests, this section covers manually forcing generation of missing styles.

Start by editing /usr/share/fonts/fonts.cache-1 as explained below. Store a copy of the modifications on another file, because a font update with fc-cache will overwrite /usr/share/fonts/fonts.cache-1.

Assuming the Dupree font is installed:

"dupree.ttf" 0 "Dupree:style=Regular:slant=0:weight=80:width=100:foundry=unknown:index=0:outline=True:etc...

Duplicate the line, change style=Regular to style=Bold or any other style. Also change slant=0 to slant=100 for italic, weight=80 to weight=200 for bold, or combine them for bold italic:

"dupree.ttf" 0 "Dupree:style=Bold Italic:slant=100:weight=200:width=100:foundry=unknown:index=0:outline=True:etc...

Now add necessary modifications to $XDG_CONFIG_HOME/fontconfig/fonts.conf:

...
<match target="font">
    <test name="family" qual="any">
        <string>Dupree</string>
         <!-- other fonts here .... -->
     </test>
     <test name="weight" compare="more_eq"><int>140</int></test>
     <edit name="embolden" mode="assign"><bool>true</bool></edit>
</match>

<match target="font">
    <test name="family" qual="any">
        <string>Dupree</string>
        <!-- other fonts here .... -->
    </test>
    <test name="slant" compare="more_eq"><int>80</int></test>
    <edit name="matrix" mode="assign">
        <times>
            <name>matrix</name>
                <matrix>
                    <double>1</double><double>0.2</double>
                    <double>0</double><double>1</double>
                </matrix>
        </times>
    </edit>
</match>
...
Tip: Use the value 'embolden' for existing bold fonts in order to make them even bolder.

Change rule overriding

Tango-inaccurate.pngThe factual accuracy of this article or section is disputed.Tango-inaccurate.png

Reason: /etc/fonts/conf.d/50-user.conf will be created again when fontconfig is updated (Discuss in Talk:Font configuration#)

Fontconfig processes files in /etc/fonts/conf.d in numerical order. This enables rules or files to override one another, but often confuses users about what file gets parsed last.

To guarantee that personal settings take precedence over any other rules, change their ordering:

# cd /etc/fonts/conf.d
# mv 50-user.conf 99-user.conf

This change seems however to be unnecessary for the most of the cases, because a user is given enough control by default to set up own font preferences, hinting and antialiasing properties, alias new fonts to generic font families, etc.

Query the current settings

To find out what settings are in effect, use fc-match --verbose. eg.

$ fc-match --verbose Sans
family: "DejaVu Sans"(s)
hintstyle: 3(i)(s)
hinting: True(s)
...

Look up the meaning of the numbers at http://www.freedesktop.org/software/fontconfig/fontconfig-user.html. Eg. 'hintstyle: 3' means 'hintfull'

Applications without fontconfig support

Some applications like URxvt will ignore fontconfig settings. You can work around this by using ~/.Xresources, but it is as flexible as fontconfig. Example (see #Fontconfig configuration for explanations of the options):

~/.Xresources
Xft.autohint: 0
Xft.lcdfilter:  lcddefault
Xft.hintstyle:  hintslight
Xft.hinting: 1
Xft.antialias: 1
Xft.rgba: rgb

Make sure the settings are loaded properly when X starts with xrdb -q (see Xresources for more information).

Troubleshooting

Distorted fonts

Note: 96 DPI is not a standard. You should use your monitor's actual DPI to get proper font rendering, especially when using subpixel rendering.

If fonts are still unexpectedly large or small, poorly proportioned or simply rendering poorly, fontconfig may be using the incorrect DPI.

Fontconfig should be able to detect DPI parameters as discovered by the Xorg server. You can check the automatically discovered DPI with xdpyinfo (provided by the xorg-xdpyinfo package):

$ xdpyinfo | grep dots
  resolution:    102x102 dots per inch

If the DPI is detected incorrectly (usually due to an incorrect monitor EDID), you can specify it manually in the Xorg configuration, see Xorg#Display size and DPI. This is the recommended solution, but it may not work with buggy drivers.

Fontconfig will default to the Xft.dpi variable if it is set. Xft.dpi is usually set by desktop environments (usually to Xorg's DPI setting) or manually in ~/.Xdefaults or ~/.Xresources. Use xrdb to query for the value:

$ xrdb -query | grep dpi
Xft.dpi:	102

Those still having problems can fall back to manually setting the DPI used by fontconfig:

...
<match target="pattern">
   <edit name="dpi" mode="assign"><double>102</double></edit>
</match>
...

Calibri, Cambria, Monaco, etc. not rendering properly

Some scalable fonts have embedded bitmap versions which are rendered instead, mainly at smaller sizes.

Using Croscore Fonts can improve the rendering in these cases. You can also force using scalable fonts at all sizes by #Disabling embedded bitmap, sacrificing some rendering quality.

Applications overriding hinting

Some applications or desktop environments may override default fontconfig hinting and anti-aliasing settings. This may happen with GNOME 3, for example while you are using Qt applications like vlc or smplayer. Use the specific configuration program for the application in such cases. For GNOME, try gnome-tweak-tool.

Applications not picking up hinting from DE's settings

For instance, under GNOME it sometimes happens that Firefox applies full hinting even when it's set to "none" in GNOME's settings, which results in sharp and widened fonts. In this case you would have to add hinting settings to your fonts.conf file:

<?xml version='1.0'?>
<!DOCTYPE fontconfig SYSTEM 'fonts.dtd'>	
<fontconfig>
 <match target="font">
  <edit mode="assign" name="hinting">
   <bool>false</bool>
  </edit>
 </match>
</fontconfig>

In this example, hinting is set to "grayscale".

Incorrect hinting in GTK applications on non-Gnome systems

Tango-inaccurate.pngThe factual accuracy of this article or section is disputed.Tango-inaccurate.png

Reason: Mentions GTK relies on fontconfig, then claims that "some" fonts get the hinting "wrong", and ends up refering to Xft (but see e.g [1]). IOW, unsupported claims and unclear relations (Discuss in Talk:Font configuration#)
GNOME uses the XSETTINGS system to configure font rendering. Without gnome-settings-daemon, GTK applications rely on fontconfig, but some fonts get the hinting wrong causing them to look too bold or too light.

A simple solution is using xsettingsd-gitAUR as a replacement for gnome-settings-daemon to provide the configuration, for example:

~/.xsettingsd
Xft/Hinting 1
Xft/RGBA "rgb"
Xft/HintStyle "hintslight"
Xft/Antialias 1

Alternatively you could just write the font configuration as Xft.* directives in ~/.Xresources without using a settings daemon.

Font problem in Generated PDFs

If the following command

fc-match helvetica

produces

helvR12-ISO8859-1.pcf.gz: "Helvetica" "Regular"

then the bitmap font provided by xorg-fonts-75dpi is likely to be embedded into PDFs generated by "Print to File" or "Export" in various applications. The bitmap font was probably installed as a consequence of installing the whole xorg group (which is usually NOT recommended). To solve the pixelized font problem, you can uninstall the package. Install gsfonts (Type 1) or tex-gyre-fonts (OpenType) for corresponding free subsitute of Helvetica (and other PostScript/PDF base fonts).

You may also experience similar problem when you open a PDF which requires Helvetica but does not have it embedded for viewing.

See also