Various people have been asking how to configure fonts with the new Xft extension, which enables AA fonts, among other things.
This is a short tutorial on how to configure the new Xft extension.

Configuring the Xft extension (including antialiasing)
Danny Tholen ([email protected])

Xft is an interface to the freetype rasterizer written by Keith Packard,
member of the XFree86 Project, Inc. It allows applications to use fonts
from the new X render extension using a unified font naming scheme. In
/etc/X11/XftConfig (or /usr/X11R6/lib/X11/XftConfig) you will find a configuration
file which can be adapted to suit your personal taste. In this document
I will explain the syntax and demonstrate some things you can do with this
file.

Structure
The basic structure revolves around a 'pattern'. A pattern is a set of
name/valuelist pairs, each valuelist contains one or more typed values.
A certain application requests a font, for example:

family: "Arial"
size: 12
encoding: "iso8859-1"

A size 12 arial font in latin-1 encoding. The Xft extension will now
try to patch this pattern to all of the fonts available in the system.
And selecting the one with the best score. Before the matching is done
Xft looks in XftConfig. The requested pattern can here be extended before
use. An example is:

match any family == "Arial" edit antialias = true;

This will enable antialiasing for all fonts of the family Arial.

Also, the X server is queried to list all of its fonts; the XLFD contains
just enough information to match fonts roughly.

Here's a list of attributes used in matching fonts (in priority order,
this may not be up to date anymore!):

foundry        font foundry (string,
like ¨monotype¨)
encoding       font encoding (string, like ¨iso8859-1¨)

spacing        font spacing (integers or proportional
               (0), mono (100), charcell (110))

bold           is the font bold? (boolean)

italic         is the font italic? (boolean)

antialias      is the font antialiased? (boolean)

family         font family (string)

size           font size (double)

style          font style (string, like "Bold Italic")

slant          font slant (roman, italic, oblique)

weight         font weight ( integers or light, medium
               (100),demibold, bold, black)

rasterizer     not yet used (probably "TrueType",
               "Type1", ...)

outline        outlines available? (boolean)

Syntax
dir

adds a directory to the list of places Xft will look for fonts. There
is no particular order implied by the list; Xft treats all fonts about
the same.

include and includeif

cause Xft to load more configuration parameters from the indicated file.
"includeif" doesn't elicit a complaint if the file doesn't exist. If the
file name begins with a '~' character, it refers to a path relative to
the home directory of the user. This is usefull for user-specific configurations.

match edit ;

if a pattern from an application matches the pattern after match, it
is edited with the instructions in edit. The pattern match is done as follows:

match qual FIELD-NAME COMPARE CONSTANT

where qual is either any (matches one specific font) or
all
(matches all fonts). An example:

match all foundry==¨monotype¨

will match (and edit) all fonts belonging to the foundry monotype.

match any family==¨arial¨

will match (and edit) one specific font with the family name arial.

FIELD-NAME is one of the properties found above under
Structure.

COMPARE is <, >, or
==.

CONSTANT is the value of the field-name in the appropiate type (see
under Structure).

You can use multiple matches before you use the edit statement.

edit FIELD-NAME ASSIGN EXPR SEMI

FIELD-NAME can be any of the above (see Structure) plus addionally:

pixelsize        font size in
pixels (integer)
charspace        characer space
(integer)
minspace        
minimal spacing (integer)

rgba             color hinting (string ¨rgb¨ or ¨bgr¨ and
                 vertical hinting ¨vrgb¨ ¨vbgr¨)

xlfd            
x server font (string, type xlsfonts to
                 see a list of your xlfd strings)

file             the font file (string)

core            
use X core fonts? (boolean)

render           use render fonts? (boolean)

index           
I have no idea what this does:)

scalable         is the font scalable (boolean)

scale           
scale the font (integer)

charwidth        character width (integer)

charheight      
character height (integer)

matrix           no idea (not really at least)

ASSIGN can be one of =, += or
=+. With =,
the matching value in the pattern will be replaced by the given expression.
+=
or =+ will prepend/append a new value to the list of values
for the indicated field.

EXPR sets the FIELD-NAME to a value.

SEMI is a semicolon. You can use multiple instructions, separated by
a semicolon.

Examples
And now I´ll try to list a few usefull configurations and explain
them. Note that it is configured for my system, and I may use different
fonts than you, so try to adapt the examples to your own needs.

1) How do I make fonts available to Xft?

List your Type 1 and TrueType font directories with dir. On my
system (Mandrake 7.2) this becomes:

