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