fontconfig-user.html revision 953daeba
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<HTML 3><HEAD 4><TITLE 5>fonts-conf</TITLE 6><META 7NAME="GENERATOR" 8CONTENT="Modular DocBook HTML Stylesheet Version 1.79"></HEAD 9><BODY 10CLASS="REFENTRY" 11BGCOLOR="#FFFFFF" 12TEXT="#000000" 13LINK="#0000FF" 14VLINK="#840084" 15ALINK="#0000FF" 16><H1 17><A 18NAME="AEN1" 19></A 20>fonts-conf</H1 21><DIV 22CLASS="REFNAMEDIV" 23><A 24NAME="AEN5" 25></A 26><H2 27>Name</H2 28>fonts.conf -- Font configuration files</DIV 29><DIV 30CLASS="REFSYNOPSISDIV" 31><A 32NAME="AEN8" 33></A 34><H2 35>Synopsis</H2 36><TABLE 37BORDER="0" 38BGCOLOR="#E0E0E0" 39WIDTH="100%" 40><TR 41><TD 42><PRE 43CLASS="SYNOPSIS" 44> /etc/fonts/fonts.conf 45 /etc/fonts/fonts.dtd 46 /etc/fonts/conf.d 47 $XDG_CONFIG_HOME/fontconfig/conf.d 48 $XDG_CONFIG_HOME/fontconfig/fonts.conf 49 ~/.fonts.conf.d 50 ~/.fonts.conf</PRE 51></TD 52></TR 53></TABLE 54></DIV 55><DIV 56CLASS="REFSECT1" 57><A 58NAME="AEN10" 59></A 60><H2 61>Description</H2 62><P 63>Fontconfig is a library designed to provide system-wide font configuration, 64customization and application access. 65 </P 66></DIV 67><DIV 68CLASS="REFSECT1" 69><A 70NAME="AEN13" 71></A 72><H2 73>Functional Overview</H2 74><P 75>Fontconfig contains two essential modules, the configuration module which 76builds an internal configuration from XML files and the matching module 77which accepts font patterns and returns the nearest matching font. 78 </P 79><DIV 80CLASS="REFSECT2" 81><A 82NAME="AEN16" 83></A 84><H3 85>Font Configuration</H3 86><P 87>The configuration module consists of the FcConfig datatype, libexpat and 88FcConfigParse which walks over an XML tree and amends a configuration with 89data found within. From an external perspective, configuration of the 90library consists of generating a valid XML tree and feeding that to 91FcConfigParse. The only other mechanism provided to applications for 92changing the running configuration is to add fonts and directories to the 93list of application-provided font files. 94 </P 95><P 96>The intent is to make font configurations relatively static, and shared by 97as many applications as possible. It is hoped that this will lead to more 98stable font selection when passing names from one application to another. 99XML was chosen as a configuration file format because it provides a format 100which is easy for external agents to edit while retaining the correct 101structure and syntax. 102 </P 103><P 104>Font configuration is separate from font matching; applications needing to 105do their own matching can access the available fonts from the library and 106perform private matching. The intent is to permit applications to pick and 107choose appropriate functionality from the library instead of forcing them to 108choose between this library and a private configuration mechanism. The hope 109is that this will ensure that configuration of fonts for all applications 110can be centralized in one place. Centralizing font configuration will 111simplify and regularize font installation and customization. 112 </P 113></DIV 114><DIV 115CLASS="REFSECT2" 116><A 117NAME="AEN21" 118></A 119><H3 120>Font Properties</H3 121><P 122>While font patterns may contain essentially any properties, there are some 123well known properties with associated types. Fontconfig uses some of these 124properties for font matching and font completion. Others are provided as a 125convenience for the applications' rendering mechanism. 126 </P 127><TABLE 128BORDER="0" 129BGCOLOR="#E0E0E0" 130WIDTH="100%" 131><TR 132><TD 133><PRE 134CLASS="PROGRAMLISTING" 135> Property Type Description 136 -------------------------------------------------------------- 137 family String Font family names 138 familylang String Languages corresponding to each family 139 style String Font style. Overrides weight and slant 140 stylelang String Languages corresponding to each style 141 fullname String Font full names (often includes style) 142 fullnamelang String Languages corresponding to each fullname 143 slant Int Italic, oblique or roman 144 weight Int Light, medium, demibold, bold or black 145 size Double Point size 146 width Int Condensed, normal or expanded 147 aspect Double Stretches glyphs horizontally before hinting 148 pixelsize Double Pixel size 149 spacing Int Proportional, dual-width, monospace or charcell 150 foundry String Font foundry name 151 antialias Bool Whether glyphs can be antialiased 152 hinting Bool Whether the rasterizer should use hinting 153 hintstyle Int Automatic hinting style 154 verticallayout Bool Use vertical layout 155 autohint Bool Use autohinter instead of normal hinter 156 globaladvance Bool Use font global advance data (deprecated) 157 file String The filename holding the font 158 index Int The index of the font within the file 159 ftface FT_Face Use the specified FreeType face object 160 rasterizer String Which rasterizer is in use (deprecated) 161 outline Bool Whether the glyphs are outlines 162 scalable Bool Whether glyphs can be scaled 163 color Bool Whether any glyphs have color 164 scale Double Scale factor for point->pixel conversions (deprecated) 165 dpi Double Target dots per inch 166 rgba Int unknown, rgb, bgr, vrgb, vbgr, 167 none - subpixel geometry 168 lcdfilter Int Type of LCD filter 169 minspace Bool Eliminate leading from line spacing 170 charset CharSet Unicode chars encoded by the font 171 lang String List of RFC-3066-style languages this 172 font supports 173 fontversion Int Version number of the font 174 capability String List of layout capabilities in the font 175 fontformat String String name of the font format 176 embolden Bool Rasterizer should synthetically embolden the font 177 embeddedbitmap Bool Use the embedded bitmap instead of the outline 178 decorative Bool Whether the style is a decorative variant 179 fontfeatures String List of the feature tags in OpenType to be enabled 180 namelang String Language name to be used for the default value of 181 familylang, stylelang, and fullnamelang 182 prgname String String Name of the running program 183 postscriptname String Font family name in PostScript 184 </PRE 185></TD 186></TR 187></TABLE 188></DIV 189><DIV 190CLASS="REFSECT2" 191><A 192NAME="AEN25" 193></A 194><H3 195>Font Matching</H3 196><P 197>Fontconfig performs matching by measuring the distance from a provided 198pattern to all of the available fonts in the system. The closest matching 199font is selected. This ensures that a font will always be returned, but 200doesn't ensure that it is anything like the requested pattern. 201 </P 202><P 203> 204Font matching starts with an application constructed pattern. The desired 205attributes of the resulting font are collected together in a pattern. Each 206property of the pattern can contain one or more values; these are listed in 207priority order; matches earlier in the list are considered "closer" than 208matches later in the list. 209 </P 210><P 211>The initial pattern is modified by applying the list of editing instructions 212specific to patterns found in the configuration; each consists of a match 213predicate and a set of editing operations. They are executed in the order 214they appeared in the configuration. Each match causes the associated 215sequence of editing operations to be applied. 216 </P 217><P 218>After the pattern has been edited, a sequence of default substitutions are 219performed to canonicalize the set of available properties; this avoids the 220need for the lower layers to constantly provide default values for various 221font properties during rendering. 222 </P 223><P 224>The canonical font pattern is finally matched against all available fonts. 225The distance from the pattern to the font is measured for each of several 226properties: foundry, charset, family, lang, spacing, pixelsize, style, 227slant, weight, antialias, rasterizer and outline. This list is in priority 228order -- results of comparing earlier elements of this list weigh more 229heavily than later elements. 230 </P 231><P 232>There is one special case to this rule; family names are split into two 233bindings; strong and weak. Strong family names are given greater precedence 234in the match than lang elements while weak family names are given lower 235precedence than lang elements. This permits the document language to drive 236font selection when any document specified font is unavailable. 237 </P 238><P 239>The pattern representing that font is augmented to include any properties 240found in the pattern but not found in the font itself; this permits the 241application to pass rendering instructions or any other data through the 242matching system. Finally, the list of editing instructions specific to 243fonts found in the configuration are applied to the pattern. This modified 244pattern is returned to the application. 245 </P 246><P 247>The return value contains sufficient information to locate and rasterize the 248font, including the file name, pixel size and other rendering data. As 249none of the information involved pertains to the FreeType library, 250applications are free to use any rasterization engine or even to take 251the identified font file and access it directly. 252 </P 253><P 254>The match/edit sequences in the configuration are performed in two passes 255because there are essentially two different operations necessary -- the 256first is to modify how fonts are selected; aliasing families and adding 257suitable defaults. The second is to modify how the selected fonts are 258rasterized. Those must apply to the selected font, not the original pattern 259as false matches will often occur. 260 </P 261></DIV 262><DIV 263CLASS="REFSECT2" 264><A 265NAME="AEN36" 266></A 267><H3 268>Font Names</H3 269><P 270>Fontconfig provides a textual representation for patterns that the library 271can both accept and generate. The representation is in three parts, first a 272list of family names, second a list of point sizes and finally a list of 273additional properties: 274 </P 275><TABLE 276BORDER="0" 277BGCOLOR="#E0E0E0" 278WIDTH="100%" 279><TR 280><TD 281><PRE 282CLASS="PROGRAMLISTING" 283> <families>-<point sizes>:<name1>=<values1>:<name2>=<values2>... 284 </PRE 285></TD 286></TR 287></TABLE 288><P 289>Values in a list are separated with commas. The name needn't include either 290families or point sizes; they can be elided. In addition, there are 291symbolic constants that simultaneously indicate both a name and a value. 292Here are some examples: 293 </P 294><TABLE 295BORDER="0" 296BGCOLOR="#E0E0E0" 297WIDTH="100%" 298><TR 299><TD 300><PRE 301CLASS="PROGRAMLISTING" 302> Name Meaning 303 ---------------------------------------------------------- 304 Times-12 12 point Times Roman 305 Times-12:bold 12 point Times Bold 306 Courier:italic Courier Italic in the default size 307 Monospace:matrix=1 .1 0 1 The users preferred monospace font 308 with artificial obliquing 309 </PRE 310></TD 311></TR 312></TABLE 313><P 314>The '\', '-', ':' and ',' characters in family names must be preceded by a 315'\' character to avoid having them misinterpreted. Similarly, values 316containing '\', '=', '_', ':' and ',' must also have them preceded by a 317'\' character. The '\' characters are stripped out of the family name and 318values as the font name is read. 319 </P 320></DIV 321></DIV 322><DIV 323CLASS="REFSECT1" 324><A 325NAME="DEBUG" 326></A 327><H2 328>Debugging Applications</H2 329><P 330>To help diagnose font and applications problems, fontconfig is built with a 331large amount of internal debugging left enabled. It is controlled by means 332of the FC_DEBUG environment variable. The value of this variable is 333interpreted as a number, and each bit within that value controls different 334debugging messages. 335 </P 336><TABLE 337BORDER="0" 338BGCOLOR="#E0E0E0" 339WIDTH="100%" 340><TR 341><TD 342><PRE 343CLASS="PROGRAMLISTING" 344> Name Value Meaning 345 --------------------------------------------------------- 346 MATCH 1 Brief information about font matching 347 MATCHV 2 Extensive font matching information 348 EDIT 4 Monitor match/test/edit execution 349 FONTSET 8 Track loading of font information at startup 350 CACHE 16 Watch cache files being written 351 CACHEV 32 Extensive cache file writing information 352 PARSE 64 (no longer in use) 353 SCAN 128 Watch font files being scanned to build caches 354 SCANV 256 Verbose font file scanning information 355 MEMORY 512 Monitor fontconfig memory usage 356 CONFIG 1024 Monitor which config files are loaded 357 LANGSET 2048 Dump char sets used to construct lang values 358 MATCH2 4096 Display font-matching transformation in patterns 359 </PRE 360></TD 361></TR 362></TABLE 363><P 364>Add the value of the desired debug levels together and assign that (in 365base 10) to the FC_DEBUG environment variable before running the 366application. Output from these statements is sent to stdout. 367 </P 368></DIV 369><DIV 370CLASS="REFSECT1" 371><A 372NAME="AEN48" 373></A 374><H2 375>Lang Tags</H2 376><P 377>Each font in the database contains a list of languages it supports. This is 378computed by comparing the Unicode coverage of the font with the orthography 379of each language. Languages are tagged using an RFC-3066 compatible naming 380and occur in two parts -- the ISO 639 language tag followed a hyphen and then 381by the ISO 3166 country code. The hyphen and country code may be elided. 382 </P 383><P 384>Fontconfig has orthographies for several languages built into the library. 385No provision has been made for adding new ones aside from rebuilding the 386library. It currently supports 122 of the 139 languages named in ISO 639-1, 387141 of the languages with two-letter codes from ISO 639-2 and another 30 388languages with only three-letter codes. Languages with both two and three 389letter codes are provided with only the two letter code. 390 </P 391><P 392>For languages used in multiple territories with radically different 393character sets, fontconfig includes per-territory orthographies. This 394includes Azerbaijani, Kurdish, Pashto, Tigrinya and Chinese. 395 </P 396></DIV 397><DIV 398CLASS="REFSECT1" 399><A 400NAME="AEN53" 401></A 402><H2 403>Configuration File Format</H2 404><P 405>Configuration files for fontconfig are stored in XML format; this 406format makes external configuration tools easier to write and ensures that 407they will generate syntactically correct configuration files. As XML 408files are plain text, they can also be manipulated by the expert user using 409a text editor. 410 </P 411><P 412>The fontconfig document type definition resides in the external entity 413"fonts.dtd"; this is normally stored in the default font configuration 414directory (/etc/fonts). Each configuration file should contain the 415following structure: 416 <TABLE 417BORDER="0" 418BGCOLOR="#E0E0E0" 419WIDTH="100%" 420><TR 421><TD 422><PRE 423CLASS="PROGRAMLISTING" 424> <?xml version="1.0"?> 425 <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> 426 <fontconfig> 427 ... 428 </fontconfig> 429 </PRE 430></TD 431></TR 432></TABLE 433> 434 </P 435><DIV 436CLASS="REFSECT2" 437><A 438NAME="AEN58" 439></A 440><H3 441><TT 442CLASS="LITERAL" 443><fontconfig></TT 444></H3 445><P 446>This is the top level element for a font configuration and can contain 447<TT 448CLASS="LITERAL" 449><dir></TT 450>, <TT 451CLASS="LITERAL" 452><cachedir></TT 453>, <TT 454CLASS="LITERAL" 455><include></TT 456>, <TT 457CLASS="LITERAL" 458><match></TT 459> and <TT 460CLASS="LITERAL" 461><alias></TT 462> elements in any order. 463 </P 464></DIV 465><DIV 466CLASS="REFSECT2" 467><A 468NAME="AEN67" 469></A 470><H3 471><TT 472CLASS="LITERAL" 473><dir prefix="default"></TT 474></H3 475><P 476>This element contains a directory name which will be scanned for font files 477to include in the set of available fonts. If 'prefix' is set to "xdg", the value in the XDG_DATA_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details. 478 </P 479></DIV 480><DIV 481CLASS="REFSECT2" 482><A 483NAME="AEN71" 484></A 485><H3 486><TT 487CLASS="LITERAL" 488><cachedir prefix="default"></TT 489></H3 490><P 491>This element contains a directory name that is supposed to be stored or read 492the cache of font information. If multiple elements are specified in 493the configuration file, the directory that can be accessed first in the list 494will be used to store the cache files. If it starts with '~', it refers to 495a directory in the users home directory. If 'prefix' is set to "xdg", the value in the XDG_CACHE_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details. 496The default directory is ``$XDG_CACHE_HOME/fontconfig'' and it contains the cache files 497named ``<TT 498CLASS="LITERAL" 499><hash value></TT 500>-<TT 501CLASS="LITERAL" 502><architecture></TT 503>.cache-<TT 504CLASS="LITERAL" 505><version></TT 506>'', 507where <TT 508CLASS="LITERAL" 509><version></TT 510> is the fontconfig cache file 511version number (currently 7). 512 </P 513></DIV 514><DIV 515CLASS="REFSECT2" 516><A 517NAME="AEN79" 518></A 519><H3 520><TT 521CLASS="LITERAL" 522><include ignore_missing="no" prefix="default"></TT 523></H3 524><P 525>This element contains the name of an additional configuration file or 526directory. If a directory, every file within that directory starting with an 527ASCII digit (U+0030 - U+0039) and ending with the string ``.conf'' will be processed in sorted order. When 528the XML datatype is traversed by FcConfigParse, the contents of the file(s) 529will also be incorporated into the configuration by passing the filename(s) to 530FcConfigLoadAndParse. If 'ignore_missing' is set to "yes" instead of the 531default "no", a missing file or directory will elicit no warning message from 532the library. If 'prefix' is set to "xdg", the value in the XDG_CONFIG_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details. 533 </P 534></DIV 535><DIV 536CLASS="REFSECT2" 537><A 538NAME="AEN83" 539></A 540><H3 541><TT 542CLASS="LITERAL" 543><config></TT 544></H3 545><P 546>This element provides a place to consolidate additional configuration 547information. <TT 548CLASS="LITERAL" 549><config></TT 550> can contain <TT 551CLASS="LITERAL" 552><blank></TT 553> and <TT 554CLASS="LITERAL" 555><rescan></TT 556> elements in any 557order. 558 </P 559></DIV 560><DIV 561CLASS="REFSECT2" 562><A 563NAME="AEN90" 564></A 565><H3 566><TT 567CLASS="LITERAL" 568><blank></TT 569></H3 570><P 571>Fonts often include "broken" glyphs which appear in the encoding but are 572drawn as blanks on the screen. Within the <TT 573CLASS="LITERAL" 574><blank></TT 575> element, place each 576Unicode characters which is supposed to be blank in an <TT 577CLASS="LITERAL" 578><int></TT 579> element. 580Characters outside of this set which are drawn as blank will be elided from 581the set of characters supported by the font. 582 </P 583></DIV 584><DIV 585CLASS="REFSECT2" 586><A 587NAME="AEN96" 588></A 589><H3 590><TT 591CLASS="LITERAL" 592><rescan></TT 593></H3 594><P 595>The <TT 596CLASS="LITERAL" 597><rescan></TT 598> element holds an <TT 599CLASS="LITERAL" 600><int></TT 601> element which indicates the default 602interval between automatic checks for font configuration changes. 603Fontconfig will validate all of the configuration files and directories and 604automatically rebuild the internal datastructures when this interval passes. 605 </P 606></DIV 607><DIV 608CLASS="REFSECT2" 609><A 610NAME="AEN102" 611></A 612><H3 613><TT 614CLASS="LITERAL" 615><selectfont></TT 616></H3 617><P 618>This element is used to black/white list fonts from being listed or matched 619against. It holds acceptfont and rejectfont elements. 620 </P 621></DIV 622><DIV 623CLASS="REFSECT2" 624><A 625NAME="AEN106" 626></A 627><H3 628><TT 629CLASS="LITERAL" 630><acceptfont></TT 631></H3 632><P 633>Fonts matched by an acceptfont element are "whitelisted"; such fonts are 634explicitly included in the set of fonts used to resolve list and match 635requests; including them in this list protects them from being "blacklisted" 636by a rejectfont element. Acceptfont elements include glob and pattern 637elements which are used to match fonts. 638 </P 639></DIV 640><DIV 641CLASS="REFSECT2" 642><A 643NAME="AEN110" 644></A 645><H3 646><TT 647CLASS="LITERAL" 648><rejectfont></TT 649></H3 650><P 651>Fonts matched by an rejectfont element are "blacklisted"; such fonts are 652excluded from the set of fonts used to resolve list and match requests as if 653they didn't exist in the system. Rejectfont elements include glob and 654pattern elements which are used to match fonts. 655 </P 656></DIV 657><DIV 658CLASS="REFSECT2" 659><A 660NAME="AEN114" 661></A 662><H3 663><TT 664CLASS="LITERAL" 665><glob></TT 666></H3 667><P 668>Glob elements hold shell-style filename matching patterns (including ? and 669*) which match fonts based on their complete pathnames. This can be used to 670exclude a set of directories (/usr/share/fonts/uglyfont*), or particular 671font file types (*.pcf.gz), but the latter mechanism relies rather heavily 672on filenaming conventions which can't be relied upon. Note that globs 673only apply to directories, not to individual fonts. 674 </P 675></DIV 676><DIV 677CLASS="REFSECT2" 678><A 679NAME="AEN118" 680></A 681><H3 682><TT 683CLASS="LITERAL" 684><pattern></TT 685></H3 686><P 687>Pattern elements perform list-style matching on incoming fonts; that is, 688they hold a list of elements and associated values. If all of those 689elements have a matching value, then the pattern matches the font. This can 690be used to select fonts based on attributes of the font (scalable, bold, 691etc), which is a more reliable mechanism than using file extensions. 692Pattern elements include patelt elements. 693 </P 694></DIV 695><DIV 696CLASS="REFSECT2" 697><A 698NAME="AEN122" 699></A 700><H3 701><TT 702CLASS="LITERAL" 703><patelt name="property"></TT 704></H3 705><P 706>Patelt elements hold a single pattern element and list of values. They must 707have a 'name' attribute which indicates the pattern element name. Patelt 708elements include int, double, string, matrix, bool, charset and const 709elements. 710 </P 711></DIV 712><DIV 713CLASS="REFSECT2" 714><A 715NAME="AEN126" 716></A 717><H3 718><TT 719CLASS="LITERAL" 720><match target="pattern"></TT 721></H3 722><P 723>This element holds first a (possibly empty) list of <TT 724CLASS="LITERAL" 725><test></TT 726> elements and then 727a (possibly empty) list of <TT 728CLASS="LITERAL" 729><edit></TT 730> elements. Patterns which match all of the 731tests are subjected to all the edits. If 'target' is set to "font" instead 732of the default "pattern", then this element applies to the font name 733resulting from a match rather than a font pattern to be matched. If 'target' 734is set to "scan", then this element applies when the font is scanned to 735build the fontconfig database. 736 </P 737></DIV 738><DIV 739CLASS="REFSECT2" 740><A 741NAME="AEN132" 742></A 743><H3 744><TT 745CLASS="LITERAL" 746><test qual="any" name="property" target="default" compare="eq"></TT 747></H3 748><P 749>This element contains a single value which is compared with the target 750('pattern', 'font', 'scan' or 'default') property "property" (substitute any of the property names seen 751above). 'compare' can be one of "eq", "not_eq", "less", "less_eq", "more", "more_eq", "contains" or 752"not_contains". 'qual' may either be the default, "any", in which case the match 753succeeds if any value associated with the property matches the test value, or 754"all", in which case all of the values associated with the property must 755match the test value. 'ignore-blanks' takes a boolean value. if 'ignore-blanks' is set "true", any blanks in the string will be ignored on its comparison. this takes effects only when compare="eq" or compare="not_eq". 756When used in a <match target="font"> element, 757the target= attribute in the <test> element selects between matching 758the original pattern or the font. "default" selects whichever target the 759outer <match> element has selected. 760 </P 761></DIV 762><DIV 763CLASS="REFSECT2" 764><A 765NAME="AEN136" 766></A 767><H3 768><TT 769CLASS="LITERAL" 770><edit name="property" mode="assign" binding="weak"></TT 771></H3 772><P 773>This element contains a list of expression elements (any of the value or 774operator elements). The expression elements are evaluated at run-time and 775modify the property "property". The modification depends on whether 776"property" was matched by one of the associated <TT 777CLASS="LITERAL" 778><test></TT 779> elements, if so, the 780modification may affect the first matched value. Any values inserted into 781the property are given the indicated binding ("strong", "weak" or "same") 782with "same" binding using the value from the matched pattern element. 783'mode' is one of: 784 <TABLE 785BORDER="0" 786BGCOLOR="#E0E0E0" 787WIDTH="100%" 788><TR 789><TD 790><PRE 791CLASS="PROGRAMLISTING" 792> Mode With Match Without Match 793 --------------------------------------------------------------------- 794 "assign" Replace matching value Replace all values 795 "assign_replace" Replace all values Replace all values 796 "prepend" Insert before matching Insert at head of list 797 "prepend_first" Insert at head of list Insert at head of list 798 "append" Append after matching Append at end of list 799 "append_last" Append at end of list Append at end of list 800 "delete" Delete matching value Delete all values 801 "delete_all" Delete all values Delete all values 802 </PRE 803></TD 804></TR 805></TABLE 806> 807 </P 808></DIV 809><DIV 810CLASS="REFSECT2" 811><A 812NAME="AEN142" 813></A 814><H3 815><TT 816CLASS="LITERAL" 817><int></TT 818>, <TT 819CLASS="LITERAL" 820><double></TT 821>, <TT 822CLASS="LITERAL" 823><string></TT 824>, <TT 825CLASS="LITERAL" 826><bool></TT 827></H3 828><P 829>These elements hold a single value of the indicated type. <TT 830CLASS="LITERAL" 831><bool></TT 832> 833elements hold either true or false. An important limitation exists in 834the parsing of floating point numbers -- fontconfig requires that 835the mantissa start with a digit, not a decimal point, so insert a leading 836zero for purely fractional values (e.g. use 0.5 instead of .5 and -0.5 837instead of -.5). 838 </P 839></DIV 840><DIV 841CLASS="REFSECT2" 842><A 843NAME="AEN150" 844></A 845><H3 846><TT 847CLASS="LITERAL" 848><matrix></TT 849></H3 850><P 851>This element holds four numerical expressions of an affine transformation. 852At their simplest these will be four <TT 853CLASS="LITERAL" 854><double></TT 855> elements 856but they can also be more involved expressions. 857 </P 858></DIV 859><DIV 860CLASS="REFSECT2" 861><A 862NAME="AEN155" 863></A 864><H3 865><TT 866CLASS="LITERAL" 867><range></TT 868></H3 869><P 870>This element holds the two <TT 871CLASS="LITERAL" 872><int></TT 873> elements of a range 874representation. 875 </P 876></DIV 877><DIV 878CLASS="REFSECT2" 879><A 880NAME="AEN160" 881></A 882><H3 883><TT 884CLASS="LITERAL" 885><charset></TT 886></H3 887><P 888>This element holds at least one <TT 889CLASS="LITERAL" 890><int></TT 891> element of 892an Unicode code point or more. 893 </P 894></DIV 895><DIV 896CLASS="REFSECT2" 897><A 898NAME="AEN165" 899></A 900><H3 901><TT 902CLASS="LITERAL" 903><langset></TT 904></H3 905><P 906>This element holds at least one <TT 907CLASS="LITERAL" 908><string></TT 909> element of 910a RFC-3066-style languages or more. 911 </P 912></DIV 913><DIV 914CLASS="REFSECT2" 915><A 916NAME="AEN170" 917></A 918><H3 919><TT 920CLASS="LITERAL" 921><name></TT 922></H3 923><P 924>Holds a property name. Evaluates to the first value from the property of 925the pattern. If the 'target' attribute is not present, it will default to 926'default', in which case the property is returned from the font pattern 927during a target="font" match, and to the pattern during a target="pattern" 928match. The attribute can also take the values 'font' or 'pattern' to 929explicitly choose which pattern to use. It is an error to use a target 930of 'font' in a match that has target="pattern". 931 </P 932></DIV 933><DIV 934CLASS="REFSECT2" 935><A 936NAME="AEN174" 937></A 938><H3 939><TT 940CLASS="LITERAL" 941><const></TT 942></H3 943><P 944>Holds the name of a constant; these are always integers and serve as 945symbolic names for common font values: 946 <TABLE 947BORDER="0" 948BGCOLOR="#E0E0E0" 949WIDTH="100%" 950><TR 951><TD 952><PRE 953CLASS="PROGRAMLISTING" 954> Constant Property Value 955 ------------------------------------- 956 thin weight 0 957 extralight weight 40 958 ultralight weight 40 959 light weight 50 960 demilight weight 55 961 semilight weight 55 962 book weight 75 963 regular weight 80 964 normal weight 80 965 medium weight 100 966 demibold weight 180 967 semibold weight 180 968 bold weight 200 969 extrabold weight 205 970 black weight 210 971 heavy weight 210 972 roman slant 0 973 italic slant 100 974 oblique slant 110 975 ultracondensed width 50 976 extracondensed width 63 977 condensed width 75 978 semicondensed width 87 979 normal width 100 980 semiexpanded width 113 981 expanded width 125 982 extraexpanded width 150 983 ultraexpanded width 200 984 proportional spacing 0 985 dual spacing 90 986 mono spacing 100 987 charcell spacing 110 988 unknown rgba 0 989 rgb rgba 1 990 bgr rgba 2 991 vrgb rgba 3 992 vbgr rgba 4 993 none rgba 5 994 lcdnone lcdfilter 0 995 lcddefault lcdfilter 1 996 lcdlight lcdfilter 2 997 lcdlegacy lcdfilter 3 998 hintnone hintstyle 0 999 hintslight hintstyle 1 1000 hintmedium hintstyle 2 1001 hintfull hintstyle 3 1002 </PRE 1003></TD 1004></TR 1005></TABLE 1006> 1007 </P 1008></DIV 1009><DIV 1010CLASS="REFSECT2" 1011><A 1012NAME="AEN179" 1013></A 1014><H3 1015><TT 1016CLASS="LITERAL" 1017><or></TT 1018>, <TT 1019CLASS="LITERAL" 1020><and></TT 1021>, <TT 1022CLASS="LITERAL" 1023><plus></TT 1024>, <TT 1025CLASS="LITERAL" 1026><minus></TT 1027>, <TT 1028CLASS="LITERAL" 1029><times></TT 1030>, <TT 1031CLASS="LITERAL" 1032><divide></TT 1033></H3 1034><P 1035>These elements perform the specified operation on a list of expression 1036elements. <TT 1037CLASS="LITERAL" 1038><or></TT 1039> and <TT 1040CLASS="LITERAL" 1041><and></TT 1042> are boolean, not bitwise. 1043 </P 1044></DIV 1045><DIV 1046CLASS="REFSECT2" 1047><A 1048NAME="AEN190" 1049></A 1050><H3 1051><TT 1052CLASS="LITERAL" 1053><eq></TT 1054>, <TT 1055CLASS="LITERAL" 1056><not_eq></TT 1057>, <TT 1058CLASS="LITERAL" 1059><less></TT 1060>, <TT 1061CLASS="LITERAL" 1062><less_eq></TT 1063>, <TT 1064CLASS="LITERAL" 1065><more></TT 1066>, <TT 1067CLASS="LITERAL" 1068><more_eq></TT 1069>, <TT 1070CLASS="LITERAL" 1071><contains></TT 1072>, <TT 1073CLASS="LITERAL" 1074><not_contains</TT 1075></H3 1076><P 1077>These elements compare two values, producing a boolean result. 1078 </P 1079></DIV 1080><DIV 1081CLASS="REFSECT2" 1082><A 1083NAME="AEN201" 1084></A 1085><H3 1086><TT 1087CLASS="LITERAL" 1088><not></TT 1089></H3 1090><P 1091>Inverts the boolean sense of its one expression element 1092 </P 1093></DIV 1094><DIV 1095CLASS="REFSECT2" 1096><A 1097NAME="AEN205" 1098></A 1099><H3 1100><TT 1101CLASS="LITERAL" 1102><if></TT 1103></H3 1104><P 1105>This element takes three expression elements; if the value of the first is 1106true, it produces the value of the second, otherwise it produces the value 1107of the third. 1108 </P 1109></DIV 1110><DIV 1111CLASS="REFSECT2" 1112><A 1113NAME="AEN209" 1114></A 1115><H3 1116><TT 1117CLASS="LITERAL" 1118><alias></TT 1119></H3 1120><P 1121>Alias elements provide a shorthand notation for the set of common match 1122operations needed to substitute one font family for another. They contain a 1123<TT 1124CLASS="LITERAL" 1125><family></TT 1126> element followed by optional <TT 1127CLASS="LITERAL" 1128><prefer></TT 1129>, <TT 1130CLASS="LITERAL" 1131><accept></TT 1132> and <TT 1133CLASS="LITERAL" 1134><default></TT 1135> 1136elements. Fonts matching the <TT 1137CLASS="LITERAL" 1138><family></TT 1139> element are edited to prepend the 1140list of <TT 1141CLASS="LITERAL" 1142><prefer></TT 1143>ed families before the matching <TT 1144CLASS="LITERAL" 1145><family></TT 1146>, append the 1147<TT 1148CLASS="LITERAL" 1149><accept></TT 1150>able families after the matching <TT 1151CLASS="LITERAL" 1152><family></TT 1153> and append the <TT 1154CLASS="LITERAL" 1155><default></TT 1156> 1157families to the end of the family list. 1158 </P 1159></DIV 1160><DIV 1161CLASS="REFSECT2" 1162><A 1163NAME="AEN223" 1164></A 1165><H3 1166><TT 1167CLASS="LITERAL" 1168><family></TT 1169></H3 1170><P 1171>Holds a single font family name 1172 </P 1173></DIV 1174><DIV 1175CLASS="REFSECT2" 1176><A 1177NAME="AEN227" 1178></A 1179><H3 1180><TT 1181CLASS="LITERAL" 1182><prefer></TT 1183>, <TT 1184CLASS="LITERAL" 1185><accept></TT 1186>, <TT 1187CLASS="LITERAL" 1188><default></TT 1189></H3 1190><P 1191>These hold a list of <TT 1192CLASS="LITERAL" 1193><family></TT 1194> elements to be used by the <TT 1195CLASS="LITERAL" 1196><alias></TT 1197> element. 1198 </P 1199></DIV 1200></DIV 1201><DIV 1202CLASS="REFSECT1" 1203><A 1204NAME="AEN235" 1205></A 1206><H2 1207>EXAMPLE CONFIGURATION FILE</H2 1208><DIV 1209CLASS="REFSECT2" 1210><A 1211NAME="AEN237" 1212></A 1213><H3 1214>System configuration file</H3 1215><P 1216>This is an example of a system-wide configuration file 1217 </P 1218><TABLE 1219BORDER="0" 1220BGCOLOR="#E0E0E0" 1221WIDTH="100%" 1222><TR 1223><TD 1224><PRE 1225CLASS="PROGRAMLISTING" 1226><?xml version="1.0"?> 1227<!DOCTYPE fontconfig SYSTEM "fonts.dtd"> 1228<!-- /etc/fonts/fonts.conf file to configure system font access --> 1229<fontconfig> 1230<!-- 1231 Find fonts in these directories 1232--> 1233<dir>/usr/share/fonts</dir> 1234<dir>/usr/X11R6/lib/X11/fonts</dir> 1235 1236<!-- 1237 Accept deprecated 'mono' alias, replacing it with 'monospace' 1238--> 1239<match target="pattern"> 1240 <test qual="any" name="family"><string>mono</string></test> 1241 <edit name="family" mode="assign"><string>monospace</string></edit> 1242</match> 1243 1244<!-- 1245 Names not including any well known alias are given 'sans-serif' 1246--> 1247<match target="pattern"> 1248 <test qual="all" name="family" mode="not_eq"><string>sans-serif</string></test> 1249 <test qual="all" name="family" mode="not_eq"><string>serif</string></test> 1250 <test qual="all" name="family" mode="not_eq"><string>monospace</string></test> 1251 <edit name="family" mode="append_last"><string>sans-serif</string></edit> 1252</match> 1253 1254<!-- 1255 Load per-user customization file, but don't complain 1256 if it doesn't exist 1257--> 1258<include ignore_missing="yes" prefix="xdg">fontconfig/fonts.conf</include> 1259 1260<!-- 1261 Load local customization files, but don't complain 1262 if there aren't any 1263--> 1264<include ignore_missing="yes">conf.d</include> 1265<include ignore_missing="yes">local.conf</include> 1266 1267<!-- 1268 Alias well known font names to available TrueType fonts. 1269 These substitute TrueType faces for similar Type1 1270 faces to improve screen appearance. 1271--> 1272<alias> 1273 <family>Times</family> 1274 <prefer><family>Times New Roman</family></prefer> 1275 <default><family>serif</family></default> 1276</alias> 1277<alias> 1278 <family>Helvetica</family> 1279 <prefer><family>Arial</family></prefer> 1280 <default><family>sans</family></default> 1281</alias> 1282<alias> 1283 <family>Courier</family> 1284 <prefer><family>Courier New</family></prefer> 1285 <default><family>monospace</family></default> 1286</alias> 1287 1288<!-- 1289 Provide required aliases for standard names 1290 Do these after the users configuration file so that 1291 any aliases there are used preferentially 1292--> 1293<alias> 1294 <family>serif</family> 1295 <prefer><family>Times New Roman</family></prefer> 1296</alias> 1297<alias> 1298 <family>sans</family> 1299 <prefer><family>Arial</family></prefer> 1300</alias> 1301<alias> 1302 <family>monospace</family> 1303 <prefer><family>Andale Mono</family></prefer> 1304</alias> 1305 1306<-- 1307 The example of the requirements of OR operator; 1308 If the 'family' contains 'Courier New' OR 'Courier' 1309 add 'monospace' as the alternative 1310--> 1311<match target="pattern"> 1312 <test name="family" mode="eq"> 1313 <string>Courier New</string> 1314 </test> 1315 <edit name="family" mode="prepend"> 1316 <string>monospace</string> 1317 </edit> 1318</match> 1319<match target="pattern"> 1320 <test name="family" mode="eq"> 1321 <string>Courier</string> 1322 </test> 1323 <edit name="family" mode="prepend"> 1324 <string>monospace</string> 1325 </edit> 1326</match> 1327 1328</fontconfig> 1329 </PRE 1330></TD 1331></TR 1332></TABLE 1333></DIV 1334><DIV 1335CLASS="REFSECT2" 1336><A 1337NAME="AEN241" 1338></A 1339><H3 1340>User configuration file</H3 1341><P 1342>This is an example of a per-user configuration file that lives in 1343$XDG_CONFIG_HOME/fontconfig/fonts.conf 1344 </P 1345><TABLE 1346BORDER="0" 1347BGCOLOR="#E0E0E0" 1348WIDTH="100%" 1349><TR 1350><TD 1351><PRE 1352CLASS="PROGRAMLISTING" 1353><?xml version="1.0"?> 1354<!DOCTYPE fontconfig SYSTEM "fonts.dtd"> 1355<!-- $XDG_CONFIG_HOME/fontconfig/fonts.conf for per-user font configuration --> 1356<fontconfig> 1357 1358<!-- 1359 Private font directory 1360--> 1361<dir prefix="xdg">fonts</dir> 1362 1363<!-- 1364 use rgb sub-pixel ordering to improve glyph appearance on 1365 LCD screens. Changes affecting rendering, but not matching 1366 should always use target="font". 1367--> 1368<match target="font"> 1369 <edit name="rgba" mode="assign"><const>rgb</const></edit> 1370</match> 1371<!-- 1372 use WenQuanYi Zen Hei font when serif is requested for Chinese 1373--> 1374<match> 1375 <!-- 1376 If you don't want to use WenQuanYi Zen Hei font for zh-tw etc, 1377 you can use zh-cn instead of zh. 1378 Please note, even if you set zh-cn, it still matches zh. 1379 if you don't like it, you can use compare="eq" 1380 instead of compare="contains". 1381 --> 1382 <test name="lang" compare="contains"> 1383 <string>zh</string> 1384 </test> 1385 <test name="family"> 1386 <string>serif</string> 1387 </test> 1388 <edit name="family" mode="prepend"> 1389 <string>WenQuanYi Zen Hei</string> 1390 </edit> 1391</match> 1392<!-- 1393 use VL Gothic font when sans-serif is requested for Japanese 1394--> 1395<match> 1396 <test name="lang" compare="contains"> 1397 <string>ja</string> 1398 </test> 1399 <test name="family"> 1400 <string>sans-serif</string> 1401 </test> 1402 <edit name="family" mode="prepend"> 1403 <string>VL Gothic</string> 1404 </edit> 1405</match> 1406</fontconfig> 1407 </PRE 1408></TD 1409></TR 1410></TABLE 1411></DIV 1412></DIV 1413><DIV 1414CLASS="REFSECT1" 1415><A 1416NAME="AEN245" 1417></A 1418><H2 1419>Files</H2 1420><P 1421><I 1422CLASS="EMPHASIS" 1423>fonts.conf</I 1424> 1425contains configuration information for the fontconfig library 1426consisting of directories to look at for font information as well as 1427instructions on editing program specified font patterns before attempting to 1428match the available fonts. It is in XML format. 1429 </P 1430><P 1431><I 1432CLASS="EMPHASIS" 1433>conf.d</I 1434> 1435is the conventional name for a directory of additional configuration files 1436managed by external applications or the local administrator. The 1437filenames starting with decimal digits are sorted in lexicographic order 1438and used as additional configuration files. All of these files are in XML 1439format. The master fonts.conf file references this directory in an 1440<include> directive. 1441 </P 1442><P 1443><I 1444CLASS="EMPHASIS" 1445>fonts.dtd</I 1446> 1447is a DTD that describes the format of the configuration files. 1448 </P 1449><P 1450><I 1451CLASS="EMPHASIS" 1452>$XDG_CONFIG_HOME/fontconfig/conf.d</I 1453> and <I 1454CLASS="EMPHASIS" 1455>~/.fonts.conf.d</I 1456> 1457is the conventional name for a per-user directory of (typically 1458auto-generated) configuration files, although the 1459actual location is specified in the global fonts.conf file. please note that ~/.fonts.conf.d is deprecated now. it will not be read by default in the future version. 1460 </P 1461><P 1462><I 1463CLASS="EMPHASIS" 1464>$XDG_CONFIG_HOME/fontconfig/fonts.conf</I 1465> and <I 1466CLASS="EMPHASIS" 1467>~/.fonts.conf</I 1468> 1469is the conventional location for per-user font configuration, although the 1470actual location is specified in the global fonts.conf file. please note that ~/.fonts.conf is deprecated now. it will not be read by default in the future version. 1471 </P 1472><P 1473><I 1474CLASS="EMPHASIS" 1475>$XDG_CACHE_HOME/fontconfig/*.cache-*</I 1476> and <I 1477CLASS="EMPHASIS" 1478> ~/.fontconfig/*.cache-*</I 1479> 1480is the conventional repository of font information that isn't found in the 1481per-directory caches. This file is automatically maintained by fontconfig. please note that ~/.fontconfig/*.cache-* is deprecated now. it will not be read by default in the future version. 1482 </P 1483></DIV 1484><DIV 1485CLASS="REFSECT1" 1486><A 1487NAME="AEN262" 1488></A 1489><H2 1490>Environment variables</H2 1491><P 1492><I 1493CLASS="EMPHASIS" 1494>FONTCONFIG_FILE</I 1495> 1496is used to override the default configuration file. 1497 </P 1498><P 1499><I 1500CLASS="EMPHASIS" 1501>FONTCONFIG_PATH</I 1502> 1503is used to override the default configuration directory. 1504 </P 1505><P 1506><I 1507CLASS="EMPHASIS" 1508>FC_DEBUG</I 1509> 1510is used to output the detailed debugging messages. see <A 1511HREF="#DEBUG" 1512>Debugging Applications</A 1513> section for more details. 1514 </P 1515><P 1516><I 1517CLASS="EMPHASIS" 1518>FC_DBG_MATCH_FILTER</I 1519> 1520is used to filter out the patterns. this takes a comma-separated list of object names and effects only when FC_DEBUG has MATCH2. see <A 1521HREF="#DEBUG" 1522>Debugging Applications</A 1523> section for more details. 1524 </P 1525><P 1526><I 1527CLASS="EMPHASIS" 1528>FC_LANG</I 1529> 1530is used to specify the default language as the weak binding in the query. if this isn't set, the default language will be determined from current locale. 1531 </P 1532><P 1533><I 1534CLASS="EMPHASIS" 1535>FONTCONFIG_USE_MMAP</I 1536> 1537is used to control the use of mmap(2) for the cache files if available. this take a boolean value. fontconfig will checks if the cache files are stored on the filesystem that is safe to use mmap(2). explicitly setting this environment variable will causes skipping this check and enforce to use or not use mmap(2) anyway. 1538 </P 1539></DIV 1540><DIV 1541CLASS="REFSECT1" 1542><A 1543NAME="AEN278" 1544></A 1545><H2 1546>See Also</H2 1547><P 1548>fc-cat(1), fc-cache(1), fc-list(1), fc-match(1), fc-query(1) 1549 </P 1550></DIV 1551><DIV 1552CLASS="REFSECT1" 1553><A 1554NAME="AEN281" 1555></A 1556><H2 1557>Version</H2 1558><P 1559>Fontconfig version 2.12.4 1560 1561 </P 1562></DIV 1563></BODY 1564></HTML 1565>