dir "/usr/X11R6/lib/X11/fonts/Type1"
dir "/usr/X11R6/lib/X11/fonts/drakfont"

2) How do I use a user specific XftConfig file?

Put an .xftconfig file in your user directory and add

includeif "~/.xftconfig"

to your standard XftConfig. This will enable a user specific configuration
file, but it will not complain if there is no such file.

3) How do I make aliases for my fonts?

I noted that my KDE console asks for ´mono´ fonts when it
is looking for a fixed font. ´console´ is used when I select
´linux´ in the font menu of the KDE konsole. Therefore, I used
two aliases for fonts which are also named ´fixed´:

match any family == "fixed" edit family =+ "mono";
match any family == "console" edit family =+ "mono";

4) Antialiasing my fonts makes me dizzy!

Although there is a big fuz around AA in X, good fonts actually look
better if they are not antialiased. The antialiasing blurs the fonts by
adding grey pixels to the edges, and this may strain your eyes if you looking
at them for a long time. (Your eyes will try to get the fonts sharper,
which ofcourse is not working because they are blurred;) However, for very
small fonts, antialiasing may increase the readability of the fonts, because
with sharp edges, there are to little pixels available for your mind to
figure out what it means. And for bigger fonts, the edges become very jagged
when not anitaliased, so here you also might want to have aliased fonts.
Ofcourse you can also turn off the antialiasing for specific fonts. In
other operating systems, most truetype fonts are not antialiased between 8 and 12
pixels, while only large Type1 fonts are antialiased.

Use the following in your XftConfig to antialias only fonts of specific sizes:

match
    any size > 8

    any size < 15

edit

    antialias = false;

5) My fixed fonts do not appear or look _very_ wrong in the KDE konsole
or similar programs!

I noted that somehow a lot of fixed font do not tell Xft that they are
fixed, and thus, mono spaced. Therefore only a part of the font is displayed.
We can manually set the spacing for these fonts (this assumes you have
fixed aliased with mono as in question 3):

match
    any family ==
"mono"

edit

    spacing = mono;

6) My Symbol, Webdings, etc. fonts do not show up!

For some reason some (symbol) fonts are not correctly recognized, and Xft will
show your default font, or a font which has the closest match (which is
generally not what you mean at all). For Adobe Symbol and MS-webdings I
did the following to get them working:

match
    any family ==
"webdings"

edit

    antialias = false;

    encoding += "glyphs-fontspecific";

match
    any family ==
"symbol"

edit

    antialias = false;

    encoding += "glyphs-fontspecific";

A usefull way of figuring out these things is to activate debuging
with

export XFT_DEBUG=1024

This will generate a lot of output, especially if you have many fonts,
because it lists the properties and scores of every font available. You
can also use other values. For a nice summary of what happens (requested font, XftConfig substitutions,
x server additions and the finally matched font), you can use XFT_DEBUG=2.

7) Why do my KDE programs start now soooo slow?

Currently, the Xft mechanism in XFree 4.0.3 has to parse the XftConfig file each time a program is started.
And the info of all these fonts has to be read. Newer versions (in CVS) will use a cache and are much faster.
Especially if you have many fonts this can be a problem, and the only real solution is to upgrade to a CVS version of XFree.

8) I have a LCD screen, can I use subpixel hinting instead of normal antialiasing?

Yes you can. Subpixel hinting uses colors instead of grey pixels to do the AA.
I do not have a LCD screen so I do not have any idea of how it looks but you can play with the
rgba setting. Try

match edit rgba=bgr;

or use rgb if you have a different type of monitor. For vertical AA you can try vbgr and vbgr.

9) My fonts still look bad!

If you do not have some good truetype fonts, it is worth to go and look
for them on the internet. Other reasons why your fonts still look bad can
be because of your build of freetype2. Snapshots versions before 2.0.2 were
compiled with an option that had some patent issues. Therefore, the standard
2.0.2 compiles without this option. To fix this, download the freetype2 source rpm
and change in include/freetype/config/ftoption.h line 314:
#undef TT_CONFIG_OPTION_BYTECODE_INTERPRETER
to:
#define TT_CONFIG_OPTION_BYTECODE_INTERPRETER
and rebuild with this modified source. See the freetype2 README file for details.

Adobe Courier looks terrible on my system, so I made an alias so that Lucida console
is displayed instead. If anyone can get it to display nicely I would appreciate it.

10) Other resources on the web...

Here you can find more info about setting up the render and Xft extensions:
SuSE HowTo
Lars Knoll HowTo
My own XftConfig can be found here;
remember that it is specifically adapted to my system, and you will have to edit it.

Feedback is appreciated!