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