fontconfig-user.txt revision eceda581
1 fonts-conf 2 3Name 4 5 fonts.conf -- Font configuration files 6 7Synopsis 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 17Description 18 19 Fontconfig is a library designed to provide system-wide font 20 configuration, customization and application access. 21 22Functional 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 29Font 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 59Font 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 81l 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 97recated) 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 110ont 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 114bled 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 123Font 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 189Font 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 216Debugging 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 244Lang 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 267Configuration 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 626EXAMPLE CONFIGURATION FILE 627 628System 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 647it> 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 655if</string></test> 656 <test qual="all" name="family" compare="not_eq"><string>serif</s 657tring></test> 658 <test qual="all" name="family" compare="not_eq"><string>monospac 659e</string></test> 660 <edit name="family" mode="append_last"><string>sans-serif</strin 661g></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 669e> 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 741User 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 748ion --> 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 770w 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 802Files 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 841Environment 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 879See Also 880 881 fc-cat(1), fc-cache(1), fc-list(1), fc-match(1), fc-query(1), 882 SOURCE_DATE_EPOCH. 883 884Version 885 886 Fontconfig version 2.14.1 887