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