C.7 Font Specification Options

By default, Emacs displays text in X using a twelve point monospace font. You can specify a different font using the command line option ‘-fn font’ (or ‘--font’, which is an alias for ‘-fn’).

‘-fn font’

‘--font=font’

Use font as the default font.

When passing a font specification to Emacs on the command line, you may need to “quote” it, by enclosing it in quotation marks, if it contains characters that the shell treats specially (e.g. spaces). Here is an example:

     emacs -fn "DejaVu Sans Mono-12"

You can also specify the font using your X resources file (usually a file named .Xdefaults or .Xresources in your home directory), by adding a line like this:

     emacs.font: font

You must restart X, or use the xrdb command, for the X resources file to take effect. See Resources. When specifying a font in your X resources file, you should not quote it.

Emacs recognizes two types of fonts: client-side fonts, which are provided by the Xft and Fontconfig libraries, and server-side fonts, which are provided by the X server itself. Most client-side fonts support advanced font features such as antialiasing and subpixel hinting, while server-side fonts do not.

There are four different ways to express a “font name”. The first format consists of Fontconfig patterns. Fontconfig patterns match only client-side fonts provided by Xft and Fontconfig, and have the following form:

     fontname[-fontsize][:name1=values1][:name2=values2]...

Within this format, any of the elements in braces may be omitted. Here, fontname is the “family name” of the font, such as ‘Monospace’ or ‘DejaVu Serif’; fontsize is the “point size” of the font (one “printer's point” is about 1/72 of an inch); and the ‘name=values’ entries specify settings such as the slant and weight of the font. Each values may be a single value, or a list of values separated by commas. In addition, some property values are valid with only one kind of property name, in which case the ‘name=’ part may be omitted.

Here is a list of common font properties:

‘slant’

One of ‘italic’, ‘oblique’ or ‘roman’.

‘weight’

One of ‘light’, ‘medium’, ‘demibold’, ‘bold’ or ‘black’.

‘style’

Some fonts define special styles which are a combination of slant and weight. For instance, the font ‘Dejavu Sans’ defines the style ‘book’. This property, if specified, overrides the slant and weight properties.

‘width’

One of ‘condensed’, ‘normal’, or ‘expanded’.

‘spacing’

One of ‘monospace’, ‘proportional’, ‘dual-width’, or ‘charcell’.

Here are some examples of Fontconfig patterns:

     Monospace
     Monospace-12
     Monospace-12:bold
     DejaVu Sans Mono:bold:italic
     Monospace-12:weight=bold:slant=italic

See the Fontconfig manual for a more detailed description of Fontconfig patterns. This manual is located in the file fontconfig-user.html, which is distributed with Fontconfig. It is also available online at http://fontconfig.org/fontconfig-user.html. In particular, the manual describes additional font properties that influence how the font is hinted, antialiased, or scaled.

The second way to specify a font is to use a GTK font description. Like Fontconfig patterns, GTK font descriptions match only client-side fonts provided by Xft and Fontconfig. They have the syntax

     fontname [properties] [fontsize]

where fontname is the family name, properties is a list of property values separated by spaces, and fontsize is the point size. The properties that you may specify are as follows:

‘style’

One of ‘roman’, ‘italic’ or ‘oblique’. If omitted, the ‘roman’ style is used.

‘weight’

One of ‘medium’, ‘ultra-light’, ‘light’, ‘semi-bold’, or ‘bold’. If omitted, ‘medium’ weight is used.

Here are some examples of GTK font descriptions:

     Monospace 12
     Monospace Bold Italic 12

The third way to specify a font is to use an XLFD (X Logical Font Description), which is the traditional method for specifying fonts under X. Each XLFD consists of fourteen words or numbers, separated by dashes, like this:

     -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1

A wildcard character (‘*’) in an XLFD matches any sequence of characters (including none), and ‘?’ matches any single character. However, matching is implementation-dependent, and can be inaccurate when wildcards match dashes in a long name. For reliable results, supply all 14 dashes and use wildcards only within a field. Case is insignificant in an XLFD. The syntax for an XLFD is as follows:

     -maker-family-weight-slant-widthtype-style...
     ...-pixels-height-horiz-vert-spacing-width-registry-encoding

The entries have the following meanings:

maker

The name of the font manufacturer.

family

The name of the font family (e.g. ‘courier’).

weight

The font weight—normally either ‘bold’, ‘medium’ or ‘light’. Some font names support other values.

slant

The font slant—normally ‘r’ (roman), ‘i’ (italic), ‘o’ (oblique), ‘ri’ (reverse italic), or ‘ot’ (other). Some font names support other values.

widthtype

The font width—normally ‘condensed’, ‘extended’, ‘semicondensed’ or ‘normal’ (some font names support other values).

style

An optional additional style name. Usually it is empty—most long font names have two hyphens in a row at this point.

pixels

The font height, in pixels.

height

The font height on the screen, measured in tenths of a printer's point. This is the point size of the font, times ten. For a given vertical resolution, height and pixels are proportional; therefore, it is common to specify just one of them and use ‘*’ for the other.

horiz

The horizontal resolution, in pixels per inch, of the screen for which the font is intended.

vert

The vertical resolution, in pixels per inch, of the screen for which the font is intended. Normally the resolution of the fonts on your system is the right value for your screen; therefore, you normally specify ‘*’ for this and horiz.

spacing

This is ‘m’ (monospace), ‘p’ (proportional) or ‘c’ (character cell).

width

The average character width, in pixels, multiplied by ten.

registry

encoding

The X font character set that the font depicts. (X font character sets are not the same as Emacs character sets, but they are similar.) You can use the xfontsel program to check which choices you have. Normally you should use ‘iso8859’ for registry and ‘1’ for encoding.

Some fonts have shorter nicknames, which you can use instead of a normal font specification. For instance,

     -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1

is equivalent to ‘6x13’. This is the fourth and final method of specifying a font.

You will probably want to use a fixed-width default font—that is, a font in which all characters have the same width. Here's how to use the fc-list command to list all fixed-width Xft and Fontconfig fonts available on your system:

     fc-list :spacing=mono
     fc-list :spacing=charcell

For server-side X fonts, any font with ‘m’ or ‘c’ in the spacing field of the XLFD is a fixed-width font. Here's how to use the xlsfonts program to list all the fixed-width fonts available on your system:

     xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+"
     xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*'
     xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*'

To see what a particular font looks like, use the xfd command. For example:

     xfd -fn 6x13

displays the entire font ‘6x13’.

While running Emacs, you can set the font of a specific kind of text (see Faces), or of a particular frame (see Frame Parameters).