Docs

Appearance

Installing fonts

This section explains how to configure both Xft and the core fonts system to access newly-installed fonts.

Configuring Xft

Xft has no configuration mechanism itself, it relies upon the fontconfig library to configure and customise fonts. That library is not specific to the X Window system, and does not rely on any particular font output mechanism.

Installing fonts in Xft

Fontconfig looks for fonts in a set of well-known directories that include all of X11R7.7's standard font directories (“/usr/share/fonts/X11/*”) by default) as well as a directory called “.fonts/” in the user's home directory. Installing a font for use by Xft applications is as simple as copying a font file into one of these directories. 

$ cp lucbr.ttf ~/.fonts/

Fontconfig will notice the new font at the next opportunity and rebuild its list of fonts. If you want to trigger this update from the command line, you may run the command “fc-cache”. 

$ fc-cache

In order to globally update the system-wide Fontconfig information on Unix systems, you will typically need to run this command as root: 

$ su -c fc-cache

Fine-tuning Xft

Fontconfig's behaviour is controlled by a set of configuration files: a standard configuration file, “/etc/fonts/fonts.conf”, a host-specific configuration file, “/etc/fonts/local.conf”, and a user-specific file called “.fonts.conf” in the user's home directory (this can be overridden with the “FONTCONFIG_FILE” environment variable).

Every Fontconfig configuration file must start with the following boilerplate: 

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

In addition, every Fontconfig configuration file must end with the following line: 

</fontconfig>

The default Fontconfig configuration file includes the directory “˜/.fonts/” in the list of directories searched for font files, and this is where user-specific font files should be installed. In the unlikely case that a new font directory needs to be added, this can be done with the following syntax: 

<dir>/usr/local/share/fonts/</dir>

Another useful option is the ability to disable anti-aliasing (font smoothing) for selected fonts. This can be done with the following syntax: 

<match target="font">
    <test qual="any" name="family">
        <string>Lucida Console</string>
    </test>
    <edit name="antialias" mode="assign">
        <bool>false</bool>
    </edit>
</match>

Anti-aliasing can be disabled for all fonts by the following incantation: 

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

Xft supports sub-pixel rasterisation on LCD displays. X11R7.7 should automatically enable this feature on laptops and when using an LCD monitor connected with a DVI cable; you can check whether this was done by typing 

$ xdpyinfo -ext RENDER | grep sub-pixel

If this doesn't print anything, you will need to configure Render for your particular LCD hardware manually; this is done with the following syntax: 

<match target="font">
    <edit name="rgba" mode="assign">
        <const>rgb</const>
    </edit>
</match>

The string “rgb” within the “<const>”...“</const>” specifies the order of pixel components on your display, and should be changed to match your hardware; it can be one of “rgb” (normal LCD screen), “bgr” (backwards LCD screen), “vrgb” (LCD screen rotated clockwise) or “vbgr” (LCD screen rotated counterclockwise).

Configuring applications

A growing number of applications use Xft in preference to the core fonts system. Some applications, however, need to be explicitly configured to use Xft.

A case in point is XTerm, which can be set to use Xft by using the “-fa” command line option or by setting the “XTerm*faceName” resource: 

XTerm*faceName: Courier
XTerm*faceName: Courier

or 

$ xterm -fa "Courier"

For KDE applications, you should select “Anti-alias fonts” in the “Fonts” panel of KDE's “Control Center”. Note that this option is misnamed: it switches KDE to using Xft but doesn't enable anti-aliasing in case it was disabled by your Xft configuration file.

Gnome applications and Mozilla Firefox will use Xft by default.

Configuring the core X11 fonts system

Installing fonts in the core system is a two step process. First, you need to create a font directory that contains all the relevant font files as well as some index files. You then need to inform the X server of the existence of this new directory by including it in the font path.

Installing bitmap fonts

The X11R7.7 server can use bitmap fonts in both the cross-platform BDF format and the somewhat more efficient binary PCF format. (X11R7.7 also supports the obsolete SNF format.)

Bitmap fonts are normally distributed in the BDF format. Before installing such fonts, it is desirable (but not absolutely necessary) to convert the font files to the PCF format. This is done by using the command “bdftopcf”, e.g. 

$ bdftopcf courier12.bdf

You may then want to compress the resulting PCF font files: 

$ gzip courier12.pcf

After the fonts have been converted, you should copy all the font files that you wish to make available into a arbitrary directory, say “/usr/local/share/fonts/bitmap/”. You should then create the index file “fonts.dir” by running the command “mkfontdir” (please see the mkfontdir(1) manual page for more information): 

$ mkdir /usr/local/share/fonts/bitmap/
$ cp *.pcf.gz /usr/local/share/fonts/bitmap/
$ mkfontdir /usr/local/share/fonts/bitmap/

All that remains is to tell the X server about the existence of the new font directory; see Setting the server's font path below.

Installing scalable fonts

