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