FONT CONFIGURATION

The intent is to make font configurations relatively static, and shared by as many applications as possible. It is hoped that this will lead to more stable font selection when passing names from one application to another. XML was chosen as a configuration file format because it provides a format which is easy for external agents to edit while retaining the correct structure and syntax.

Font configuration is separate from font matching; applications needing to do their own matching can access the available fonts from the library and perform private matching. The intent is to permit applications to pick and choose appropriate functionality from the library instead of forcing them to choose between this library and a private configuration mechanism. The hope is that this will ensure that configuration of fonts for all applications can be centralized in one place. Centralizing font configuration will simplify and regularize font installation and customization.

FONT PROPERTIES

  Property        Type    Description
  --------------------------------------------------------------
  family          String  Font family names
  familylang      String  Languages corresponding to each family
  style           String  Font style. Overrides weight and slant
  stylelang       String  Languages corresponding to each style
  fullname        String  Font full names (often includes style)
  fullnamelang    String  Languages corresponding to each fullname
  slant           Int     Italic, oblique or roman
  weight          Int     Light, medium, demibold, bold or black
  size            Double  Point size
  width           Int     Condensed, normal or expanded
  aspect          Double  Stretches glyphs horizontally before hinting
  pixelsize       Double  Pixel size
  spacing         Int     Proportional, dual-width, monospace or charcell
  foundry         String  Font foundry name
  antialias       Bool    Whether glyphs can be antialiased
  hinting         Bool    Whether the rasterizer should use hinting
  hintstyle       Int     Automatic hinting style
  verticallayout  Bool    Use vertical layout
  autohint        Bool    Use autohinter instead of normal hinter
  globaladvance   Bool    Use font global advance data (deprecated)
  file            String  The filename holding the font
  index           Int     The index of the font within the file
  ftface          FT_Face Use the specified FreeType face object
  rasterizer      String  Which rasterizer is in use (deprecated)
  outline         Bool    Whether the glyphs are outlines
  scalable        Bool    Whether glyphs can be scaled
  color           Bool    Whether any glyphs have color
  scale           Double  Scale factor for point->pixel conversions (deprecated)
  dpi             Double  Target dots per inch
  rgba            Int     unknown, rgb, bgr, vrgb, vbgr,
                          none - subpixel geometry
  lcdfilter       Int     Type of LCD filter
  minspace        Bool    Eliminate leading from line spacing
  charset         CharSet Unicode chars encoded by the font
  lang            String  List of RFC-3066-style languages this
                          font supports
  fontversion     Int     Version number of the font
  capability      String  List of layout capabilities in the font
  fontformat      String  String name of the font format
  embolden        Bool    Rasterizer should synthetically embolden the font
  embeddedbitmap  Bool    Use the embedded bitmap instead of the outline
  decorative      Bool    Whether the style is a decorative variant
  fontfeatures    String  List of the feature tags in OpenType to be enabled
  namelang        String  Language name to be used for the default value of
                          familylang, stylelang, and fullnamelang
  prgname         String  String  Name of the running program
  postscriptname  String  Font family name in PostScript
    

FONT MATCHING

Font matching starts with an application constructed pattern. The desired attributes of the resulting font are collected together in a pattern. Each property of the pattern can contain one or more values; these are listed in priority order; matches earlier in the list are considered "closer" than matches later in the list.

The initial pattern is modified by applying the list of editing instructions specific to patterns found in the configuration; each consists of a match predicate and a set of editing operations. They are executed in the order they appeared in the configuration. Each match causes the associated sequence of editing operations to be applied.

After the pattern has been edited, a sequence of default substitutions are performed to canonicalize the set of available properties; this avoids the need for the lower layers to constantly provide default values for various font properties during rendering.

The canonical font pattern is finally matched against all available fonts. The distance from the pattern to the font is measured for each of several properties: foundry, charset, family, lang, spacing, pixelsize, style, slant, weight, antialias, rasterizer and outline. This list is in priority order -- results of comparing earlier elements of this list weigh more heavily than later elements.

There is one special case to this rule; family names are split into two bindings; strong and weak. Strong family names are given greater precedence in the match than lang elements while weak family names are given lower precedence than lang elements. This permits the document language to drive font selection when any document specified font is unavailable.

The pattern representing that font is augmented to include any properties found in the pattern but not found in the font itself; this permits the application to pass rendering instructions or any other data through the matching system. Finally, the list of editing instructions specific to fonts found in the configuration are applied to the pattern. This modified pattern is returned to the application.

