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