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