The return value contains sufficient information to locate and rasterize the font, including the file name, pixel size and other rendering data. As none of the information involved pertains to the FreeType library, applications are free to use any rasterization engine or even to take the identified font file and access it directly.

The match/edit sequences in the configuration are performed in two passes because there are essentially two different operations necessary -- the first is to modify how fonts are selected; aliasing families and adding suitable defaults. The second is to modify how the selected fonts are rasterized. Those must apply to the selected font, not the original pattern as false matches will often occur.

FONT NAMES

	<families>-<point sizes>:<name1>=<values1>:<name2>=<values2>...
    

Values in a list are separated with commas. The name needn't include either families or point sizes; they can be elided. In addition, there are symbolic constants that simultaneously indicate both a name and a value. Here are some examples:

  Name                            Meaning
  ----------------------------------------------------------
  Times-12                        12 point Times Roman
  Times-12:bold                   12 point Times Bold
  Courier:italic                  Courier Italic in the default size
  Monospace:matrix=1 .1 0 1       The users preferred monospace font
                                  with artificial obliquing
    

The '\', '-', ':' and ',' characters in family names must be preceded by a '\' character to avoid having them misinterpreted. Similarly, values containing '\', '=', '_', ':' and ',' must also have them preceded by a '\' character. The '\' characters are stripped out of the family name and values as the font name is read.

<FONTCONFIG>

<DIR PREFIX="DEFAULT">

<CACHEDIR PREFIX="DEFAULT">

<INCLUDE IGNORE_MISSING="NO" PREFIX="DEFAULT">

<CONFIG>

<BLANK>

<RESCAN>

<SELECTFONT>

<ACCEPTFONT>

<REJECTFONT>

<GLOB>

<PATTERN>

<PATELT NAME="PROPERTY">

<MATCH TARGET="PATTERN">

<TEST QUAL="ANY" NAME="PROPERTY" TARGET="DEFAULT" COMPARE="EQ">

<EDIT NAME="PROPERTY" MODE="ASSIGN" BINDING="WEAK">

  Mode                    With Match              Without Match
  ---------------------------------------------------------------------
  "assign"                Replace matching value  Replace all values
  "assign_replace"        Replace all values      Replace all values
  "prepend"               Insert before matching  Insert at head of list
  "prepend_first"         Insert at head of list  Insert at head of list
  "append"                Append after matching   Append at end of list
  "append_last"           Append at end of list   Append at end of list
  "delete"                Delete matching value   Delete all values
  "delete_all"            Delete all values       Delete all values
    

<INT>, <DOUBLE>, <STRING>, <BOOL>

<MATRIX>

<RANGE>

<CHARSET>

<LANGSET>

<NAME>

<CONST>

  Constant        Property        Value
  -------------------------------------
  thin            weight          0
  extralight      weight          40
  ultralight      weight          40
  light           weight          50
  demilight       weight          55
  semilight       weight          55
  book            weight          75
  regular         weight          80
  normal          weight          80
  medium          weight          100
  demibold        weight          180
  semibold        weight          180
  bold            weight          200
  extrabold       weight          205
  black           weight          210
  heavy           weight          210
  roman           slant           0
  italic          slant           100
  oblique         slant           110
  ultracondensed  width           50
  extracondensed  width           63
  condensed       width           75
  semicondensed   width           87
  normal          width           100
  semiexpanded    width           113
  expanded        width           125
  extraexpanded   width           150
  ultraexpanded   width           200
  proportional    spacing         0
  dual            spacing         90
  mono            spacing         100
  charcell        spacing         110
  unknown         rgba            0
  rgb             rgba            1
  bgr             rgba            2
  vrgb            rgba            3
  vbgr            rgba            4
  none            rgba            5
  lcdnone         lcdfilter       0
  lcddefault      lcdfilter       1
  lcdlight        lcdfilter       2
  lcdlegacy       lcdfilter       3
  hintnone        hintstyle       0
  hintslight      hintstyle       1
  hintmedium      hintstyle       2
  hintfull        hintstyle       3
    

<OR>, <AND>, <PLUS>, <MINUS>, <TIMES>, <DIVIDE>

<EQ>, <NOT_EQ>, <LESS>, <LESS_EQ>, <MORE>, <MORE_EQ>, <CONTAINS>, <NOT_CONTAINS

<NOT>

<IF>

<ALIAS>

<FAMILY>

