Difference between revisions of "Font configuration"

From ArchWiki
Jump to navigation Jump to search
 
Line 1: Line 1:
[[Category:X Server (English)]]
+
[[Category:Fonts]]
[[Category:Fonts (English)]]
+
[[es:Font configuration]]
[[Category:HOWTOs (English)]]
+
[[it:Font configuration]]
 +
[[ja:フォント設定]]
 +
[[ru:Font configuration]]
 +
[[sr:Font configuration]]
 +
[[zh-hans:Font configuration]]
 +
{{Related articles start}}
 +
{{Related|Font configuration/Examples}}
 +
{{Related|Fonts}}
 +
{{Related|Metric-compatible fonts}}
 +
{{Related|Microsoft fonts}}
 +
{{Related|Java Runtime Environment fonts}}
 +
{{Related|X Logical Font Description}}
 +
{{Related articles end}}
  
by PhrakTure
+
[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. The FreeType library renders the fonts, based on this configuration. The ''freetype2'' font rendering packages on Arch Linux include the bytecode interpreter (BCI) enabled for better font rendering especially with an LCD monitor. See [[#Fontconfig configuration]] and [[Font configuration/Examples]].
{{i18n_links_start}}
 
{{i18n_entry|English|Xorg_Font_Configuration}}
 
{{i18n_entry|Русский|Xorg_Font_Configuration_(Русский)}}
 
{{i18n_links_end}}
 
  
==X.org Font Configuration and beautification==
+
Though Fontconfig is used often in modern Unix and Unix-like operating systems, some applications rely on the original method of font selection and display, the [[X Logical Font Description]].
:See the [http://www.x.org/X11R6.8.2/doc/fonts.html Xorg Font Documentation] for full details.
 
:See the [http://freetype.sourceforge.net/freetype2/ FreeType2 Project Page] for details on the freetype X.org Module.
 
:See [http://avi.alkalay.net/linux/docs/font-howto/Font.html Optimal Use of Fonts on Linux] for more information about fonts in Linux.
 
  
===xorg.conf modules===
+
== Font paths ==
*freetype - support for True Type (ttf, ttc), Type1 (pfa, pfb), CID (cid), CFF, Open Type, bitmap (bdf, pcf, snf), Windows (fnt), PFR, and Type42 fonts
 
*type1 - support for Type1 (pfa, pfb) and CID (cid) fonts
 
*speedo - support for Bitstream Speedo (spd) fonts
 
*xtt - support for True Type (ttf, ttc) fonts ('''conflicts with freetype''')
 
*bitmap - support for bitmap (bdf, pcf, snf) fonts
 
  
As you can see, freetype provides everything provided by these other modules already.  In addition, xtt will conflict with freetype.
+
For fonts to be known to applications, they must be cataloged for easy and quick access.
  
==X.org Font Path and /etc/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]].
===xorg.conf font path===
 
The font path described in the xorg.conf file is used for non-Xft fonts. It is worthwhile to specify a majority of fonts here. Applications which do not support Xft will fall back to the X Server's font path.  Personally, I keep a minimum of fonts here - for use with xterm and its ilk.
 
  
===/etc/fonts/ font directories===
+
To see a list of known Fontconfig fonts:
The conf files in /etc/fonts (fonts.conf and local.conf) are used for fontconfig (Xft fonts).  fonts.conf should never be changed, and all changes should be done in local.conf (for system wide changes) or ~/.fonts.conf (for user based changes).
 
Files in /etc/fonts/conf.d are sourced when they start with a number and end with .conf.
 
  
The directories listed in fonts.conf are scanned by fc-cache for use with fontconfig (/usr/share/fonts and ~/.fonts).  All fonts should be placed in these directories. If installing new fonts, running '''fc-cache -fv''' will detect the changes.
+
  $ fc-list : file
  
===Adding new fonts===
+
See {{man|1|fc-list}} for more output formats.
When new fonts are added, they are just files on your system.  A handful of utilities need to be run in order to tell the system that new fonts have been added.
 
/usr/bin/fc-cache
 
This will update the fontconfig cache, assuming the new fonts can be searched by fontconfig (see the above section about /etc/fonts)
 
/usr/bin/mkfontscale
 
/usr/bin/mkfontdir
 
ln -s /usr/X11R6/lib/X11/fonts/encodings/encodings.dir encodings.dir
 
  
These utilities need to be run from inside the directory of the new fonts.  mkfontscale creates a fonts.scale file and mkfontdir creates a fonts.dir file.  These files are used by the X Server, and only need to be done if the fonts are to be served through the FontPath of X.org.  The encodings soft link allows the X Server to use these new fonts under all supported encodings.  After all this, you should have 3 new files in the font dir : fonts.scale, fonts.dir, and encodings.dir.
+
Check for Xorg's known font paths by reviewing its log:
  
===fc-list and xlsfont utilities===
+
  $ grep /fonts ~/.local/share/xorg/Xorg.0.log
These utilities will list, from the command line, all fonts available to each font subsystem. fc-list will list all fontconfig fonts, while xlsfont will list all X fonts. This is useful in combination with grep, i.e. "xlsfonts || grep -i bitstream" to see all bitstream fonts available.
 
  
==Some Font Downloads==
+
{{Tip|
*[http://www.users.bigpond.net.au/gavindi/ Arkpandora TrueType fonts] - Replacements for Arial and Times New Roman.
+
* You can also check the list of [[Xorg]]'s known font paths using the command {{ic|xset q}}.
*[http://themes.freshmeat.net/projects/ppantsfonts/ PPants Angular Font Collection]-Small collection of Angular-styled fonts with a general width of six pixels.  
+
* Use {{ic|/var/log/Xorg.0.log}} if Xorg is run with root privileges.
*[http://www.tobias-jung.de/seekingprofont/ Profont]-Programming font.
+
}}
  
==Goodies==
+
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:
===LCD ClearType Patch===
 
http://bbs.archlinux.org/viewtopic.php?id=33955
 
  
===My fonts look like crap - I've configured everything right but it appears I just have no good fonts.===
+
Section "Files"
I would suggest the following packages from pacman to fix this:
+
    FontPath    "/usr/share/fonts/local/"
  pacman -S ttf-ms-fonts ttf-cheapskate artwiz-fonts
+
  EndSection
  
===I have some apps compiled against Gtk+ 2.2 and under and fonts still look like garbage.===
+
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 {{ic|~/.xinitrc}}:
Yeah, this happens.  Modern GTK apps enable Xft by default, however, before 2.2 this was not the case.  Maybe these apps should be updated to the newer GTK.  If that is not an option, then adding the line '''export GDK_USE_XFT=1''' to a global settings file (/etc/profile, /etc/profile.d/gnome.sh, ~/.xinitrc, etc) will enable Xft for older apps
 
  
===I have a similar problem as above with older Qt based apps.===
+
xset +fp /usr/share/fonts/local/          # Prepend a custom font path to Xorg's list of known font paths
Similar solution, add '''export QT_XFT=true''' somewhere.
+
xset -fp /usr/share/fonts/sucky_fonts/    # Remove the specified font path from Xorg's list of known font paths
  
===Fonts in Gtk apps are too small when using KDE===
+
To see a list of known Xorg fonts use {{ic|xlsfonts}}, from the {{Pkg|xorg-xlsfonts}} package.
Install gtk-qt-engine:
 
pacman -Sy gtk-qt-engine
 
*Change the font size for Gtk apps in `Control Center' -> `Appearance & Themes' -> `GTK Styles and Fonts'.
 
  
===The bytecode interpreter makes my fonts look crappy, and it's compiled in, do I need to recompile?===
+
== Fontconfig configuration ==
Nope, not at all.  Freetype's internal auto-hinting is just shut off.  In some distros, the bytecode interpreter is compiled in and enabled by default.  As a result, the bytecode interpreter overrides the freetype autohinter (which the developers are very proud of).  To force the autohinter to be on, add the following to /etc/fonts/local.conf or ~/.fonts.conf
 
      <!-- Use the Autohinter -->
 
      <match target="pattern">
 
        <edit name=<code>"autohint" mode=</code>"assign">
 
            <bool>true</bool>
 
        </edit>
 
      </match>
 
  
Or change to the /etc/fonts/conf.d directory, and link the 10-autohint.conf file from the conf.avail directory into the conf.d directory.  The following commands should work (the second command must be run with superuser privileges).
+
Fontconfig is documented in the {{man|5|fonts-conf}} man page.
cd /etc/fonts/conf.d
 
ln -s ../conf.avail/10-autohint.conf
 
  
Question: I don't understand this... The bytecode interpreter is supposed to beat the autohinter by a long shot so i don't see why anyone would want the autohinter. Reply: It appears that the bytecode interpreter in the 2.3 branch is quite poor. There's a forum post about it here: http://bbs.archlinux.org/viewtopic.php?id=29976 The above code made fonts much better for me. Although they didn't come into affect until after I rebooted - no idea why.
+
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 {{Pkg|fontconfig}} 2.10.1 ([http://cgit.freedesktop.org/fontconfig/commit/?id&#61;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}}).}}
  
===Autohint works great but not for my bold fonts. How can I turn it off only for bold fonts?===
+
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; simply restarting such applications is sufficient to load the new configuration. 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.
Autohinter can give you nice fonts but often makes fonts too wide. This is especially annoying with bold fonts. Fortunately you can turn off autohinter for bold fonts while leaving it on for the rest.
 
*First turn on autohinter (see above) and add the following to ~/[[.fonts.conf]]
 
      <match target="font">
 
          <test name=<code>"weight" compare=</code>"more">
 
              <const>medium</const>
 
          </test>
 
          <edit name=<code>"autohint" mode=</code>"assign">
 
              <bool>false</bool>
 
          </edit>
 
      </match>
 
  
===I have a TFT/DFP/LCD display uses a DVI cable and fonts look odd and fuzzy===
+
{{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. Also ensure that the desktop [[locale]] settings or ''Regional Settings'' are supported by the configured fonts, if not the font configuration could be overidden.}}
This is due to rendering differences between CRTs and non-CRTs.  To fix this problem, you need to enable sub-pixel rendering.  Edit the ~/[[.fonts.conf]] file.  Add the following section to enable this feature. NOTE that this will do nothing but a minor amount of extra work on CRTs and does not improve the display quality.  Possible values for the '''const''' section include - rgb, bgr, vrgb, bgrv, and none.
 
  
< !-- Enable sub-pixel rendering -->
+
Fontconfig configuration files use [[Wikipedia:XML|XML]] format and need these headers:
<match target="font" >
+
 
  <edit mode="assign" name="rgba" >
+
{{bc|<nowiki>
  <const>rgb</const>
+
<?xml version="1.0"?>
  </edit>
+
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
</match>
+
<fontconfig>
 +
 
 +
  <!-- settings go here -->
 +
 
 +
</fontconfig>
 +
</nowiki>}}
 +
 
 +
The configuration examples in this article omit these tags.
 +
 
 +
=== 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.
 +
 
 +
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 ===
 +
 
 +
[[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]]. The technique known as [[Wikipedia:Anti-aliasing|anti-aliasing]] can be used to increase the apparent resolution of font edges. Anti-aliasing is '''enabled''' by default. To disable it:
 +
 
 +
{{bc|<nowiki>
 +
  <match target="font">
 +
    <edit name="antialias" mode="assign">
 +
      <bool>false</bool>
 +
    </edit>
 +
  </match>
 +
</nowiki>}}
 +
 
 +
{{Note|Some applications, like [[GNOME]] may [[#Troubleshooting|override default anti-aliasing settings]].}}
 +
 
 +
=== Hinting ===
 +
 
 +
[[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]].
 +
 
 +
==== 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>
 +
  <match target="font">
 +
    <edit name="hinting" mode="assign">
 +
      <bool>false</bool>
 +
    </edit>
 +
  </match>
 +
</nowiki>}}
 +
 
 +
{{Note|1=You can switch BCI implementations by editing {{ic|/etc/profile.d/freetype2.sh}} which includes a brief documentation. Most popular values are {{ic|1=truetype:interpreter-version=35}} (classic mode, emulates Windows 98; 2.6 default), {{ic|1=truetype:interpreter-version=38}} ("Infinality" subpixel mode), {{ic|1=truetype:interpreter-version=40}} (minimal subpixel mode; 2.7 default). If you prefer classic Windows ClearType style you can use {{ic|1=truetype:interpreter-version=36}}. Subpixel rendering should use a subpixel BCI. For details, see [https://www.freetype.org/freetype2/docs/reference/ft2-properties.html#tt_interpreter_version_xxx].}}
  
===I don't want my fonts Antialiased under a certain point size.===
+
==== Autohinter ====
A sample of this is in the /etc/fonts/local.conf file.  It is commented, just like the subpixel rendering section.  Changes, if anything, should be made to the '''compare="less_eq"''' portion, and the '''<int>12</int>''' portion - these are the comparison operation and point size to compare, respectively.
 
      <!-- Disable anti-aliasing for fonts that are size <=12 -->
 
      <match target="pattern">
 
        <test qual="any" name="size" compare="less_eq">
 
            <int>12</int>
 
        </test>
 
        <edit name="antialias" mode="assign"><bool>false</bool></edit>
 
      </match>
 
  
===I'm using MS TrueType fonts (verdana) and want to enable anti-aliasing but only for bigger fonts that look too jagged.===
+
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:
      <?xml version="1.0"?>
 
      <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
 
      <fontconfig>
 
  
      <match target="font" >
+
{{bc|<nowiki>
      <test compare<code>"more" name</code>"size" qual="any" >
+
  <match target="font">
      <double>12</double>
+
    <edit name="autohint" mode="assign">
      </test>
 
      <edit mode<code>"assign" name</code>"antialias" >
 
 
       <bool>true</bool>
 
       <bool>true</bool>
      </edit>
+
    </edit>
      </match>
+
  </match>
 +
</nowiki>}}
 +
 
 +
==== Hintstyle ====
  
      <match target="font" >
+
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 (see [https://www.freetype.org/freetype2/docs/text-rendering-general.html]), 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}} implicitly uses the autohinter in a vertical-only mode in favor of font-native information for non-CFF (''.otf'') fonts.
      <test compare<code>"more" name</code>"pixelsize" qual="any" >
+
 
       <double>17</double>
+
{{ic|hintslight}} is the default setting. To change it:
      </test>
+
 
      <edit mode<code>"assign" name</code>"antialias" >
+
{{bc|<nowiki>
       <bool>true</bool>
+
  <match target="font">
      </edit>
+
    <edit name="hintstyle" mode="assign">
      </match>
+
       <const>hintnone</const>
      </fontconfig>
+
    </edit>
 +
  </match>
 +
</nowiki>}}
 +
 
 +
{{Note|Some applications, like [[GNOME]] may [[#Troubleshooting|override default hinting settings.]]}}
 +
 
 +
=== Pixel alignment ===
 +
 
 +
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].
 +
 
 +
{{bc|<nowiki>
 +
  <match target="font">
 +
    <edit name="rgba" mode="assign">
 +
       <const>rgb</const>
 +
    </edit>
 +
  </match>
 +
</nowiki>}}
 +
 
 +
{{Note|Without subpixel rendering (see below), freetype will only care about the alignment (vertical or horizontal) of the subpixels. There is no difference between '''RGB''' and '''BGR''', for example.}}
 +
 
 +
=== Subpixel rendering ===
  
===I want to add more fonts.===
+
[[wikipedia:Subpixel_rendering|Subpixel rendering]] is a technique to improve sharpness of font rendering by effectively tripling the horizontal (or vertical) resolution through the use of subpixels. On Windows machines, this technique is called "ClearType".  
Save your fonts in a directory and add it to '''~/[[.fonts.conf]]'''
 
  
    < !-- Additional font directories -->
+
FreeType implements its own LCD-optimized rendering called [http://lists.gnu.org/archive/html/freetype-commit/2017-03/msg00012.html Harmony]. With this FreeType LCD rendering technology, the resulting output does not require additional LCD filtering, unlike Microsoft's patented Cleartype subpixel rendering where an LCD filter is recommended. See section below on how to enable LCD filter and its benefits.
    <dir>/path/to/dir</dir>
 
  
===I want my font sizes to match my DPI settings===
+
Cleartype subpixel rendering is covered by Microsoft patents and '''disabled''' by default on Arch Linux. To enable it, you have to re-compile {{pkg|freetype2}} and define the {{ic|FT_CONFIG_OPTION_SUBPIXEL_RENDERING}} macro, or use e.g. the AUR package {{AUR|freetype2-cleartype}}.
Edit '''~/[[.fonts.conf]]''' with the following.  This setting should match your dpi settings in either [[xorg.conf]] or your startx command. Use xdpyinfo to get your current dpi setting.  Most people recommend/use a value of 96 or 100. Changing and setting the dpi of X is beyond the scope of this document (see [[Xorg#Display_Size.2FDPI|Xorg DisplaySize/DPI]]).
 
      <!-- Setup for DPI = 100 -->
 
      <match target="pattern">
 
        <edit name=<code>"dpi" mode=</code>"assign"><double>100</double></edit>
 
      </match>
 
  
===I don't like font <enter name here> and want to use <another font name> instead===
+
==== LCD filter ====
  
The most reliable way to do this is to add an XML fragment similar to the one below to /etc/fonts/local.conf. This will cause Nimbus Sans to be used in place of Helvetica:
+
When using Cleartype subpixel rendering, you should enable the LCD filter, which is designed to reduce colour fringing.  This is described under [https://www.freetype.org/freetype2/docs/reference/ft2-lcd_rendering.html LCD filtering] in the FreeType 2 API reference.  Different options are described under [https://www.freetype.org/freetype2/docs/reference/ft2-lcd_rendering.html#ft_lcdfilter FT_LcdFilter], and are illustrated by this [http://www.spasche.net/files/lcdfiltering/ LCD filter test] page.
  
 +
The {{ic|lcddefault}} filter will work for most users. Other filters are available that can be used in special situations: {{ic|lcdlight}}; a lighter filter ideal for fonts that look too bold or fuzzy, {{ic|lcdlegacy}}, the original Cairo filter; and {{ic|lcdnone}} to disable it entirely.
  
   <match target="pattern">
+
{{bc|<nowiki>
      <test name="family"><string>Helvetica</string></test>
+
   <match target="font">
      <edit name="family" mode="assign">
+
    <edit name="lcdfilter" mode="assign">
          <string>Nimbus Sans</string>
+
      <const>lcddefault</const>
      </edit>
+
    </edit>
 
   </match>
 
   </match>
 +
</nowiki>}}
  
 +
==== Advanced LCD filter specification ====
  
An alternate approach is to set the "preferred" font, but '''this only works if the original font is not on your system''', in which case the one you specify will be substituted:
+
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. This requires installation of the {{Pkg|asp}} package.
  
 +
Checkout the {{Pkg|freetype2}} PKGBUILD and download/extract the build files:
  
      <!-- Replace Helvetica with Bitstream Vera Sans Mono -->
+
$ asp checkout freetype2
      <!-- Note, an alias for Helvetica should already exist in default local.conf files -->
+
$ cd freetype2/trunk
      <alias>
+
$ makepkg -o
        <family>Helvetica </family>
+
 
        <prefer><family>Bitstream Vera Sans Mono</family></prefer>
+
Enable subpixel rendering by editing the file {{ic|src/freetype-VERSION/include/freetype/config/ftoption.h}} and uncommenting the {{ic|FT_CONFIG_OPTION_SUBPIXEL_RENDERING}} macro.
        <default><family>fixed</family></default>
+
 
      </alias>
+
Then, edit the file {{ic|src/freetype-VERSION/src/base/ftlcdfil.c}} and look up the definition of the constant {{ic|default_filter[5]}}:
  
===I have tons of disgusting pixel fonts that I don't want===
+
static const FT_Byte  default_filter[5] =
The only two fonts that you absolutely have to have in order to start X are 'cursor' and 'fixed', both of which are in the fonts/misc directory. If you want to get rid of all the pixel fonts besides these two, you can delete all the files in the misc directory besides cursor.pcf.gz and all the fonts that are similar to either 9x18.pcf.gz or 9x18-ISO8859-1.pcf.gz. When I deleted all the fonts besides those from the misc directory, I had about 337 files still in it, so if you have a lot less than that you should probably put them back before restarting X.
+
    { 0x10, 0x40, 0x70, 0x40, 0x10 };
  
===Something or someone disabled all my non-scalable (bitmap) fonts, I want them back===
+
This constant defines a low-pass filter applied to the rendered glyph. Modify it as needed. (reference: [https://lists.nongnu.org/archive/html/freetype/2006-09/msg00069.html freetype list discussion]) Save the file, build and install the custom package:
By default, fontconfig 2.3.2-4 and higher will disable the use of bitmap fonts. This setting is managed in /etc/fonts/conf.d/10-no-bitmaps.conf, or in higher versions, /etc/fonts/conf.d/10-bitmaps.conf.
 
To enable bitmap fonts and keep them enabled after upgrades of fontconfig, place a symlink from yes-bitmaps.conf to 10-bitmaps.conf, overwriting the symlink to no-bitmaps.conf.
 
  
===Fake bold & italic styles for incomplete fonts===
+
$ makepkg -e
Freetype already has had this capability for some time, but only if app asks so (which never happens) - it's not going to add Bold or Italic style for those regular-only fonts anyway. To make up them, you need to edit ''/usr/share/fonts/fonts.cache-1'' manually (and keep your modification somewhere because font update (fc-cache) overrides it). Assume you have a font Dupree:
+
# pacman -Rd freetype2
      "dupree.ttf" 0 "Dupree:style=Regular:slant=0:weight=80:width=100:foundry=unknown:index=0:outline=True:....
+
# pacman -U freetype2-VERSION-ARCH.pkg.tar.xz
Duplicate the line, change ''style=Regular'' to ''style=Bold'' or other styles you want. Also change ''slant=0'' to ''slant=100'' for italic, ''weight=80'' to ''weight=200'' for bold (combine for bold italic):
 
      "dupree.ttf" 0 "Dupree:style=Bold Italic:slant=100:weight=200:width=100:foundry=unknown:index=0:outline=True:....
 
Now add necessary modification to ''~/.fonts.conf'':
 
      <match target="font">
 
        <test name="family" qual="any">
 
            <string>Dupree</string>
 
            &lt;!-- other fonts here .... --&gt;
 
        </test>
 
        <test compare="more_eq" name="weight"><int>140</int></test>
 
        <edit mode="assign" name="embolden"><bool>true</bool></edit>
 
      </match>
 
      <match target="font">
 
        <test name="family" qual="any">
 
            <string>Dupree</string>
 
            &lt;!-- other fonts here .... --&gt;
 
        </test>
 
        <test compare="more_eq" name="slant"><int>80</int></test>
 
        <edit mode="assign" name="matrix">
 
            <times>
 
              <name>matrix</name>
 
              <matrix>
 
                  <double>1</double><double>0.2</double>
 
                  <double>0</double><double>1</double>
 
              </matrix>
 
            </times>
 
        </edit>
 
      </match>
 
(Note that you can use embolden for bold fonts as well - to make them even bolder)
 
  
===A web developer's fonts/local.conf taken from arch forums===
+
Reboot or restart X. The lcddefault filter should now render fonts differently.
Backup your current config and give this one a try.  I noticed it especially improved the Georgia font.
 
<pre>
 
<?xml version="1.0"?>
 
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
 
  
<!-- the cathectic LCD tweaks, from linuxquestions.org,
+
=== Custom settings for certain fonts or font styles ===
http://www.linuxquestions.org/questions/showthread.php?postid=1361098#post1361098 -->
 
  
<fontconfig>
+
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:
  
<!-- Disable sub-pixel rendering.
+
...
  X detects it anyway, and if you set this as well, it just looks really horrible  -->
+
  <match target="font">
<match target="font" >
+
    <test name="weight" compare="more">
<edit mode="assign" name="rgba" >
+
        <const>medium</const>
<const>none</const>
+
    </test>
</edit>
+
    <edit name="autohint" mode="assign">
 +
        <bool>false</bool>
 +
    </edit>
 
  </match>
 
  </match>
  <match target="font" >
+
...
<edit mode="assign" name="hinting">
+
 
<bool>true</bool>
+
Some fonts may not look good with BCI hinting. It can be disabled for just those fonts:
</edit>
+
 
 +
...
 +
  <match target="font">
 +
    <test name="family" qual="any">
 +
        <string>My Font</string>
 +
    </test>
 +
    <edit name="hinting" mode="assign">
 +
        <bool>false</bool>
 +
    </edit>
 
  </match>
 
  </match>
  <match target="font" >
+
...
<edit mode="assign" name="hintstyle">
+
 
<const>hintfull</const>
+
=== Replace or set default fonts ===
</edit>
+
 
 +
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>
 +
...
 +
  <match target="pattern">
 +
  <test qual="any" name="family"><string>georgia</string></test>
 +
  <edit name="family" mode="assign" binding="same"><string>Ubuntu</string></edit>
 
  </match>
 
  </match>
 +
...
 +
</nowiki>}}
 +
 +
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:
 +
 +
{{bc|<nowiki>
 +
...
 +
<!-- 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>
 +
...
 +
</nowiki>}}
 +
 +
=== Whitelisting and blacklisting fonts ===
 +
 +
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.
 +
 +
First obtain the Family name as listed in the font itself:
 +
 +
{{hc|1=$ fc-scan .fonts/lklug.ttf --format='%{family}\n'|2=
 +
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.
  
<!-- The first part of the 'magic.'
+
To disable embedded bitmap for all fonts:
This makes the fonts start to look nice,
+
 
but some of the shapes will be distorted, so hinting is needed still -->
+
{{hc|~/.config/fontconfig/conf.d/20-no-embedded.conf|<nowiki>
<match target="font" >
+
<?xml version="1.0"?>
<edit mode="assign" name="antialias">
+
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<bool>true</bool>
+
<fontconfig>
</edit>
+
  <match target="font">
</match>
+
    <edit name="embeddedbitmap" mode="assign">
 +
      <bool>false</bool>
 +
    </edit>
 +
  </match>
 +
</fontconfig>
 +
</nowiki>}}
 +
 
 +
To disable embedded bitmap fonts for a specific font:
  
<!-- Autohinter is not turned on automatically.
 
Only disable this if you have recompiled Freetype with the bytecode interpreter,
 
which is run automatically.<br />  -->
 
<match target="pattern" >
 
<edit mode="assign" name="autohint">
 
<bool>true</bool>
 
</edit>
 
</match>
 
 
  <match target="font">
 
  <match target="font">
<test name="weight" compare="more">
+
  <test qual="any" name="family">
<const>medium</const>
+
    <string>Monaco</string>
</test>
+
  </test>
<edit name="autohint" mode="assign">
+
  <edit name="embeddedbitmap">
<bool>false</bool>
+
    <bool>false</bool>
</edit>
+
  </edit>
 
  </match>
 
  </match>
<!-- Helvetica is a non true type font, and will look bad.
+
 
  This replaces it with whatever is the default sans-serif font -->
+
=== Disable scaling of bitmap fonts ===
<match target="pattern" name="family" >
+
 
<test name="family" qual="any" >
+
To disable scaling of bitmap fonts (which often makes them blurry), remove {{ic|/etc/fonts/conf.d/10-scale-bitmap-fonts.conf}}.
<string>Helvetica</string>
+
 
</test>
+
=== Create bold and italic styles for incomplete fonts ===
<edit mode="assign" name="family" >
+
 
<string>sans-serif</string>
+
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.
</edit>
+
 
 +
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}}.
 +
 
 +
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 {{ic|1=style=Regular}} to {{ic|1=style=Bold}} or any other style. Also change {{ic|1=slant=0}} to {{ic|1=slant=100}} for italic, {{ic|1=weight=80}} to {{ic|1=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 {{ic|$XDG_CONFIG_HOME/fontconfig/fonts.conf}}:
 +
 
 +
{{bc|<nowiki>
 +
...
 +
<match target="font">
 +
    <test name="family" qual="any">
 +
        <string>Dupree</string>
 +
        &lt;!-- other fonts here .... --&gt;
 +
    </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>
 +
        &lt;!-- other fonts here .... --&gt;
 +
    </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>
 +
...
 +
</nowiki>}}
 +
 
 +
{{Tip| Use the value {{ic|embolden}} for existing bold fonts in order to make them even bolder.}}
 +
 
 +
=== Change rule overriding ===
 +
 
 +
{{Accuracy|{{ic|/etc/fonts/conf.d/50-user.conf}} will be created again when {{Pkg|fontconfig}} is updated.|Talk:Font configuration#Change Rule Overriding}}
 +
 
 +
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:
 +
 
 +
# 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 {{ic|fc-match --verbose}}. eg.
 +
 
 +
{{hc|$ fc-match --verbose Sans|
 +
family: "DejaVu Sans"(s)
 +
hintstyle: 3(i)(s)
 +
hinting: True(s)
 +
...
 +
}}
 +
 
 +
Look up the meaning of the numbers at {{man|5|fonts-conf}} Eg. 'hintstyle: 3' means 'hintfull'
 +
 
 +
== Applications without fontconfig support ==
 +
 
 +
Some applications like [[URxvt]] will ignore fontconfig settings. You can work around this by using {{ic|~/.Xresources}}, but it is not as flexible as fontconfig. Example (see [[#Fontconfig configuration]] for explanations of the options):
 +
 
 +
{{hc|~/.Xresources|<nowiki>
 +
Xft.autohint: 0
 +
Xft.lcdfilter: lcddefault
 +
Xft.hintstyle: hintslight
 +
Xft.hinting: 1
 +
Xft.antialias: 1
 +
Xft.rgba: rgb
 +
</nowiki>}}
 +
 
 +
Make sure the settings are loaded properly when X starts with {{ic|xrdb -q}} (see [[X resources]] 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 {{ic|xdpyinfo}} (provided by the {{pkg|xorg-xdpyinfo}} package):
 +
 
 +
{{hc|$ xdpyinfo {{!}} grep dots|
 +
  resolution:    102x102 dots per inch
 +
}}
 +
 
 +
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.
 +
 
 +
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|$ xrdb -query {{!}} grep dpi|
 +
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>
 
  </match>
  <dir>~/.fonts</dir>
+
  ...
</fontconfig>
+
 
</pre>
+
=== Calibri, Cambria, Monaco, etc. not rendering properly ===
WikiMigration--[[User:Dlanor|dlanor]] 14:05, 23 Jul 2005 (EDT)
+
 
 +
Some scalable fonts have embedded bitmap versions which are rendered instead, mainly at smaller sizes. Using [[Metric-compatible fonts]] as replacements can improve the rendering in these cases.
 +
 
 +
You can also force using scalable fonts at all sizes by [[#Disable bitmap fonts|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 {{pkg|vlc}} or {{pkg|smplayer}}. Use the specific configuration program for the application in such cases. For GNOME, try {{Pkg|gnome-tweaks}}.
 +
 
 +
=== Applications not picking up hinting from GNOME 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 {{ic|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 ===
 +
In some desktop environments, especially outside [[GNOME]] and [[Plasma]], some GTK applications could not read font configuration properly. In order to solve this issue, install {{Pkg|xsettingsd}} or {{AUR|xsettingsd-git}} and execute it at every system startup. See also [https://github.com/derat/xsettingsd/wiki/Settings xsettingsd wiki] for more information. It can be configured with the following common configuration:
 +
 
 +
{{hc|~/.xsettingsd|
 +
Xft/Hinting 1
 +
Xft/HintStyle "hintslight"
 +
Xft/Antialias 1
 +
Xft/RGBA "rgb"
 +
}}
 +
 
 +
If that is not working in some other applications, you could install {{Pkg|xorg-xrdb}} and provide the following configuration:
 +
 
 +
{{hc|~/.Xresources|
 +
Xft.hinting: 1
 +
Xft.hintstyle: hintslight
 +
Xft.antialias: 1
 +
Xft.rgba: rgb
 +
}}
 +
 
 +
Then you can execute the script {{ic|xrdb -merge ~/.Xresources}} at every system startup to apply the options. See also [[X resources]] and [[#Applications without fontconfig support]].
 +
 
 +
=== Helvetica 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 {{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).
 +
 
 +
You may also experience similar problem when you open a PDF which requires Helvetica but does not have it embedded for viewing.
 +
 
 +
=== FreeType breaking bitmap fonts ===
 +
 
 +
Some users are reporting problems ({{Bug|52502}}) with bitmap fonts having changed names after upgrading {{Pkg|freetype2}} to version 2.7.1, creating havok in terminal emulators and several other programs such as {{AUR|dwm}} or {{Pkg|dmenu}} by falling back to another (different) font. This was caused by the changes to the PCF font family format, which is described in their ''release notes'' [https://sourceforge.net/projects/freetype/files/freetype2/2.7.1/]. Users transitioning from the old format might want to create a ''font alias'' to remedy the problems, like the solution which is described in [https://forum.manjaro.org/t/terminus-font-name-fix-after-freetype2-update-to-2-7-1-1/15530], given here too:
 +
 
 +
Assume we want to create an alias for {{Pkg|terminus-font}}, which was renamed from {{ic|Terminus}} to {{ic|xos4 Terminus}} in the previously described {{Pkg|freetype2}} update:
 +
* Create a configuration file in {{ic|/etc/fonts/conf.avail/}} for the ''font alias'':
 +
{{hc|/etc/fonts/conf.avail/33-TerminusPCFFont.conf|<nowiki>
 +
<?xml version="1.0"?>
 +
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
 +
<fontconfig>
 +
    <alias>
 +
        <family>Terminus</family>
 +
        <prefer><family>xos4 Terminus</family></prefer>
 +
        <default><family>fixed</family></default>
 +
    </alias>
 +
</fontconfig>
 +
</nowiki>}}
 +
* Create a symbolic link towards it in the {{ic|/etc/fonts/conf.d}} directory. In our example we would link as follows: {{ic|ln -s /etc/fonts/conf.avail/33-TerminusPCFFont.conf /etc/fonts/conf.d}} to make the change permanent.
 +
Everything should now work as it did before the update, the ''font alias'' should not be in effect, but make sure to either reload {{ic|.Xresources}} or restart the display server first so the affected programs can use the alias.
 +
 
 +
=== Debugging FreeType fonts ===
 +
 
 +
{{Pkg|freetype2-demos}} provides tools for debugging FreeType font configuration. {{ic|ftview}} is a GUI in which you can tweak font rendering settings with a live preview. For example:
 +
 
 +
$ ftview -e unic -d 1024x768x24 -r 96 10 /usr/share/fonts/noto/NotoSans-Regular.ttf
 +
 
 +
== See also ==
 +
 
 +
* [[Wikipedia:Fontconfig]]
 +
* [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]
 +
* [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]
 +
* [https://www.freetype.org/freetype2/docs/reference/index.html#controlling-freetype-modules FreeType 2 API Reference: Controlling FreeType Modules]

Latest revision as of 12:42, 27 October 2019

Fontconfig is a library designed to provide a list of available fonts to applications, and also for configuration for how fonts get rendered. The FreeType library renders the fonts, based on this configuration. The freetype2 font rendering packages on Arch Linux include the bytecode interpreter (BCI) enabled for better font rendering especially with an LCD monitor. See #Fontconfig configuration and Font configuration/Examples.

Though Fontconfig is used often in modern Unix and Unix-like operating systems, some applications rely on the original method of font selection and display, the X Logical Font Description.

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 fc-list(1) 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(5) 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; simply restarting such applications is sufficient to load the new configuration. 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. Also ensure that the desktop locale settings or Regional Settings are supported by the configured fonts, if not the font configuration could be overidden.

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. The technique known as anti-aliasing can be used to increase the apparent resolution of font edges. Anti-aliasing is enabled by default. 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>
Note: You can switch BCI implementations by editing /etc/profile.d/freetype2.sh which includes a brief documentation. Most popular values are truetype:interpreter-version=35 (classic mode, emulates Windows 98; 2.6 default), truetype:interpreter-version=38 ("Infinality" subpixel mode), truetype:interpreter-version=40 (minimal subpixel mode; 2.7 default). If you prefer classic Windows ClearType style you can use truetype:interpreter-version=36. Subpixel rendering should use a subpixel BCI. For details, see [1].

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 (see [2]), while hintfull will be a crisp font that aligns well to the pixel grid but will lose a greater amount of font shape. hintslight implicitly uses the autohinter in a vertical-only mode in favor of font-native information for non-CFF (.otf) fonts.

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.

Pixel alignment

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.

  <match target="font">
    <edit name="rgba" mode="assign">
      <const>rgb</const>
    </edit>
  </match>
Note: Without subpixel rendering (see below), freetype will only care about the alignment (vertical or horizontal) of the subpixels. There is no difference between RGB and BGR, for example.

Subpixel rendering

Subpixel rendering is a technique to improve sharpness of font rendering by effectively tripling the horizontal (or vertical) resolution through the use of subpixels. On Windows machines, this technique is called "ClearType".

FreeType implements its own LCD-optimized rendering called Harmony. With this FreeType LCD rendering technology, the resulting output does not require additional LCD filtering, unlike Microsoft's patented Cleartype subpixel rendering where an LCD filter is recommended. See section below on how to enable LCD filter and its benefits.

Cleartype subpixel rendering is covered by Microsoft patents and disabled by default on Arch Linux. To enable it, you have to re-compile freetype2 and define the FT_CONFIG_OPTION_SUBPIXEL_RENDERING macro, or use e.g. the AUR package freetype2-cleartypeAUR.

LCD filter

When using Cleartype 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. This requires installation of the asp package.

Checkout the freetype2 PKGBUILD and download/extract the build files:

$ asp checkout freetype2
$ cd freetype2/trunk
$ makepkg -o

Enable subpixel rendering by editing the file src/freetype-VERSION/include/freetype/config/ftoption.h and uncommenting the FT_CONFIG_OPTION_SUBPIXEL_RENDERING macro.

Then, 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. (reference: freetype list discussion) 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.

Custom settings for certain fonts or font styles

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

Some fonts may not look good with BCI hinting. It can be disabled for just those fonts:

...
<match target="font">
    <test name="family" qual="any">
        <string>My Font</string>
    </test>
    <edit name="hinting" 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>
...

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#Change Rule Overriding)

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 fonts-conf(5) 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 not 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 X resources 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 Metric-compatible fonts as replacements 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-tweaks.

Applications not picking up hinting from GNOME 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

In some desktop environments, especially outside GNOME and Plasma, some GTK applications could not read font configuration properly. In order to solve this issue, install xsettingsd or xsettingsd-gitAUR and execute it at every system startup. See also xsettingsd wiki for more information. It can be configured with the following common configuration:

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

If that is not working in some other applications, you could install xorg-xrdb and provide the following configuration:

~/.Xresources
Xft.hinting: 1
Xft.hintstyle: hintslight
Xft.antialias: 1
Xft.rgba: rgb 

Then you can execute the script xrdb -merge ~/.Xresources at every system startup to apply the options. See also X resources and #Applications without fontconfig support.

Helvetica 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.

FreeType breaking bitmap fonts

Some users are reporting problems (FS#52502) with bitmap fonts having changed names after upgrading freetype2 to version 2.7.1, creating havok in terminal emulators and several other programs such as dwmAUR or dmenu by falling back to another (different) font. This was caused by the changes to the PCF font family format, which is described in their release notes [3]. Users transitioning from the old format might want to create a font alias to remedy the problems, like the solution which is described in [4], given here too:

Assume we want to create an alias for terminus-font, which was renamed from Terminus to xos4 Terminus in the previously described freetype2 update:

  • Create a configuration file in /etc/fonts/conf.avail/ for the font alias:
/etc/fonts/conf.avail/33-TerminusPCFFont.conf
<?xml version="1.0"?>
 <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
 <fontconfig>
     <alias>
         <family>Terminus</family>
         <prefer><family>xos4 Terminus</family></prefer>
         <default><family>fixed</family></default>
     </alias>
 </fontconfig>
  • Create a symbolic link towards it in the /etc/fonts/conf.d directory. In our example we would link as follows: ln -s /etc/fonts/conf.avail/33-TerminusPCFFont.conf /etc/fonts/conf.d to make the change permanent.

Everything should now work as it did before the update, the font alias should not be in effect, but make sure to either reload .Xresources or restart the display server first so the affected programs can use the alias.

Debugging FreeType fonts

freetype2-demos provides tools for debugging FreeType font configuration. ftview is a GUI in which you can tweak font rendering settings with a live preview. For example:

$ ftview -e unic -d 1024x768x24 -r 96 10 /usr/share/fonts/noto/NotoSans-Regular.ttf

See also