The X11R7.7 server supports scalable fonts in multiple formats, including Type 1, TrueType, and OpenType/CFF. (Earlier versions of X11 also included support for the Speedo and CID scalable font formats, but that is not included in current releases.)

Installing scalable fonts is very similar to installing bitmap fonts: you create a directory with the font files, and run “mkfontdir” to create an index file called “fonts.dir”.

There is, however, a big difference: “mkfontdir” cannot automatically recognise scalable font files. For that reason, you must first index all the font files in a file called “fonts.scale”. While this can be done by hand, it is best done by using the “mkfontscale” utility. 

$ mkfontscale /usr/local/share/fonts/Type1/
$ mkfontdir /usr/local/share/fonts/Type1/

Under some circumstances, it may be necessary to modify the “fonts.scale” file generated by mkfontscale; for more information, please see the mkfontdir(1) and mkfontscale(1) manual pages and Core fonts and internationalisation later in this document.

CID-keyed fonts

The CID-keyed font format was designed by Adobe Systems for fonts with large character sets. The CID-keyed format is obsolete, as it has been superseded by other formats such as OpenType/CFF and support for CID-keyed fonts has been removed from X11.

Setting the server's font path

The list of directories where the server looks for fonts is known as the font path. Informing the server of the existence of a new font directory consists of putting it on the font path.

The font path is an ordered list; if a client's request matches multiple fonts, the first one in the font path is the one that gets used. When matching fonts, the server makes two passes over the font path: during the first pass, it searches for an exact match; during the second, it searches for fonts suitable for scaling.

For best results, scalable fonts should appear in the font path before the bitmap fonts; this way, the server will prefer bitmap fonts to scalable fonts when an exact match is possible, but will avoid scaling bitmap fonts when a scalable font can be used. (The “:unscaled” hack, while still supported, should no longer be necessary in X11R7.7.)

You may check the font path of the running server by typing the command 

$ xset q

Font path catalogue directories

You can specify a special kind of font path directory in the form catalogue:<dir>. The directory specified after the catalogue: prefix will be scanned for symlinks and each symlink destination will be added as a local font path entry.

The symlink can be suffixed by attributes such as 'unscaled', which will be passed through to the underlying font path entry. The only exception is the newly introduced 'pri' attribute, which will be used for ordering the font paths specified by the symlinks.

An example configuration: 

         75dpi:unscaled:pri=20 -> /usr/share/X11/fonts/75dpi
         ghostscript:pri=60 -> /usr/share/fonts/default/ghostscript
         misc:unscaled:pri=10 -> /usr/share/X11/fonts/misc
         type1:pri=40 -> /usr/share/X11/fonts/Type1
         type1:pri=50 -> /usr/share/fonts/default/Type1

This will add /usr/share/X11/fonts/misc as the first font path entry with the attribute unscaled. This is functionally equivalent to setting the following font path: 

         /usr/share/X11/fonts/misc:unscaled,
         /usr/share/X11/fonts/75dpi:unscaled,
         /usr/share/X11/fonts/Type1,
         /usr/share/fonts/default/Type1,
         /usr/share/fonts/default/ghostscript

Temporary modification of the font path

The “xset” utility may be used to modify the font path for the current session. The font path is set with the command xset fp; a new element is added to the front with xset +fp, and added to the end with xset fp+. For example, 

$ xset +fp /usr/local/fonts/Type1
$ xset fp+ /usr/local/fonts/bitmap

Conversely, an element may be removed from the front of the font path with “xset -fp”, and removed from the end with “xset fp-”. You may reset the font path to its default value with “xset fp default”.

For more information, please consult the xset(1) manual page.

Permanent modification of the font path

The default font path (the one used just after server startup or after “xset fp default”) may be specified in the X server's “xorg.conf” file. It is computed by appending all the directories mentioned in the “FontPath” entries of the “Files” section in the order in which they appear. If no font path is specified in a config file, the server uses a default value specified when it was built. 

FontPath "/usr/local/fonts/Type1"
...
FontPath "/usr/local/fonts/bitmap"

For more information, please consult the xorg.conf(5) manual page.

Troubleshooting

If you seem to be unable to use some of the fonts you have installed, the first thing to check is that the “fonts.dir” files are correct and that they are readable by the server (the X server usually runs as root, beware of NFS-mounted font directories). If this doesn't help, it is quite possible that you are trying to use a font in a format that is not supported by your server.

X11R7.7 supports the BDF, PCF, SNF, Type 1, TrueType, and OpenType font formats. However, not all X11R7.7 servers come with all the font backends configured in.

On most platforms, the X11R7.7 servers no longer uses font backends from modules that are loaded at runtime. The built in font support corresponds to the functionality formerly provided by these modules:

  • "bitmap": bitmap fonts (“*.bdf”, “*.pcf” and “*.snf”);

  • "freetype": TrueType fonts (“*.ttf” and “*.ttc”), OpenType fonts (“*.otf” and “*.otc”) and Type 1 fonts (“*.pfa” and “*.pfb”).