<PREFER>, <ACCEPT>, <DEFAULT>

SYSTEM CONFIGURATION FILE

<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<!-- /etc/fonts/fonts.conf file to configure system font access -->
<fontconfig>
<!-- 
	Find fonts in these directories
-->
<dir>/usr/share/fonts</dir>
<dir>/usr/X11R6/lib/X11/fonts</dir>
<!--
	Accept deprecated 'mono' alias, replacing it with 'monospace'
-->
<match target="pattern">
	<test qual="any" name="family"><string>mono</string></test>
	<edit name="family" mode="assign"><string>monospace</string></edit>
</match>
<!--
	Names not including any well known alias are given 'sans-serif'
-->
<match target="pattern">
	<test qual="all" name="family" mode="not_eq"><string>sans-serif</string></test>
	<test qual="all" name="family" mode="not_eq"><string>serif</string></test>
	<test qual="all" name="family" mode="not_eq"><string>monospace</string></test>
	<edit name="family" mode="append_last"><string>sans-serif</string></edit>
</match>
<!--
	Load per-user customization file, but don't complain
	if it doesn't exist
-->
<include ignore_missing="yes" prefix="xdg">fontconfig/fonts.conf</include>
<!--
	Load local customization files, but don't complain
	if there aren't any
-->
<include ignore_missing="yes">conf.d</include>
<include ignore_missing="yes">local.conf</include>
<!--
	Alias well known font names to available TrueType fonts.
	These substitute TrueType faces for similar Type1
	faces to improve screen appearance.
-->
<alias>
	<family>Times</family>
	<prefer><family>Times New Roman</family></prefer>
	<default><family>serif</family></default>
</alias>
<alias>
	<family>Helvetica</family>
	<prefer><family>Arial</family></prefer>
	<default><family>sans</family></default>
</alias>
<alias>
	<family>Courier</family>
	<prefer><family>Courier New</family></prefer>
	<default><family>monospace</family></default>
</alias>
<!--
	Provide required aliases for standard names
	Do these after the users configuration file so that
	any aliases there are used preferentially
-->
<alias>
	<family>serif</family>
	<prefer><family>Times New Roman</family></prefer>
</alias>
<alias>
	<family>sans</family>
	<prefer><family>Arial</family></prefer>
</alias>
<alias>
	<family>monospace</family>
	<prefer><family>Andale Mono</family></prefer>
</alias>
<--
	The example of the requirements of OR operator;
	If the 'family' contains 'Courier New' OR 'Courier'
	add 'monospace' as the alternative
-->
<match target="pattern">
	<test name="family" mode="eq">
		<string>Courier New</string>
	</test>
	<edit name="family" mode="prepend">
		<string>monospace</string>
	</edit>
</match>
<match target="pattern">
	<test name="family" mode="eq">
		<string>Courier</string>
	</test>
	<edit name="family" mode="prepend">
		<string>monospace</string>
	</edit>
</match>
</fontconfig>
    

USER CONFIGURATION FILE

<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<!-- $XDG_CONFIG_HOME/fontconfig/fonts.conf for per-user font configuration -->
<fontconfig>
<!--
	Private font directory
-->
<dir prefix="xdg">fonts</dir>
<!--
	use rgb sub-pixel ordering to improve glyph appearance on
	LCD screens.  Changes affecting rendering, but not matching
	should always use target="font".
-->
<match target="font">
	<edit name="rgba" mode="assign"><const>rgb</const></edit>
</match>
<!--
	use WenQuanYi Zen Hei font when serif is requested for Chinese
-->
<match>
	<!--
		If you don't want to use WenQuanYi Zen Hei font for zh-tw etc,
		you can use zh-cn instead of zh.
		Please note, even if you set zh-cn, it still matches zh.
		if you don't like it, you can use compare="eq"
		instead of compare="contains".
	-->
	<test name="lang" compare="contains">
		<string>zh</string>
	</test>
	<test name="family">
		<string>serif</string>
	</test>
	<edit name="family" mode="prepend">
		<string>WenQuanYi Zen Hei</string>
	</edit>
</match>
<!--
	use VL Gothic font when sans-serif is requested for Japanese
-->
<match>
	<test name="lang" compare="contains">
		<string>ja</string>
	</test>
	<test name="family">
		<string>sans-serif</string>
	</test>
	<edit name="family" mode="prepend">
		<string>VL Gothic</string>
	</edit>
</match>
</fontconfig>