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