doc/fontconfig-user.txt

   1                                fonts-conf
   2
   3 Name
   4
   5    fonts.conf -- Font configuration files
   6
   7 Synopsis
   8
   9    /etc/fonts/fonts.conf
  10    /etc/fonts/fonts.dtd
  11    /etc/fonts/conf.d
  12    $XDG_CONFIG_HOME/fontconfig/conf.d
  13    $XDG_CONFIG_HOME/fontconfig/fonts.conf
  14    ~/.fonts.conf.d
  15    ~/.fonts.conf
  16
  17 Description
  18
  19    Fontconfig is a library designed to provide system-wide font
  20    configuration, customization and application access.
  21
  22 Functional Overview
  23
  24    Fontconfig contains two essential modules, the configuration
  25    module which builds an internal configuration from XML files
  26    and the matching module which accepts font patterns and returns
  27    the nearest matching font.
  28
  29 Font Configuration
  30
  31    The configuration module consists of the FcConfig datatype,
  32    libexpat and FcConfigParse which walks over an XML tree and
  33    amends a configuration with data found within. From an external
  34    perspective, configuration of the library consists of
  35    generating a valid XML tree and feeding that to FcConfigParse.
  36    The only other mechanism provided to applications for changing
  37    the running configuration is to add fonts and directories to
  38    the list of application-provided font files.
  39
  40    The intent is to make font configurations relatively static,
  41    and shared by as many applications as possible. It is hoped
  42    that this will lead to more stable font selection when passing
  43    names from one application to another. XML was chosen as a
  44    configuration file format because it provides a format which is
  45    easy for external agents to edit while retaining the correct
  46    structure and syntax.
  47
  48    Font configuration is separate from font matching; applications
  49    needing to do their own matching can access the available fonts
  50    from the library and perform private matching. The intent is to
  51    permit applications to pick and choose appropriate
  52    functionality from the library instead of forcing them to
  53    choose between this library and a private configuration
  54    mechanism. The hope is that this will ensure that configuration
  55    of fonts for all applications can be centralized in one place.
  56    Centralizing font configuration will simplify and regularize
  57    font installation and customization.
  58
  59 Font Properties
  60
  61    While font patterns may contain essentially any properties,
  62    there are some well known properties with associated types.
  63    Fontconfig uses some of these properties for font matching and
  64    font completion. Others are provided as a convenience for the
  65    applications' rendering mechanism.
  66   Property        Type    Description
  67   --------------------------------------------------------------
  68   family          String  Font family names
  69   familylang      String  Languages corresponding to each family
  70   style           String  Font style. Overrides weight and slant
  71   stylelang       String  Languages corresponding to each style
  72   fullname        String  Font full names (often includes style)
  73   fullnamelang    String  Languages corresponding to each fullname
  74   slant           Int     Italic, oblique or roman
  75   weight          Int     Light, medium, demibold, bold or black
  76   size            Double  Point size
  77   width           Int     Condensed, normal or expanded
  78   aspect          Double  Stretches glyphs horizontally before hinting
  79   pixelsize       Double  Pixel size
  80   spacing         Int     Proportional, dual-width, monospace or charcel
  81 l
  82   foundry         String  Font foundry name
  83   antialias       Bool    Whether glyphs can be antialiased
  84   hinting         Bool    Whether the rasterizer should use hinting
  85   hintstyle       Int     Automatic hinting style
  86   verticallayout  Bool    Use vertical layout
  87   autohint        Bool    Use autohinter instead of normal hinter
  88   globaladvance   Bool    Use font global advance data (deprecated)
  89   file            String  The filename holding the font
  90   index           Int     The index of the font within the file
  91   ftface          FT_Face Use the specified FreeType face object
  92   rasterizer      String  Which rasterizer is in use (deprecated)
  93   outline         Bool    Whether the glyphs are outlines
  94   scalable        Bool    Whether glyphs can be scaled
  95   color           Bool    Whether any glyphs have color
  96   scale           Double  Scale factor for point->pixel conversions (dep
  97 recated)
  98   dpi             Double  Target dots per inch
  99   rgba            Int     unknown, rgb, bgr, vrgb, vbgr,
 100                           none - subpixel geometry
 101   lcdfilter       Int     Type of LCD filter
 102   minspace        Bool    Eliminate leading from line spacing
 103   charset         CharSet Unicode chars encoded by the font
 104   lang            String  List of RFC-3066-style languages this
 105                           font supports
 106   fontversion     Int     Version number of the font
 107   capability      String  List of layout capabilities in the font
 108   fontformat      String  String name of the font format
 109   embolden        Bool    Rasterizer should synthetically embolden the f
 110 ont
 111   embeddedbitmap  Bool    Use the embedded bitmap instead of the outline
 112   decorative      Bool    Whether the style is a decorative variant
 113   fontfeatures    String  List of the feature tags in OpenType to be ena
 114 bled
 115   namelang        String  Language name to be used for the default value
 116  of
 117                           familylang, stylelang, and fullnamelang
 118   prgname         String  String  Name of the running program
 119   postscriptname  String  Font family name in PostScript
 120
 121 Font Matching
 122
 123    Fontconfig performs matching by measuring the distance from a
 124    provided pattern to all of the available fonts in the system.
 125    The closest matching font is selected. This ensures that a font
 126    will always be returned, but doesn't ensure that it is anything
 127    like the requested pattern.
 128
 129    Font matching starts with an application constructed pattern.
 130    The desired attributes of the resulting font are collected
 131    together in a pattern. Each property of the pattern can contain
 132    one or more values; these are listed in priority order; matches
 133    earlier in the list are considered "closer" than matches later
 134    in the list.
 135
 136    The initial pattern is modified by applying the list of editing
 137    instructions specific to patterns found in the configuration;
 138    each consists of a match predicate and a set of editing
 139    operations. They are executed in the order they appeared in the
 140    configuration. Each match causes the associated sequence of
 141    editing operations to be applied.
 142
 143    After the pattern has been edited, a sequence of default
 144    substitutions are performed to canonicalize the set of
 145    available properties; this avoids the need for the lower layers
 146    to constantly provide default values for various font
 147    properties during rendering.
 148
 149    The canonical font pattern is finally matched against all
 150    available fonts. The distance from the pattern to the font is
 151    measured for each of several properties: foundry, charset,
 152    family, lang, spacing, pixelsize, style, slant, weight,
 153    antialias, rasterizer and outline. This list is in priority
 154    order -- results of comparing earlier elements of this list
 155    weigh more heavily than later elements.
 156
 157    There is one special case to this rule; family names are split
 158    into two bindings; strong and weak. Strong family names are
 159    given greater precedence in the match than lang elements while
 160    weak family names are given lower precedence than lang
 161    elements. This permits the document language to drive font
 162    selection when any document specified font is unavailable.
 163
 164    The pattern representing that font is augmented to include any
 165    properties found in the pattern but not found in the font
 166    itself; this permits the application to pass rendering
 167    instructions or any other data through the matching system.
 168    Finally, the list of editing instructions specific to fonts
 169    found in the configuration are applied to the pattern. This
 170    modified pattern is returned to the application.
 171
 172    The return value contains sufficient information to locate and
 173    rasterize the font, including the file name, pixel size and
 174    other rendering data. As none of the information involved
 175    pertains to the FreeType library, applications are free to use
 176    any rasterization engine or even to take the identified font
 177    file and access it directly.
 178
 179    The match/edit sequences in the configuration are performed in
 180    two passes because there are essentially two different
 181    operations necessary -- the first is to modify how fonts are
 182    selected; aliasing families and adding suitable defaults. The
 183    second is to modify how the selected fonts are rasterized.
 184    Those must apply to the selected font, not the original pattern
 185    as false matches will often occur.
 186
 187 Font Names
 188
 189    Fontconfig provides a textual representation for patterns that
 190    the library can both accept and generate. The representation is
 191    in three parts, first a list of family names, second a list of
 192    point sizes and finally a list of additional properties:
 193         <families>-<point sizes>:<name1>=<values1>:<name2>=<values2>...
 194
 195    Values in a list are separated with commas. The name needn't
 196    include either families or point sizes; they can be elided. In
 197    addition, there are symbolic constants that simultaneously
 198    indicate both a name and a value. Here are some examples:
 199   Name                            Meaning
 200   ----------------------------------------------------------
 201   Times-12                        12 point Times Roman
 202   Times-12:bold                   12 point Times Bold
 203   Courier:italic                  Courier Italic in the default size
 204   Monospace:matrix=1 .1 0 1       The users preferred monospace font
 205                                   with artificial obliquing
 206
 207    The '\', '-', ':' and ',' characters in family names must be
 208    preceded by a '\' character to avoid having them
 209    misinterpreted. Similarly, values containing '\', '=', '_', ':'
 210    and ',' must also have them preceded by a '\' character. The
 211    '\' characters are stripped out of the family name and values
 212    as the font name is read.
 213
 214 Debugging Applications
 215
 216    To help diagnose font and applications problems, fontconfig is
 217    built with a large amount of internal debugging left enabled.
 218    It is controlled by means of the FC_DEBUG environment variable.
 219    The value of this variable is interpreted as a number, and each
 220    bit within that value controls different debugging messages.
 221   Name         Value    Meaning
 222   ---------------------------------------------------------
 223   MATCH            1    Brief information about font matching
 224   MATCHV           2    Extensive font matching information
 225   EDIT             4    Monitor match/test/edit execution
 226   FONTSET          8    Track loading of font information at startup
 227   CACHE           16    Watch cache files being written
 228   CACHEV          32    Extensive cache file writing information
 229   PARSE           64    (no longer in use)
 230   SCAN           128    Watch font files being scanned to build caches
 231   SCANV          256    Verbose font file scanning information
 232   MEMORY         512    Monitor fontconfig memory usage
 233   CONFIG        1024    Monitor which config files are loaded
 234   LANGSET       2048    Dump char sets used to construct lang values
 235   MATCH2        4096    Display font-matching transformation in patterns
 236
 237    Add the value of the desired debug levels together and assign
 238    that (in base 10) to the FC_DEBUG environment variable before
 239    running the application. Output from these statements is sent
 240    to stdout.
 241
 242 Lang Tags
 243
 244    Each font in the database contains a list of languages it
 245    supports. This is computed by comparing the Unicode coverage of
 246    the font with the orthography of each language. Languages are
 247    tagged using an RFC-3066 compatible naming and occur in two
 248    parts -- the ISO 639 language tag followed a hyphen and then by
 249    the ISO 3166 country code. The hyphen and country code may be
 250    elided.
 251
 252    Fontconfig has orthographies for several languages built into
 253    the library. No provision has been made for adding new ones
 254    aside from rebuilding the library. It currently supports 122 of
 255    the 139 languages named in ISO 639-1, 141 of the languages with
 256    two-letter codes from ISO 639-2 and another 30 languages with
 257    only three-letter codes. Languages with both two and three
 258    letter codes are provided with only the two letter code.
 259
 260    For languages used in multiple territories with radically
 261    different character sets, fontconfig includes per-territory
 262    orthographies. This includes Azerbaijani, Kurdish, Pashto,
 263    Tigrinya and Chinese.
 264
 265 Configuration File Format
 266
 267    Configuration files for fontconfig are stored in XML format;
 268    this format makes external configuration tools easier to write
 269    and ensures that they will generate syntactically correct
 270    configuration files. As XML files are plain text, they can also
 271    be manipulated by the expert user using a text editor.
 272
 273    The fontconfig document type definition resides in the external
 274    entity "fonts.dtd"; this is normally stored in the default font
 275    configuration directory (/etc/fonts). Each configuration file
 276    should contain the following structure:
 277         <?xml version="1.0"?>
 278         <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
 279         <fontconfig>
 280         ...
 281         </fontconfig>
 282
 283 <fontconfig>
 284
 285    This is the top level element for a font configuration and can
 286    contain <dir>, <cachedir>, <include>, <match> and <alias>
 287    elements in any order.
 288
 289 <dir prefix="default">
 290
 291    This element contains a directory name which will be scanned
 292    for font files to include in the set of available fonts. If
 293    'prefix' is set to "xdg", the value in the XDG_DATA_HOME
 294    environment variable will be added as the path prefix. please
 295    see XDG Base Directory Specification for more details.
 296
 297 <cachedir prefix="default">
 298
 299    This element contains a directory name that is supposed to be
 300    stored or read the cache of font information. If multiple
 301    elements are specified in the configuration file, the directory
 302    that can be accessed first in the list will be used to store
 303    the cache files. If it starts with '~', it refers to a
 304    directory in the users home directory. If 'prefix' is set to
 305    "xdg", the value in the XDG_CACHE_HOME environment variable
 306    will be added as the path prefix. please see XDG Base Directory
 307    Specification for more details. The default directory is
 308    ``$XDG_CACHE_HOME/fontconfig'' and it contains the cache files
 309    named ``<hash value>-<architecture>.cache-<version>'', where
 310    <version> is the font configuration file version number
 311    (currently 5).
 312
 313 <include ignore_missing="no" prefix="default">
 314
 315    This element contains the name of an additional configuration
 316    file or directory. If a directory, every file within that
 317    directory starting with an ASCII digit (U+0030 - U+0039) and
 318    ending with the string ``.conf'' will be processed in sorted
 319    order. When the XML datatype is traversed by FcConfigParse, the
 320    contents of the file(s) will also be incorporated into the
 321    configuration by passing the filename(s) to
 322    FcConfigLoadAndParse. If 'ignore_missing' is set to "yes"
 323    instead of the default "no", a missing file or directory will
 324    elicit no warning message from the library. If 'prefix' is set
 325    to "xdg", the value in the XDG_CONFIG_HOME environment variable
 326    will be added as the path prefix. please see XDG Base Directory
 327    Specification for more details.
 328
 329 <config>
 330
 331    This element provides a place to consolidate additional
 332    configuration information. <config> can contain <blank> and
 333    <rescan> elements in any order.
 334
 335 <blank>
 336
 337    Fonts often include "broken" glyphs which appear in the
 338    encoding but are drawn as blanks on the screen. Within the
 339    <blank> element, place each Unicode characters which is
 340    supposed to be blank in an <int> element. Characters outside of
 341    this set which are drawn as blank will be elided from the set
 342    of characters supported by the font.
 343
 344 <rescan>
 345
 346    The <rescan> element holds an <int> element which indicates the
 347    default interval between automatic checks for font
 348    configuration changes. Fontconfig will validate all of the
 349    configuration files and directories and automatically rebuild
 350    the internal datastructures when this interval passes.
 351
 352 <selectfont>
 353
 354    This element is used to black/white list fonts from being
 355    listed or matched against. It holds acceptfont and rejectfont
 356    elements.
 357
 358 <acceptfont>
 359
 360    Fonts matched by an acceptfont element are "whitelisted"; such
 361    fonts are explicitly included in the set of fonts used to
 362    resolve list and match requests; including them in this list
 363    protects them from being "blacklisted" by a rejectfont element.
 364    Acceptfont elements include glob and pattern elements which are
 365    used to match fonts.
 366
 367 <rejectfont>
 368
 369    Fonts matched by an rejectfont element are "blacklisted"; such
 370    fonts are excluded from the set of fonts used to resolve list
 371    and match requests as if they didn't exist in the system.
 372    Rejectfont elements include glob and pattern elements which are
 373    used to match fonts.
 374
 375 <glob>
 376
 377    Glob elements hold shell-style filename matching patterns
 378    (including ? and *) which match fonts based on their complete
 379    pathnames. This can be used to exclude a set of directories
 380    (/usr/share/fonts/uglyfont*), or particular font file types
 381    (*.pcf.gz), but the latter mechanism relies rather heavily on
 382    filenaming conventions which can't be relied upon. Note that
 383    globs only apply to directories, not to individual fonts.
 384
 385 <pattern>
 386
 387    Pattern elements perform list-style matching on incoming fonts;
 388    that is, they hold a list of elements and associated values. If
 389    all of those elements have a matching value, then the pattern
 390    matches the font. This can be used to select fonts based on
 391    attributes of the font (scalable, bold, etc), which is a more
 392    reliable mechanism than using file extensions. Pattern elements
 393    include patelt elements.
 394
 395 <patelt name="property">
 396
 397    Patelt elements hold a single pattern element and list of
 398    values. They must have a 'name' attribute which indicates the
 399    pattern element name. Patelt elements include int, double,
 400    string, matrix, bool, charset and const elements.
 401
 402 <match target="pattern">
 403
 404    This element holds first a (possibly empty) list of <test>
 405    elements and then a (possibly empty) list of <edit> elements.
 406    Patterns which match all of the tests are subjected to all the
 407    edits. If 'target' is set to "font" instead of the default
 408    "pattern", then this element applies to the font name resulting
 409    from a match rather than a font pattern to be matched. If
 410    'target' is set to "scan", then this element applies when the
 411    font is scanned to build the fontconfig database.
 412
 413 <test qual="any" name="property" target="default" compare="eq">
 414
 415    This element contains a single value which is compared with the
 416    target ('pattern', 'font', 'scan' or 'default') property
 417    "property" (substitute any of the property names seen above).
 418    'compare' can be one of "eq", "not_eq", "less", "less_eq",
 419    "more", "more_eq", "contains" or "not_contains". 'qual' may
 420    either be the default, "any", in which case the match succeeds
 421    if any value associated with the property matches the test
 422    value, or "all", in which case all of the values associated
 423    with the property must match the test value. 'ignore-blanks'
 424    takes a boolean value. if 'ignore-blanks' is set "true", any
 425    blanks in the string will be ignored on its comparison. this
 426    takes effects only when compare="eq" or compare="not_eq". When
 427    used in a <match target="font"> element, the target= attribute
 428    in the <test> element selects between matching the original
 429    pattern or the font. "default" selects whichever target the
 430    outer <match> element has selected.
 431
 432 <edit name="property" mode="assign" binding="weak">
 433
 434    This element contains a list of expression elements (any of the
 435    value or operator elements). The expression elements are
 436    evaluated at run-time and modify the property "property". The
 437    modification depends on whether "property" was matched by one
 438    of the associated <test> elements, if so, the modification may
 439    affect the first matched value. Any values inserted into the
 440    property are given the indicated binding ("strong", "weak" or
 441    "same") with "same" binding using the value from the matched
 442    pattern element. 'mode' is one of:
 443   Mode                    With Match              Without Match
 444   ---------------------------------------------------------------------
 445   "assign"                Replace matching value  Replace all values
 446   "assign_replace"        Replace all values      Replace all values
 447   "prepend"               Insert before matching  Insert at head of list
 448   "prepend_first"         Insert at head of list  Insert at head of list
 449   "append"                Append after matching   Append at end of list
 450   "append_last"           Append at end of list   Append at end of list
 451   "delete"                Delete matching value   Delete all values
 452   "delete_all"            Delete all values       Delete all values
 453
 454 <int>, <double>, <string>, <bool>
 455
 456    These elements hold a single value of the indicated type.
 457    <bool> elements hold either true or false. An important
 458    limitation exists in the parsing of floating point numbers --
 459    fontconfig requires that the mantissa start with a digit, not a
 460    decimal point, so insert a leading zero for purely fractional
 461    values (e.g. use 0.5 instead of .5 and -0.5 instead of -.5).
 462
 463 <matrix>
 464
 465    This element holds four numerical expressions of an affine
 466    transformation. At their simplest these will be four <double>
 467    elements but they can also be more involved expressions.
 468
 469 <range>
 470
 471    This element holds the two <int> elements of a range
 472    representation.
 473
 474 <charset>
 475
 476    This element holds at least one <int> element of an Unicode
 477    code point or more.
 478
 479 <langset>
 480
 481    This element holds at least one <string> element of a
 482    RFC-3066-style languages or more.
 483
 484 <name>
 485
 486    Holds a property name. Evaluates to the first value from the
 487    property of the pattern. If the 'target' attribute is not
 488    present, it will default to 'default', in which case the
 489    property is returned from the font pattern during a
 490    target="font" match, and to the pattern during a
 491    target="pattern" match. The attribute can also take the values
 492    'font' or 'pattern' to explicitly choose which pattern to use.
 493    It is an error to use a target of 'font' in a match that has
 494    target="pattern".
 495
 496 <const>
 497
 498    Holds the name of a constant; these are always integers and
 499    serve as symbolic names for common font values:
 500   Constant        Property        Value
 501   -------------------------------------
 502   thin            weight          0
 503   extralight      weight          40
 504   ultralight      weight          40
 505   light           weight          50
 506   demilight       weight          55
 507   semilight       weight          55
 508   book            weight          75
 509   regular         weight          80
 510   normal          weight          80
 511   medium          weight          100
 512   demibold        weight          180
 513   semibold        weight          180
 514   bold            weight          200
 515   extrabold       weight          205
 516   black           weight          210
 517   heavy           weight          210
 518   roman           slant           0
 519   italic          slant           100
 520   oblique         slant           110
 521   ultracondensed  width           50
 522   extracondensed  width           63
 523   condensed       width           75
 524   semicondensed   width           87
 525   normal          width           100
 526   semiexpanded    width           113
 527   expanded        width           125
 528   extraexpanded   width           150
 529   ultraexpanded   width           200
 530   proportional    spacing         0
 531   dual            spacing         90
 532   mono            spacing         100
 533   charcell        spacing         110
 534   unknown         rgba            0
 535   rgb             rgba            1
 536   bgr             rgba            2
 537   vrgb            rgba            3
 538   vbgr            rgba            4
 539   none            rgba            5
 540   lcdnone         lcdfilter       0
 541   lcddefault      lcdfilter       1
 542   lcdlight        lcdfilter       2
 543   lcdlegacy       lcdfilter       3
 544   hintnone        hintstyle       0
 545   hintslight      hintstyle       1
 546   hintmedium      hintstyle       2
 547   hintfull        hintstyle       3
 548
 549 <or>, <and>, <plus>, <minus>, <times>, <divide>
 550
 551    These elements perform the specified operation on a list of
 552    expression elements. <or> and <and> are boolean, not bitwise.
 553
 554 <eq>, <not_eq>, <less>, <less_eq>, <more>, <more_eq>, <contains>,
 555 <not_contains
 556
 557    These elements compare two values, producing a boolean result.
 558
 559 <not>
 560
 561    Inverts the boolean sense of its one expression element
 562
 563 <if>
 564
 565    This element takes three expression elements; if the value of
 566    the first is true, it produces the value of the second,
 567    otherwise it produces the value of the third.
 568
 569 <alias>
 570
 571    Alias elements provide a shorthand notation for the set of
 572    common match operations needed to substitute one font family
 573    for another. They contain a <family> element followed by
 574    optional <prefer>, <accept> and <default> elements. Fonts
 575    matching the <family> element are edited to prepend the list of
 576    <prefer>ed families before the matching <family>, append the
 577    <accept>able families after the matching <family> and append
 578    the <default> families to the end of the family list.
 579
 580 <family>
 581
 582    Holds a single font family name
 583
 584 <prefer>, <accept>, <default>
 585
 586    These hold a list of <family> elements to be used by the
 587    <alias> element.
 588
 589 EXAMPLE CONFIGURATION FILE
 590
 591 System configuration file
 592
 593    This is an example of a system-wide configuration file
 594 <?xml version="1.0"?>
 595 <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
 596 <!-- /etc/fonts/fonts.conf file to configure system font access -->
 597 <fontconfig>
 598 <!--
 599         Find fonts in these directories
 600 -->
 601 <dir>/usr/share/fonts</dir>
 602 <dir>/usr/X11R6/lib/X11/fonts</dir>
 603
 604 <!--
 605         Accept deprecated 'mono' alias, replacing it with 'monospace'
 606 -->
 607 <match target="pattern">
 608         <test qual="any" name="family"><string>mono</string></test>
 609         <edit name="family" mode="assign"><string>monospace</string></ed
 610 it>
 611 </match>
 612
 613 <!--
 614         Names not including any well known alias are given 'sans-serif'
 615 -->
 616 <match target="pattern">
 617         <test qual="all" name="family" mode="not_eq"><string>sans-serif<
 618 /string></test>
 619         <test qual="all" name="family" mode="not_eq"><string>serif</stri
 620 ng></test>
 621         <test qual="all" name="family" mode="not_eq"><string>monospace</
 622 string></test>
 623         <edit name="family" mode="append_last"><string>sans-serif</strin
 624 g></edit>
 625 </match>
 626
 627 <!--
 628         Load per-user customization file, but don't complain
 629         if it doesn't exist
 630 -->
 631 <include ignore_missing="yes" prefix="xdg">fontconfig/fonts.conf</includ
 632 e>
 633
 634 <!--
 635         Load local customization files, but don't complain
 636         if there aren't any
 637 -->
 638 <include ignore_missing="yes">conf.d</include>
 639 <include ignore_missing="yes">local.conf</include>
 640
 641 <!--
 642         Alias well known font names to available TrueType fonts.
 643         These substitute TrueType faces for similar Type1
 644         faces to improve screen appearance.
 645 -->
 646 <alias>
 647         <family>Times</family>
 648         <prefer><family>Times New Roman</family></prefer>
 649         <default><family>serif</family></default>
 650 </alias>
 651 <alias>
 652         <family>Helvetica</family>
 653         <prefer><family>Arial</family></prefer>
 654         <default><family>sans</family></default>
 655 </alias>
 656 <alias>
 657         <family>Courier</family>
 658         <prefer><family>Courier New</family></prefer>
 659         <default><family>monospace</family></default>
 660 </alias>
 661
 662 <!--
 663         Provide required aliases for standard names
 664         Do these after the users configuration file so that
 665         any aliases there are used preferentially
 666 -->
 667 <alias>
 668         <family>serif</family>
 669         <prefer><family>Times New Roman</family></prefer>
 670 </alias>
 671 <alias>
 672         <family>sans</family>
 673         <prefer><family>Arial</family></prefer>
 674 </alias>
 675 <alias>
 676         <family>monospace</family>
 677         <prefer><family>Andale Mono</family></prefer>
 678 </alias>
 679
 680 <--
 681         The example of the requirements of OR operator;
 682         If the 'family' contains 'Courier New' OR 'Courier'
 683         add 'monospace' as the alternative
 684 -->
 685 <match target="pattern">
 686         <test name="family" mode="eq">
 687                 <string>Courier New</string>
 688         </test>
 689         <edit name="family" mode="prepend">
 690                 <string>monospace</string>
 691         </edit>
 692 </match>
 693 <match target="pattern">
 694         <test name="family" mode="eq">
 695                 <string>Courier</string>
 696         </test>
 697         <edit name="family" mode="prepend">
 698                 <string>monospace</string>
 699         </edit>
 700 </match>
 701
 702 </fontconfig>
 703
 704 User configuration file
 705
 706    This is an example of a per-user configuration file that lives
 707    in $XDG_CONFIG_HOME/fontconfig/fonts.conf
 708 <?xml version="1.0"?>
 709 <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
 710 <!-- $XDG_CONFIG_HOME/fontconfig/fonts.conf for per-user font configurat
 711 ion -->
 712 <fontconfig>
 713
 714 <!--
 715         Private font directory
 716 -->
 717 <dir prefix="xdg">fonts</dir>
 718
 719 <!--
 720         use rgb sub-pixel ordering to improve glyph appearance on
 721         LCD screens.  Changes affecting rendering, but not matching
 722         should always use target="font".
 723 -->
 724 <match target="font">
 725         <edit name="rgba" mode="assign"><const>rgb</const></edit>
 726 </match>
 727 <!--
 728         use WenQuanYi Zen Hei font when serif is requested for Chinese
 729 -->
 730 <match>
 731         <!--
 732                 If you don't want to use WenQuanYi Zen Hei font for zh-t
 733 w etc,
 734                 you can use zh-cn instead of zh.
 735                 Please note, even if you set zh-cn, it still matches zh.
 736                 if you don't like it, you can use compare="eq"
 737                 instead of compare="contains".
 738         -->
 739         <test name="lang" compare="contains">
 740                 <string>zh</string>
 741         </test>
 742         <test name="family">
 743                 <string>serif</string>
 744         </test>
 745         <edit name="family" mode="prepend">
 746                 <string>WenQuanYi Zen Hei</string>
 747         </edit>
 748 </match>
 749 <!--
 750         use VL Gothic font when sans-serif is requested for Japanese
 751 -->
 752 <match>
 753         <test name="lang" compare="contains">
 754                 <string>ja</string>
 755         </test>
 756         <test name="family">
 757                 <string>sans-serif</string>
 758         </test>
 759         <edit name="family" mode="prepend">
 760                 <string>VL Gothic</string>
 761         </edit>
 762 </match>
 763 </fontconfig>
 764
 765 Files
 766
 767    fonts.conf contains configuration information for the
 768    fontconfig library consisting of directories to look at for
 769    font information as well as instructions on editing program
 770    specified font patterns before attempting to match the
 771    available fonts. It is in XML format.
 772
 773    conf.d is the conventional name for a directory of additional
 774    configuration files managed by external applications or the
 775    local administrator. The filenames starting with decimal digits
 776    are sorted in lexicographic order and used as additional
 777    configuration files. All of these files are in XML format. The
 778    master fonts.conf file references this directory in an
 779    <include> directive.
 780
 781    fonts.dtd is a DTD that describes the format of the
 782    configuration files.
 783
 784    $XDG_CONFIG_HOME/fontconfig/conf.d and ~/.fonts.conf.d is the
 785    conventional name for a per-user directory of (typically
 786    auto-generated) configuration files, although the actual
 787    location is specified in the global fonts.conf file. please
 788    note that ~/.fonts.conf.d is deprecated now. it will not be
 789    read by default in the future version.
 790
 791    $XDG_CONFIG_HOME/fontconfig/fonts.conf and ~/.fonts.conf is the
 792    conventional location for per-user font configuration, although
 793    the actual location is specified in the global fonts.conf file.
 794    please note that ~/.fonts.conf is deprecated now. it will not
 795    be read by default in the future version.
 796
 797    $XDG_CACHE_HOME/fontconfig/*.cache-* and
 798    ~/.fontconfig/*.cache-* is the conventional repository of font
 799    information that isn't found in the per-directory caches. This
 800    file is automatically maintained by fontconfig. please note
 801    that ~/.fontconfig/*.cache-* is deprecated now. it will not be
 802    read by default in the future version.
 803
 804 Environment variables
 805
 806    FONTCONFIG_FILE is used to override the default configuration
 807    file.
 808
 809    FONTCONFIG_PATH is used to override the default configuration
 810    directory.
 811
 812    FC_DEBUG is used to output the detailed debugging messages. see
 813    Debugging Applications section for more details.
 814
 815    FC_DBG_MATCH_FILTER is used to filter out the patterns. this
 816    takes a comma-separated list of object names and effects only
 817    when FC_DEBUG has MATCH2. see Debugging Applications section
 818    for more details.
 819
 820    FONTCONFIG_USE_MMAP is used to control the use of mmap(2) for
 821    the cache files if available. this take a boolean value.
 822    fontconfig will checks if the cache files are stored on the
 823    filesystem that is safe to use mmap(2). explicitly setting this
 824    environment variable will causes skipping this check and
 825    enforce to use or not use mmap(2) anyway.
 826
 827 See Also
 828
 829    fc-cat(1), fc-cache(1), fc-list(1), fc-match(1), fc-query(1)
 830
 831 Version
 832
 833    Fontconfig version 2.12.1