diff options
Diffstat (limited to 'fontconfig/doc/fontconfig-user.sgml')
| -rw-r--r-- | fontconfig/doc/fontconfig-user.sgml | 1408 |
1 files changed, 704 insertions, 704 deletions
diff --git a/fontconfig/doc/fontconfig-user.sgml b/fontconfig/doc/fontconfig-user.sgml index efa01aa58..217feb97a 100644 --- a/fontconfig/doc/fontconfig-user.sgml +++ b/fontconfig/doc/fontconfig-user.sgml @@ -1,704 +1,704 @@ -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
-<!ENTITY version SYSTEM "version.sgml">
-<!ENTITY confdir SYSTEM "confdir.sgml">
-]>
-<!--
- Copyright © 2003 Keith Packard
-
- Permission to use, copy, modify, distribute, and sell this software and its
- documentation for any purpose is hereby granted without fee, provided that
- the above copyright notice appear in all copies and that both that
- copyright notice and this permission notice appear in supporting
- documentation, and that the name of the author(s) not be used in
- advertising or publicity pertaining to distribution of the software without
- specific, written prior permission. The authors make no
- representations about the suitability of this software for any purpose. It
- is provided "as is" without express or implied warranty.
-
- THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
- INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
- EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
- CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
- DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
- TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
--->
-<refentry>
-<refmeta>
- <refentrytitle>fonts-conf</refentrytitle>
- <manvolnum>5</manvolnum>
-</refmeta>
-<refnamediv>
- <refname>fonts.conf</refname>
- <refpurpose>Font configuration files</refpurpose>
-</refnamediv>
-<refsynopsisdiv>
-<synopsis>
- &confdir;/fonts.conf
- &confdir;/fonts.dtd
- &confdir;/conf.d
- ~/.fonts.conf.d
- ~/.fonts.conf
-</synopsis>
-</refsynopsisdiv>
-<refsect1><title>Description</title>
- <para>
-Fontconfig is a library designed to provide system-wide font configuration,
-customization and application access.
- </para>
-</refsect1>
-<refsect1><title>Functional Overview</title>
- <para>
-Fontconfig contains two essential modules, the configuration module which
-builds an internal configuration from XML files and the matching module
-which accepts font patterns and returns the nearest matching font.
- </para>
- <refsect2><title>Font Configuration</title>
- <para>
-The configuration module consists of the FcConfig datatype, libexpat and
-FcConfigParse which walks over an XML tree and amends a configuration with
-data found within. From an external perspective, configuration of the
-library consists of generating a valid XML tree and feeding that to
-FcConfigParse. The only other mechanism provided to applications for
-changing the running configuration is to add fonts and directories to the
-list of application-provided font files.
- </para><para>
-The intent is to make font configurations relatively static, and shared by
-as many applications as possible. It is hoped that this will lead to more
-stable font selection when passing names from one application to another.
-XML was chosen as a configuration file format because it provides a format
-which is easy for external agents to edit while retaining the correct
-structure and syntax.
- </para><para>
-Font configuration is separate from font matching; applications needing to
-do their own matching can access the available fonts from the library and
-perform private matching. The intent is to permit applications to pick and
-choose appropriate functionality from the library instead of forcing them to
-choose between this library and a private configuration mechanism. The hope
-is that this will ensure that configuration of fonts for all applications
-can be centralized in one place. Centralizing font configuration will
-simplify and regularize font installation and customization.
- </para>
- </refsect2>
- <refsect2>
- <title>Font Properties</title>
- <para>
-While font patterns may contain essentially any properties, there are some
-well known properties with associated types. Fontconfig uses some of these
-properties for font matching and font completion. Others are provided as a
-convenience for the applications' rendering mechanism.
- </para>
- <programlisting>
- Property Type Description
- --------------------------------------------------------------
- family String Font family names
- familylang String Languages corresponding to each family
- style String Font style. Overrides weight and slant
- stylelang String Languages corresponding to each style
- fullname String Font full names (often includes style)
- fullnamelang String Languages corresponding to each fullname
- slant Int Italic, oblique or roman
- weight Int Light, medium, demibold, bold or black
- size Double Point size
- width Int Condensed, normal or expanded
- aspect Double Stretches glyphs horizontally before hinting
- pixelsize Double Pixel size
- spacing Int Proportional, dual-width, monospace or charcell
- foundry String Font foundry name
- antialias Bool Whether glyphs can be antialiased
- hinting Bool Whether the rasterizer should use hinting
- hintstyle Int Automatic hinting style
- verticallayout Bool Use vertical layout
- autohint Bool Use autohinter instead of normal hinter
- globaladvance Bool Use font global advance data
- file String The filename holding the font
- index Int The index of the font within the file
- ftface FT_Face Use the specified FreeType face object
- rasterizer String Which rasterizer is in use
- outline Bool Whether the glyphs are outlines
- scalable Bool Whether glyphs can be scaled
- scale Double Scale factor for point->pixel conversions
- dpi Double Target dots per inch
- rgba Int unknown, rgb, bgr, vrgb, vbgr,
- none - subpixel geometry
- lcdfilter Int Type of LCD filter
- minspace Bool Eliminate leading from line spacing
- charset CharSet Unicode chars encoded by the font
- lang String List of RFC-3066-style languages this
- font supports
- fontversion Int Version number of the font
- capability String List of layout capabilities in the font
- embolden Bool Rasterizer should synthetically embolden the font
- </programlisting>
- </refsect2>
- <refsect2>
- <title>Font Matching</title>
- <para>
-Fontconfig performs matching by measuring the distance from a provided
-pattern to all of the available fonts in the system. The closest matching
-font is selected. This ensures that a font will always be returned, but
-doesn't ensure that it is anything like the requested pattern.
- </para><para>
-Font matching starts with an application constructed pattern. The desired
-attributes of the resulting font are collected together in a pattern. Each
-property of the pattern can contain one or more values; these are listed in
-priority order; matches earlier in the list are considered "closer" than
-matches later in the list.
- </para><para>
-The initial pattern is modified by applying the list of editing instructions
-specific to patterns found in the configuration; each consists of a match
-predicate and a set of editing operations. They are executed in the order
-they appeared in the configuration. Each match causes the associated
-sequence of editing operations to be applied.
- </para><para>
-After the pattern has been edited, a sequence of default substitutions are
-performed to canonicalize the set of available properties; this avoids the
-need for the lower layers to constantly provide default values for various
-font properties during rendering.
- </para><para>
-The canonical font pattern is finally matched against all available fonts.
-The distance from the pattern to the font is measured for each of several
-properties: foundry, charset, family, lang, spacing, pixelsize, style,
-slant, weight, antialias, rasterizer and outline. This list is in priority
-order -- results of comparing earlier elements of this list weigh more
-heavily than later elements.
- </para><para>
-There is one special case to this rule; family names are split into two
-bindings; strong and weak. Strong family names are given greater precedence
-in the match than lang elements while weak family names are given lower
-precedence than lang elements. This permits the document language to drive
-font selection when any document specified font is unavailable.
- </para><para>
-The pattern representing that font is augmented to include any properties
-found in the pattern but not found in the font itself; this permits the
-application to pass rendering instructions or any other data through the
-matching system. Finally, the list of editing instructions specific to
-fonts found in the configuration are applied to the pattern. This modified
-pattern is returned to the application.
- </para><para>
-The return value contains sufficient information to locate and rasterize the
-font, including the file name, pixel size and other rendering data. As
-none of the information involved pertains to the FreeType library,
-applications are free to use any rasterization engine or even to take
-the identified font file and access it directly.
- </para><para>
-The match/edit sequences in the configuration are performed in two passes
-because there are essentially two different operations necessary -- the
-first is to modify how fonts are selected; aliasing families and adding
-suitable defaults. The second is to modify how the selected fonts are
-rasterized. Those must apply to the selected font, not the original pattern
-as false matches will often occur.
- </para>
- </refsect2>
- <refsect2><title>Font Names</title>
- <para>
-Fontconfig provides a textual representation for patterns that the library
-can both accept and generate. The representation is in three parts, first a
-list of family names, second a list of point sizes and finally a list of
-additional properties:
- </para>
- <programlisting>
- <families>-<point sizes>:<name1>=<values1>:<name2>=<values2>...
- </programlisting>
- <para>
-Values in a list are separated with commas. The name needn't include either
-families or point sizes; they can be elided. In addition, there are
-symbolic constants that simultaneously indicate both a name and a value.
-Here are some examples:
- </para>
- <programlisting>
- Name Meaning
- ----------------------------------------------------------
- Times-12 12 point Times Roman
- Times-12:bold 12 point Times Bold
- Courier:italic Courier Italic in the default size
- Monospace:matrix=1 .1 0 1 The users preferred monospace font
- with artificial obliquing
- </programlisting>
- <para>
-The '\', '-', ':' and ',' characters in family names must be preceded by a
-'\' character to avoid having them misinterpreted. Similarly, values
-containing '\', '=', '_', ':' and ',' must also have them preceded by a
-'\' character. The '\' characters are stripped out of the family name and
-values as the font name is read.
- </para>
- </refsect2>
-</refsect1>
-<refsect1><title>Debugging Applications</title>
- <para>
-To help diagnose font and applications problems, fontconfig is built with a
-large amount of internal debugging left enabled. It is controlled by means
-of the FC_DEBUG environment variable. The value of this variable is
-interpreted as a number, and each bit within that value controls different
-debugging messages.
- </para>
- <programlisting>
- Name Value Meaning
- ---------------------------------------------------------
- MATCH 1 Brief information about font matching
- MATCHV 2 Extensive font matching information
- EDIT 4 Monitor match/test/edit execution
- FONTSET 8 Track loading of font information at startup
- CACHE 16 Watch cache files being written
- CACHEV 32 Extensive cache file writing information
- PARSE 64 (no longer in use)
- SCAN 128 Watch font files being scanned to build caches
- SCANV 256 Verbose font file scanning information
- MEMORY 512 Monitor fontconfig memory usage
- CONFIG 1024 Monitor which config files are loaded
- LANGSET 2048 Dump char sets used to construct lang values
- OBJTYPES 4096 Display message when value typechecks fail
- </programlisting>
- <para>
-Add the value of the desired debug levels together and assign that (in
-base 10) to the FC_DEBUG environment variable before running the
-application. Output from these statements is sent to stdout.
- </para>
-</refsect1>
-<refsect1><title>Lang Tags</title>
- <para>
-Each font in the database contains a list of languages it supports. This is
-computed by comparing the Unicode coverage of the font with the orthography
-of each language. Languages are tagged using an RFC-3066 compatible naming
-and occur in two parts -- the ISO 639 language tag followed a hyphen and then
-by the ISO 3166 country code. The hyphen and country code may be elided.
- </para><para>
-Fontconfig has orthographies for several languages built into the library.
-No provision has been made for adding new ones aside from rebuilding the
-library. It currently supports 122 of the 139 languages named in ISO 639-1,
-141 of the languages with two-letter codes from ISO 639-2 and another 30
-languages with only three-letter codes. Languages with both two and three
-letter codes are provided with only the two letter code.
- </para><para>
-For languages used in multiple territories with radically different
-character sets, fontconfig includes per-territory orthographies. This
-includes Azerbaijani, Kurdish, Pashto, Tigrinya and Chinese.
- </para>
-</refsect1>
-<refsect1><title>Configuration File Format</title>
- <para>
-Configuration files for fontconfig are stored in XML format; this
-format makes external configuration tools easier to write and ensures that
-they will generate syntactically correct configuration files. As XML
-files are plain text, they can also be manipulated by the expert user using
-a text editor.
- </para><para>
-The fontconfig document type definition resides in the external entity
-"fonts.dtd"; this is normally stored in the default font configuration
-directory (&confdir;). Each configuration file should contain the
-following structure:
- <programlisting>
- <?xml version="1.0"?>
- <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
- <fontconfig>
- ...
- </fontconfig>
- </programlisting>
- </para>
-<refsect2><title><literal><fontconfig></literal></title><para>
-This is the top level element for a font configuration and can contain
-<literal><dir></literal>, <literal><cache></literal>, <literal><include></literal>, <literal><match></literal> and <literal><alias></literal> elements in any order.
- </para></refsect2>
- <refsect2><title><literal><dir></literal></title><para>
-This element contains a directory name which will be scanned for font files
-to include in the set of available fonts.
- </para></refsect2>
- <refsect2><title><literal><cache></literal></title><para>
-This element contains a file name for the per-user cache of font
-information. If it starts with '~', it refers to a file in the users
-home directory. This file is used to hold information about fonts that
-isn't present in the per-directory cache files. It is automatically
-maintained by the fontconfig library. The default for this file
-is ``~/.fonts.cache-<literal><version></literal>'', where <literal><version></literal> is the font configuration
-file version number (currently 2).
- </para></refsect2>
- <refsect2><title><literal><include ignore_missing="no"></literal></title><para>
-This element contains the name of an additional configuration file or
-directory. If a directory, every file within that directory starting with an
-ASCII digit (U+0030 - U+0039) and ending with the string ``.conf'' will be processed in sorted order. When
-the XML datatype is traversed by FcConfigParse, the contents of the file(s)
-will also be incorporated into the configuration by passing the filename(s) to
-FcConfigLoadAndParse. If 'ignore_missing' is set to "yes" instead of the
-default "no", a missing file or directory will elicit no warning message from
-the library.
- </para></refsect2>
- <refsect2><title><literal><config></literal></title><para>
-This element provides a place to consolidate additional configuration
-information. <literal><config></literal> can contain <literal><blank></literal> and <literal><rescan></literal> elements in any
-order.
- </para></refsect2>
- <refsect2><title><literal><blank></literal></title><para>
-Fonts often include "broken" glyphs which appear in the encoding but are
-drawn as blanks on the screen. Within the <literal><blank></literal> element, place each
-Unicode characters which is supposed to be blank in an <literal><int></literal> element.
-Characters outside of this set which are drawn as blank will be elided from
-the set of characters supported by the font.
- </para></refsect2>
- <refsect2><title><literal><rescan></literal></title><para>
-The <literal><rescan></literal> element holds an <literal><int></literal> element which indicates the default
-interval between automatic checks for font configuration changes.
-Fontconfig will validate all of the configuration files and directories and
-automatically rebuild the internal datastructures when this interval passes.
- </para></refsect2>
- <refsect2><title><literal><selectfont></literal></title><para>
-This element is used to black/white list fonts from being listed or matched
-against. It holds acceptfont and rejectfont elements.
- </para></refsect2>
- <refsect2><title><literal><acceptfont></literal></title><para>
-Fonts matched by an acceptfont element are "whitelisted"; such fonts are
-explicitly included in the set of fonts used to resolve list and match
-requests; including them in this list protects them from being "blacklisted"
-by a rejectfont element. Acceptfont elements include glob and pattern
-elements which are used to match fonts.
- </para></refsect2>
- <refsect2><title><literal><rejectfont></literal></title><para>
-Fonts matched by an rejectfont element are "blacklisted"; such fonts are
-excluded from the set of fonts used to resolve list and match requests as if
-they didn't exist in the system. Rejectfont elements include glob and
-pattern elements which are used to match fonts.
- </para></refsect2>
- <refsect2><title><literal><glob></literal></title><para>
-Glob elements hold shell-style filename matching patterns (including ? and
-*) which match fonts based on their complete pathnames. This can be used to
-exclude a set of directories (/usr/share/fonts/uglyfont*), or particular
-font file types (*.pcf.gz), but the latter mechanism relies rather heavily
-on filenaming conventions which can't be relied upon. Note that globs
-only apply to directories, not to individual fonts.
- </para></refsect2>
- <refsect2><title><literal><pattern></literal></title><para>
-Pattern elements perform list-style matching on incoming fonts; that is,
-they hold a list of elements and associated values. If all of those
-elements have a matching value, then the pattern matches the font. This can
-be used to select fonts based on attributes of the font (scalable, bold,
-etc), which is a more reliable mechanism than using file extensions.
-Pattern elements include patelt elements.
- </para></refsect2>
- <refsect2><title><literal><patelt name="property"></literal></title><para>
-Patelt elements hold a single pattern element and list of values. They must
-have a 'name' attribute which indicates the pattern element name. Patelt
-elements include int, double, string, matrix, bool, charset and const
-elements.
- </para></refsect2>
- <refsect2><title><literal><match target="pattern"></literal></title><para>
-This element holds first a (possibly empty) list of <literal><test></literal> elements and then
-a (possibly empty) list of <literal><edit></literal> elements. Patterns which match all of the
-tests are subjected to all the edits. If 'target' is set to "font" instead
-of the default "pattern", then this element applies to the font name
-resulting from a match rather than a font pattern to be matched. If 'target'
-is set to "scan", then this element applies when the font is scanned to
-build the fontconfig database.
- </para></refsect2>
- <refsect2><title><literal><test qual="any" name="property" target="default" compare="eq"></literal></title><para>
-This element contains a single value which is compared with the target
-('pattern', 'font', 'scan' or 'default') property "property" (substitute any of the property names seen
-above). 'compare' can be one of "eq", "not_eq", "less", "less_eq", "more", or
-"more_eq". 'qual' may either be the default, "any", in which case the match
-succeeds if any value associated with the property matches the test value, or
-"all", in which case all of the values associated with the property must
-match the test value. When used in a <match target="font"> element,
-the target= attribute in the <test> element selects between matching
-the original pattern or the font. "default" selects whichever target the
-outer <match> element has selected.
- </para></refsect2>
- <refsect2><title><literal><edit name="property" mode="assign" binding="weak"></literal></title><para>
-This element contains a list of expression elements (any of the value or
-operator elements). The expression elements are evaluated at run-time and
-modify the property "property". The modification depends on whether
-"property" was matched by one of the associated <literal><test></literal> elements, if so, the
-modification may affect the first matched value. Any values inserted into
-the property are given the indicated binding ("strong", "weak" or "same")
-with "same" binding using the value from the matched pattern element.
-'mode' is one of:
- <programlisting>
- Mode With Match Without Match
- ---------------------------------------------------------------------
- "assign" Replace matching value Replace all values
- "assign_replace" Replace all values Replace all values
- "prepend" Insert before matching Insert at head of list
- "prepend_first" Insert at head of list Insert at head of list
- "append" Append after matching Append at end of list
- "append_last" Append at end of list Append at end of list
- </programlisting>
- </para></refsect2>
- <refsect2><title><literal><int></literal>, <literal><double></literal>, <literal><string></literal>, <literal><bool></literal></title><para>
-These elements hold a single value of the indicated type. <literal><bool></literal>
-elements hold either true or false. An important limitation exists in
-the parsing of floating point numbers -- fontconfig requires that
-the mantissa start with a digit, not a decimal point, so insert a leading
-zero for purely fractional values (e.g. use 0.5 instead of .5 and -0.5
-instead of -.5).
- </para></refsect2>
- <refsect2><title><literal><matrix></literal></title><para>
-This element holds the four <literal><double></literal> elements of an affine
-transformation.
- </para></refsect2>
- <refsect2><title><literal><range></literal></title><para>
-This element holds the two <literal><int></literal> elements of a range
-representation.
- </para></refsect2>
- <refsect2><title><literal><charset></literal></title><para>
-This element holds at least one <literal><int></literal> element of
-an Unicode code point or more.
- </para></refsect2>
- <refsect2><title><literal><langset></literal></title><para>
-This element holds at least one <literal><string></literal> element of
-a RFC-3066-style languages or more.
- </para></refsect2>
- <refsect2><title><literal><name></literal></title><para>
-Holds a property name. Evaluates to the first value from the property of
-the font, not the pattern.
- </para></refsect2>
- <refsect2><title><literal><const></literal></title><para>
-Holds the name of a constant; these are always integers and serve as
-symbolic names for common font values:
- <programlisting>
- Constant Property Value
- -------------------------------------
- thin weight 0
- extralight weight 40
- ultralight weight 40
- light weight 50
- book weight 75
- regular weight 80
- normal weight 80
- medium weight 100
- demibold weight 180
- semibold weight 180
- bold weight 200
- extrabold weight 205
- black weight 210
- heavy weight 210
- roman slant 0
- italic slant 100
- oblique slant 110
- ultracondensed width 50
- extracondensed width 63
- condensed width 75
- semicondensed width 87
- normal width 100
- semiexpanded width 113
- expanded width 125
- extraexpanded width 150
- ultraexpanded width 200
- proportional spacing 0
- dual spacing 90
- mono spacing 100
- charcell spacing 110
- unknown rgba 0
- rgb rgba 1
- bgr rgba 2
- vrgb rgba 3
- vbgr rgba 4
- none rgba 5
- lcdnone lcdfilter 0
- lcddefault lcdfilter 1
- lcdlight lcdfilter 2
- lcdlegacy lcdfilter 3
- hintnone hintstyle 0
- hintslight hintstyle 1
- hintmedium hintstyle 2
- hintfull hintstyle 3
- </programlisting>
- </para>
- </refsect2>
- <refsect2>
- <title><literal><or></literal>, <literal><and></literal>, <literal><plus></literal>, <literal><minus></literal>, <literal><times></literal>, <literal><divide></literal></title>
- <para>
-These elements perform the specified operation on a list of expression
-elements. <literal><or></literal> and <literal><and></literal> are boolean, not bitwise.
- </para>
- </refsect2>
- <refsect2>
- <title><literal><eq></literal>, <literal><not_eq></literal>, <literal><less></literal>, <literal><less_eq></literal>, <literal><more></literal>, <literal><more_eq></literal></title>
- <para>
-These elements compare two values, producing a boolean result.
- </para></refsect2>
- <refsect2><title><literal><not></literal></title><para>
-Inverts the boolean sense of its one expression element
- </para></refsect2>
- <refsect2><title><literal><if></literal></title><para>
-This element takes three expression elements; if the value of the first is
-true, it produces the value of the second, otherwise it produces the value
-of the third.
- </para></refsect2>
- <refsect2><title><literal><alias></literal></title><para>
-Alias elements provide a shorthand notation for the set of common match
-operations needed to substitute one font family for another. They contain a
-<literal><family></literal> element followed by optional <literal><prefer></literal>, <literal><accept></literal> and <literal><default></literal>
-elements. Fonts matching the <literal><family></literal> element are edited to prepend the
-list of <literal><prefer></literal>ed families before the matching <literal><family></literal>, append the
-<literal><accept></literal>able families after the matching <literal><family></literal> and append the <literal><default></literal>
-families to the end of the family list.
- </para></refsect2>
- <refsect2><title><literal><family></literal></title><para>
-Holds a single font family name
- </para></refsect2>
- <refsect2><title><literal><prefer></literal>, <literal><accept></literal>, <literal><default></literal></title><para>
-These hold a list of <literal><family></literal> elements to be used by the <literal><alias></literal> element.
- </para></refsect2>
-</refsect1>
-<refsect1><title>EXAMPLE CONFIGURATION FILE</title>
- <refsect2><title>System configuration file</title>
- <para>
-This is an example of a system-wide configuration file
- </para>
- <programlisting>
-<?xml version="1.0"?>
-<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
-<!-- &confdir;/fonts.conf file to configure system font access -->
-<fontconfig>
-<!--
- Find fonts in these directories
--->
-<dir>/usr/share/fonts</dir>
-<dir>/usr/X11R6/lib/X11/fonts</dir>
-
-<!--
- Accept deprecated 'mono' alias, replacing it with 'monospace'
--->
-<match target="pattern">
- <test qual="any" name="family"><string>mono</string></test>
- <edit name="family" mode="assign"><string>monospace</string></edit>
-</match>
-
-<!--
- Names not including any well known alias are given 'sans'
--->
-<match target="pattern">
- <test qual="all" name="family" mode="not_eq">sans</test>
- <test qual="all" name="family" mode="not_eq">serif</test>
- <test qual="all" name="family" mode="not_eq">monospace</test>
- <edit name="family" mode="append_last"><string>sans</string></edit>
-</match>
-
-<!--
- Load per-user customization file, but don't complain
- if it doesn't exist
--->
-<include ignore_missing="yes">~/.fonts.conf</include>
-
-<!--
- Load local customization files, but don't complain
- if there aren't any
--->
-<include ignore_missing="yes">conf.d</include>
-<include ignore_missing="yes">local.conf</include>
-
-<!--
- Alias well known font names to available TrueType fonts.
- These substitute TrueType faces for similar Type1
- faces to improve screen appearance.
--->
-<alias>
- <family>Times</family>
- <prefer><family>Times New Roman</family></prefer>
- <default><family>serif</family></default>
-</alias>
-<alias>
- <family>Helvetica</family>
- <prefer><family>Arial</family></prefer>
- <default><family>sans</family></default>
-</alias>
-<alias>
- <family>Courier</family>
- <prefer><family>Courier New</family></prefer>
- <default><family>monospace</family></default>
-</alias>
-
-<!--
- Provide required aliases for standard names
- Do these after the users configuration file so that
- any aliases there are used preferentially
--->
-<alias>
- <family>serif</family>
- <prefer><family>Times New Roman</family></prefer>
-</alias>
-<alias>
- <family>sans</family>
- <prefer><family>Arial</family></prefer>
-</alias>
-<alias>
- <family>monospace</family>
- <prefer><family>Andale Mono</family></prefer>
-</alias>
-</fontconfig>
- </programlisting>
- </refsect2>
- <refsect2><title>User configuration file</title>
- <para>
-This is an example of a per-user configuration file that lives in
-~/.fonts.conf
- </para>
- <programlisting>
-<?xml version="1.0"?>
-<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
-<!-- ~/.fonts.conf for per-user font configuration -->
-<fontconfig>
-
-<!--
- Private font directory
--->
-<dir>~/.fonts</dir>
-
-<!--
- use rgb sub-pixel ordering to improve glyph appearance on
- LCD screens. Changes affecting rendering, but not matching
- should always use target="font".
--->
-<match target="font">
- <edit name="rgba" mode="assign"><const>rgb</const></edit>
-</match>
-</fontconfig>
- </programlisting>
- </refsect2>
-</refsect1>
-<refsect1><title>Files</title>
- <para>
-<emphasis>fonts.conf</emphasis>
-contains configuration information for the fontconfig library
-consisting of directories to look at for font information as well as
-instructions on editing program specified font patterns before attempting to
-match the available fonts. It is in XML format.
- </para>
- <para>
-<emphasis>conf.d</emphasis>
-is the conventional name for a directory of additional configuration files
-managed by external applications or the local administrator. The
-filenames starting with decimal digits are sorted in lexicographic order
-and used as additional configuration files. All of these files are in XML
-format. The master fonts.conf file references this directory in an
-<include> directive.
- </para>
- <para>
-<emphasis>fonts.dtd</emphasis>
-is a DTD that describes the format of the configuration files.
- </para>
- <para>
-<emphasis>~/.fonts.conf.d</emphasis>
-is the conventional name for a per-user directory of (typically
-auto-generated) configuration files, although the
-actual location is specified in the global fonts.conf file.
- </para>
- <para>
-<emphasis>~/.fonts.conf</emphasis>
-is the conventional location for per-user font configuration, although the
-actual location is specified in the global fonts.conf file.
- </para>
- <para>
-<emphasis> ~/.fonts.cache-*</emphasis>
-is the conventional repository of font information that isn't found in the
-per-directory caches. This file is automatically maintained by fontconfig.
- </para>
-</refsect1>
-<refsect1><title>See Also</title>
- <para>
-fc-cat(1), fc-cache(1), fc-list(1), fc-match(1), fc-query(1)
- </para>
-</refsect1>
-<refsect1><title>Version</title>
- <para>
-Fontconfig version &version;
- </para>
-</refsect1>
-</refentry>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ +<!ENTITY version SYSTEM "version.sgml"> +<!ENTITY confdir SYSTEM "confdir.sgml"> +]> +<!-- + Copyright © 2003 Keith Packard + + Permission to use, copy, modify, distribute, and sell this software and its + documentation for any purpose is hereby granted without fee, provided that + the above copyright notice appear in all copies and that both that + copyright notice and this permission notice appear in supporting + documentation, and that the name of the author(s) not be used in + advertising or publicity pertaining to distribution of the software without + specific, written prior permission. The authors make no + representations about the suitability of this software for any purpose. It + is provided "as is" without express or implied warranty. + + THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + PERFORMANCE OF THIS SOFTWARE. +--> +<refentry> +<refmeta> + <refentrytitle>fonts-conf</refentrytitle> + <manvolnum>5</manvolnum> +</refmeta> +<refnamediv> + <refname>fonts.conf</refname> + <refpurpose>Font configuration files</refpurpose> +</refnamediv> +<refsynopsisdiv> +<synopsis> + &confdir;/fonts.conf + &confdir;/fonts.dtd + &confdir;/conf.d + ~/.fonts.conf.d + ~/.fonts.conf +</synopsis> +</refsynopsisdiv> +<refsect1><title>Description</title> + <para> +Fontconfig is a library designed to provide system-wide font configuration, +customization and application access. + </para> +</refsect1> +<refsect1><title>Functional Overview</title> + <para> +Fontconfig contains two essential modules, the configuration module which +builds an internal configuration from XML files and the matching module +which accepts font patterns and returns the nearest matching font. + </para> + <refsect2><title>Font Configuration</title> + <para> +The configuration module consists of the FcConfig datatype, libexpat and +FcConfigParse which walks over an XML tree and amends a configuration with +data found within. From an external perspective, configuration of the +library consists of generating a valid XML tree and feeding that to +FcConfigParse. The only other mechanism provided to applications for +changing the running configuration is to add fonts and directories to the +list of application-provided font files. + </para><para> +The intent is to make font configurations relatively static, and shared by +as many applications as possible. It is hoped that this will lead to more +stable font selection when passing names from one application to another. +XML was chosen as a configuration file format because it provides a format +which is easy for external agents to edit while retaining the correct +structure and syntax. + </para><para> +Font configuration is separate from font matching; applications needing to +do their own matching can access the available fonts from the library and +perform private matching. The intent is to permit applications to pick and +choose appropriate functionality from the library instead of forcing them to +choose between this library and a private configuration mechanism. The hope +is that this will ensure that configuration of fonts for all applications +can be centralized in one place. Centralizing font configuration will +simplify and regularize font installation and customization. + </para> + </refsect2> + <refsect2> + <title>Font Properties</title> + <para> +While font patterns may contain essentially any properties, there are some +well known properties with associated types. Fontconfig uses some of these +properties for font matching and font completion. Others are provided as a +convenience for the applications' rendering mechanism. + </para> + <programlisting> + Property Type Description + -------------------------------------------------------------- + family String Font family names + familylang String Languages corresponding to each family + style String Font style. Overrides weight and slant + stylelang String Languages corresponding to each style + fullname String Font full names (often includes style) + fullnamelang String Languages corresponding to each fullname + slant Int Italic, oblique or roman + weight Int Light, medium, demibold, bold or black + size Double Point size + width Int Condensed, normal or expanded + aspect Double Stretches glyphs horizontally before hinting + pixelsize Double Pixel size + spacing Int Proportional, dual-width, monospace or charcell + foundry String Font foundry name + antialias Bool Whether glyphs can be antialiased + hinting Bool Whether the rasterizer should use hinting + hintstyle Int Automatic hinting style + verticallayout Bool Use vertical layout + autohint Bool Use autohinter instead of normal hinter + globaladvance Bool Use font global advance data + file String The filename holding the font + index Int The index of the font within the file + ftface FT_Face Use the specified FreeType face object + rasterizer String Which rasterizer is in use + outline Bool Whether the glyphs are outlines + scalable Bool Whether glyphs can be scaled + scale Double Scale factor for point->pixel conversions + dpi Double Target dots per inch + rgba Int unknown, rgb, bgr, vrgb, vbgr, + none - subpixel geometry + lcdfilter Int Type of LCD filter + minspace Bool Eliminate leading from line spacing + charset CharSet Unicode chars encoded by the font + lang String List of RFC-3066-style languages this + font supports + fontversion Int Version number of the font + capability String List of layout capabilities in the font + embolden Bool Rasterizer should synthetically embolden the font + </programlisting> + </refsect2> + <refsect2> + <title>Font Matching</title> + <para> +Fontconfig performs matching by measuring the distance from a provided +pattern to all of the available fonts in the system. The closest matching +font is selected. This ensures that a font will always be returned, but +doesn't ensure that it is anything like the requested pattern. + </para><para> +Font matching starts with an application constructed pattern. The desired +attributes of the resulting font are collected together in a pattern. Each +property of the pattern can contain one or more values; these are listed in +priority order; matches earlier in the list are considered "closer" than +matches later in the list. + </para><para> +The initial pattern is modified by applying the list of editing instructions +specific to patterns found in the configuration; each consists of a match +predicate and a set of editing operations. They are executed in the order +they appeared in the configuration. Each match causes the associated +sequence of editing operations to be applied. + </para><para> +After the pattern has been edited, a sequence of default substitutions are +performed to canonicalize the set of available properties; this avoids the +need for the lower layers to constantly provide default values for various +font properties during rendering. + </para><para> +The canonical font pattern is finally matched against all available fonts. +The distance from the pattern to the font is measured for each of several +properties: foundry, charset, family, lang, spacing, pixelsize, style, +slant, weight, antialias, rasterizer and outline. This list is in priority +order -- results of comparing earlier elements of this list weigh more +heavily than later elements. + </para><para> +There is one special case to this rule; family names are split into two +bindings; strong and weak. Strong family names are given greater precedence +in the match than lang elements while weak family names are given lower +precedence than lang elements. This permits the document language to drive +font selection when any document specified font is unavailable. + </para><para> +The pattern representing that font is augmented to include any properties +found in the pattern but not found in the font itself; this permits the +application to pass rendering instructions or any other data through the +matching system. Finally, the list of editing instructions specific to +fonts found in the configuration are applied to the pattern. This modified +pattern is returned to the application. + </para><para> +The return value contains sufficient information to locate and rasterize the +font, including the file name, pixel size and other rendering data. As +none of the information involved pertains to the FreeType library, +applications are free to use any rasterization engine or even to take +the identified font file and access it directly. + </para><para> +The match/edit sequences in the configuration are performed in two passes +because there are essentially two different operations necessary -- the +first is to modify how fonts are selected; aliasing families and adding +suitable defaults. The second is to modify how the selected fonts are +rasterized. Those must apply to the selected font, not the original pattern +as false matches will often occur. + </para> + </refsect2> + <refsect2><title>Font Names</title> + <para> +Fontconfig provides a textual representation for patterns that the library +can both accept and generate. The representation is in three parts, first a +list of family names, second a list of point sizes and finally a list of +additional properties: + </para> + <programlisting> + <families>-<point sizes>:<name1>=<values1>:<name2>=<values2>... + </programlisting> + <para> +Values in a list are separated with commas. The name needn't include either +families or point sizes; they can be elided. In addition, there are +symbolic constants that simultaneously indicate both a name and a value. +Here are some examples: + </para> + <programlisting> + Name Meaning + ---------------------------------------------------------- + Times-12 12 point Times Roman + Times-12:bold 12 point Times Bold + Courier:italic Courier Italic in the default size + Monospace:matrix=1 .1 0 1 The users preferred monospace font + with artificial obliquing + </programlisting> + <para> +The '\', '-', ':' and ',' characters in family names must be preceded by a +'\' character to avoid having them misinterpreted. Similarly, values +containing '\', '=', '_', ':' and ',' must also have them preceded by a +'\' character. The '\' characters are stripped out of the family name and +values as the font name is read. + </para> + </refsect2> +</refsect1> +<refsect1><title>Debugging Applications</title> + <para> +To help diagnose font and applications problems, fontconfig is built with a +large amount of internal debugging left enabled. It is controlled by means +of the FC_DEBUG environment variable. The value of this variable is +interpreted as a number, and each bit within that value controls different +debugging messages. + </para> + <programlisting> + Name Value Meaning + --------------------------------------------------------- + MATCH 1 Brief information about font matching + MATCHV 2 Extensive font matching information + EDIT 4 Monitor match/test/edit execution + FONTSET 8 Track loading of font information at startup + CACHE 16 Watch cache files being written + CACHEV 32 Extensive cache file writing information + PARSE 64 (no longer in use) + SCAN 128 Watch font files being scanned to build caches + SCANV 256 Verbose font file scanning information + MEMORY 512 Monitor fontconfig memory usage + CONFIG 1024 Monitor which config files are loaded + LANGSET 2048 Dump char sets used to construct lang values + OBJTYPES 4096 Display message when value typechecks fail + </programlisting> + <para> +Add the value of the desired debug levels together and assign that (in +base 10) to the FC_DEBUG environment variable before running the +application. Output from these statements is sent to stdout. + </para> +</refsect1> +<refsect1><title>Lang Tags</title> + <para> +Each font in the database contains a list of languages it supports. This is +computed by comparing the Unicode coverage of the font with the orthography +of each language. Languages are tagged using an RFC-3066 compatible naming +and occur in two parts -- the ISO 639 language tag followed a hyphen and then +by the ISO 3166 country code. The hyphen and country code may be elided. + </para><para> +Fontconfig has orthographies for several languages built into the library. +No provision has been made for adding new ones aside from rebuilding the +library. It currently supports 122 of the 139 languages named in ISO 639-1, +141 of the languages with two-letter codes from ISO 639-2 and another 30 +languages with only three-letter codes. Languages with both two and three +letter codes are provided with only the two letter code. + </para><para> +For languages used in multiple territories with radically different +character sets, fontconfig includes per-territory orthographies. This +includes Azerbaijani, Kurdish, Pashto, Tigrinya and Chinese. + </para> +</refsect1> +<refsect1><title>Configuration File Format</title> + <para> +Configuration files for fontconfig are stored in XML format; this +format makes external configuration tools easier to write and ensures that +they will generate syntactically correct configuration files. As XML +files are plain text, they can also be manipulated by the expert user using +a text editor. + </para><para> +The fontconfig document type definition resides in the external entity +"fonts.dtd"; this is normally stored in the default font configuration +directory (&confdir;). Each configuration file should contain the +following structure: + <programlisting> + <?xml version="1.0"?> + <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> + <fontconfig> + ... + </fontconfig> + </programlisting> + </para> +<refsect2><title><literal><fontconfig></literal></title><para> +This is the top level element for a font configuration and can contain +<literal><dir></literal>, <literal><cache></literal>, <literal><include></literal>, <literal><match></literal> and <literal><alias></literal> elements in any order. + </para></refsect2> + <refsect2><title><literal><dir></literal></title><para> +This element contains a directory name which will be scanned for font files +to include in the set of available fonts. + </para></refsect2> + <refsect2><title><literal><cache></literal></title><para> +This element contains a file name for the per-user cache of font +information. If it starts with '~', it refers to a file in the users +home directory. This file is used to hold information about fonts that +isn't present in the per-directory cache files. It is automatically +maintained by the fontconfig library. The default for this file +is ``~/.fonts.cache-<literal><version></literal>'', where <literal><version></literal> is the font configuration +file version number (currently 2). + </para></refsect2> + <refsect2><title><literal><include ignore_missing="no"></literal></title><para> +This element contains the name of an additional configuration file or +directory. If a directory, every file within that directory starting with an +ASCII digit (U+0030 - U+0039) and ending with the string ``.conf'' will be processed in sorted order. When +the XML datatype is traversed by FcConfigParse, the contents of the file(s) +will also be incorporated into the configuration by passing the filename(s) to +FcConfigLoadAndParse. If 'ignore_missing' is set to "yes" instead of the +default "no", a missing file or directory will elicit no warning message from +the library. + </para></refsect2> + <refsect2><title><literal><config></literal></title><para> +This element provides a place to consolidate additional configuration +information. <literal><config></literal> can contain <literal><blank></literal> and <literal><rescan></literal> elements in any +order. + </para></refsect2> + <refsect2><title><literal><blank></literal></title><para> +Fonts often include "broken" glyphs which appear in the encoding but are +drawn as blanks on the screen. Within the <literal><blank></literal> element, place each +Unicode characters which is supposed to be blank in an <literal><int></literal> element. +Characters outside of this set which are drawn as blank will be elided from +the set of characters supported by the font. + </para></refsect2> + <refsect2><title><literal><rescan></literal></title><para> +The <literal><rescan></literal> element holds an <literal><int></literal> element which indicates the default +interval between automatic checks for font configuration changes. +Fontconfig will validate all of the configuration files and directories and +automatically rebuild the internal datastructures when this interval passes. + </para></refsect2> + <refsect2><title><literal><selectfont></literal></title><para> +This element is used to black/white list fonts from being listed or matched +against. It holds acceptfont and rejectfont elements. + </para></refsect2> + <refsect2><title><literal><acceptfont></literal></title><para> +Fonts matched by an acceptfont element are "whitelisted"; such fonts are +explicitly included in the set of fonts used to resolve list and match +requests; including them in this list protects them from being "blacklisted" +by a rejectfont element. Acceptfont elements include glob and pattern +elements which are used to match fonts. + </para></refsect2> + <refsect2><title><literal><rejectfont></literal></title><para> +Fonts matched by an rejectfont element are "blacklisted"; such fonts are +excluded from the set of fonts used to resolve list and match requests as if +they didn't exist in the system. Rejectfont elements include glob and +pattern elements which are used to match fonts. + </para></refsect2> + <refsect2><title><literal><glob></literal></title><para> +Glob elements hold shell-style filename matching patterns (including ? and +*) which match fonts based on their complete pathnames. This can be used to +exclude a set of directories (/usr/share/fonts/uglyfont*), or particular +font file types (*.pcf.gz), but the latter mechanism relies rather heavily +on filenaming conventions which can't be relied upon. Note that globs +only apply to directories, not to individual fonts. + </para></refsect2> + <refsect2><title><literal><pattern></literal></title><para> +Pattern elements perform list-style matching on incoming fonts; that is, +they hold a list of elements and associated values. If all of those +elements have a matching value, then the pattern matches the font. This can +be used to select fonts based on attributes of the font (scalable, bold, +etc), which is a more reliable mechanism than using file extensions. +Pattern elements include patelt elements. + </para></refsect2> + <refsect2><title><literal><patelt name="property"></literal></title><para> +Patelt elements hold a single pattern element and list of values. They must +have a 'name' attribute which indicates the pattern element name. Patelt +elements include int, double, string, matrix, bool, charset and const +elements. + </para></refsect2> + <refsect2><title><literal><match target="pattern"></literal></title><para> +This element holds first a (possibly empty) list of <literal><test></literal> elements and then +a (possibly empty) list of <literal><edit></literal> elements. Patterns which match all of the +tests are subjected to all the edits. If 'target' is set to "font" instead +of the default "pattern", then this element applies to the font name +resulting from a match rather than a font pattern to be matched. If 'target' +is set to "scan", then this element applies when the font is scanned to +build the fontconfig database. + </para></refsect2> + <refsect2><title><literal><test qual="any" name="property" target="default" compare="eq"></literal></title><para> +This element contains a single value which is compared with the target +('pattern', 'font', 'scan' or 'default') property "property" (substitute any of the property names seen +above). 'compare' can be one of "eq", "not_eq", "less", "less_eq", "more", or +"more_eq". 'qual' may either be the default, "any", in which case the match +succeeds if any value associated with the property matches the test value, or +"all", in which case all of the values associated with the property must +match the test value. When used in a <match target="font"> element, +the target= attribute in the <test> element selects between matching +the original pattern or the font. "default" selects whichever target the +outer <match> element has selected. + </para></refsect2> + <refsect2><title><literal><edit name="property" mode="assign" binding="weak"></literal></title><para> +This element contains a list of expression elements (any of the value or +operator elements). The expression elements are evaluated at run-time and +modify the property "property". The modification depends on whether +"property" was matched by one of the associated <literal><test></literal> elements, if so, the +modification may affect the first matched value. Any values inserted into +the property are given the indicated binding ("strong", "weak" or "same") +with "same" binding using the value from the matched pattern element. +'mode' is one of: + <programlisting> + Mode With Match Without Match + --------------------------------------------------------------------- + "assign" Replace matching value Replace all values + "assign_replace" Replace all values Replace all values + "prepend" Insert before matching Insert at head of list + "prepend_first" Insert at head of list Insert at head of list + "append" Append after matching Append at end of list + "append_last" Append at end of list Append at end of list + </programlisting> + </para></refsect2> + <refsect2><title><literal><int></literal>, <literal><double></literal>, <literal><string></literal>, <literal><bool></literal></title><para> +These elements hold a single value of the indicated type. <literal><bool></literal> +elements hold either true or false. An important limitation exists in +the parsing of floating point numbers -- fontconfig requires that +the mantissa start with a digit, not a decimal point, so insert a leading +zero for purely fractional values (e.g. use 0.5 instead of .5 and -0.5 +instead of -.5). + </para></refsect2> + <refsect2><title><literal><matrix></literal></title><para> +This element holds the four <literal><double></literal> elements of an affine +transformation. + </para></refsect2> + <refsect2><title><literal><range></literal></title><para> +This element holds the two <literal><int></literal> elements of a range +representation. + </para></refsect2> + <refsect2><title><literal><charset></literal></title><para> +This element holds at least one <literal><int></literal> element of +an Unicode code point or more. + </para></refsect2> + <refsect2><title><literal><langset></literal></title><para> +This element holds at least one <literal><string></literal> element of +a RFC-3066-style languages or more. + </para></refsect2> + <refsect2><title><literal><name></literal></title><para> +Holds a property name. Evaluates to the first value from the property of +the font, not the pattern. + </para></refsect2> + <refsect2><title><literal><const></literal></title><para> +Holds the name of a constant; these are always integers and serve as +symbolic names for common font values: + <programlisting> + Constant Property Value + ------------------------------------- + thin weight 0 + extralight weight 40 + ultralight weight 40 + light weight 50 + book weight 75 + regular weight 80 + normal weight 80 + medium weight 100 + demibold weight 180 + semibold weight 180 + bold weight 200 + extrabold weight 205 + black weight 210 + heavy weight 210 + roman slant 0 + italic slant 100 + oblique slant 110 + ultracondensed width 50 + extracondensed width 63 + condensed width 75 + semicondensed width 87 + normal width 100 + semiexpanded width 113 + expanded width 125 + extraexpanded width 150 + ultraexpanded width 200 + proportional spacing 0 + dual spacing 90 + mono spacing 100 + charcell spacing 110 + unknown rgba 0 + rgb rgba 1 + bgr rgba 2 + vrgb rgba 3 + vbgr rgba 4 + none rgba 5 + lcdnone lcdfilter 0 + lcddefault lcdfilter 1 + lcdlight lcdfilter 2 + lcdlegacy lcdfilter 3 + hintnone hintstyle 0 + hintslight hintstyle 1 + hintmedium hintstyle 2 + hintfull hintstyle 3 + </programlisting> + </para> + </refsect2> + <refsect2> + <title><literal><or></literal>, <literal><and></literal>, <literal><plus></literal>, <literal><minus></literal>, <literal><times></literal>, <literal><divide></literal></title> + <para> +These elements perform the specified operation on a list of expression +elements. <literal><or></literal> and <literal><and></literal> are boolean, not bitwise. + </para> + </refsect2> + <refsect2> + <title><literal><eq></literal>, <literal><not_eq></literal>, <literal><less></literal>, <literal><less_eq></literal>, <literal><more></literal>, <literal><more_eq></literal></title> + <para> +These elements compare two values, producing a boolean result. + </para></refsect2> + <refsect2><title><literal><not></literal></title><para> +Inverts the boolean sense of its one expression element + </para></refsect2> + <refsect2><title><literal><if></literal></title><para> +This element takes three expression elements; if the value of the first is +true, it produces the value of the second, otherwise it produces the value +of the third. + </para></refsect2> + <refsect2><title><literal><alias></literal></title><para> +Alias elements provide a shorthand notation for the set of common match +operations needed to substitute one font family for another. They contain a +<literal><family></literal> element followed by optional <literal><prefer></literal>, <literal><accept></literal> and <literal><default></literal> +elements. Fonts matching the <literal><family></literal> element are edited to prepend the +list of <literal><prefer></literal>ed families before the matching <literal><family></literal>, append the +<literal><accept></literal>able families after the matching <literal><family></literal> and append the <literal><default></literal> +families to the end of the family list. + </para></refsect2> + <refsect2><title><literal><family></literal></title><para> +Holds a single font family name + </para></refsect2> + <refsect2><title><literal><prefer></literal>, <literal><accept></literal>, <literal><default></literal></title><para> +These hold a list of <literal><family></literal> elements to be used by the <literal><alias></literal> element. + </para></refsect2> +</refsect1> +<refsect1><title>EXAMPLE CONFIGURATION FILE</title> + <refsect2><title>System configuration file</title> + <para> +This is an example of a system-wide configuration file + </para> + <programlisting> +<?xml version="1.0"?> +<!DOCTYPE fontconfig SYSTEM "fonts.dtd"> +<!-- &confdir;/fonts.conf file to configure system font access --> +<fontconfig> +<!-- + Find fonts in these directories +--> +<dir>/usr/share/fonts</dir> +<dir>/usr/X11R6/lib/X11/fonts</dir> + +<!-- + Accept deprecated 'mono' alias, replacing it with 'monospace' +--> +<match target="pattern"> + <test qual="any" name="family"><string>mono</string></test> + <edit name="family" mode="assign"><string>monospace</string></edit> +</match> + +<!-- + Names not including any well known alias are given 'sans' +--> +<match target="pattern"> + <test qual="all" name="family" mode="not_eq">sans</test> + <test qual="all" name="family" mode="not_eq">serif</test> + <test qual="all" name="family" mode="not_eq">monospace</test> + <edit name="family" mode="append_last"><string>sans</string></edit> +</match> + +<!-- + Load per-user customization file, but don't complain + if it doesn't exist +--> +<include ignore_missing="yes">~/.fonts.conf</include> + +<!-- + Load local customization files, but don't complain + if there aren't any +--> +<include ignore_missing="yes">conf.d</include> +<include ignore_missing="yes">local.conf</include> + +<!-- + Alias well known font names to available TrueType fonts. + These substitute TrueType faces for similar Type1 + faces to improve screen appearance. +--> +<alias> + <family>Times</family> + <prefer><family>Times New Roman</family></prefer> + <default><family>serif</family></default> +</alias> +<alias> + <family>Helvetica</family> + <prefer><family>Arial</family></prefer> + <default><family>sans</family></default> +</alias> +<alias> + <family>Courier</family> + <prefer><family>Courier New</family></prefer> + <default><family>monospace</family></default> +</alias> + +<!-- + Provide required aliases for standard names + Do these after the users configuration file so that + any aliases there are used preferentially +--> +<alias> + <family>serif</family> + <prefer><family>Times New Roman</family></prefer> +</alias> +<alias> + <family>sans</family> + <prefer><family>Arial</family></prefer> +</alias> +<alias> + <family>monospace</family> + <prefer><family>Andale Mono</family></prefer> +</alias> +</fontconfig> + </programlisting> + </refsect2> + <refsect2><title>User configuration file</title> + <para> +This is an example of a per-user configuration file that lives in +~/.fonts.conf + </para> + <programlisting> +<?xml version="1.0"?> +<!DOCTYPE fontconfig SYSTEM "fonts.dtd"> +<!-- ~/.fonts.conf for per-user font configuration --> +<fontconfig> + +<!-- + Private font directory +--> +<dir>~/.fonts</dir> + +<!-- + use rgb sub-pixel ordering to improve glyph appearance on + LCD screens. Changes affecting rendering, but not matching + should always use target="font". +--> +<match target="font"> + <edit name="rgba" mode="assign"><const>rgb</const></edit> +</match> +</fontconfig> + </programlisting> + </refsect2> +</refsect1> +<refsect1><title>Files</title> + <para> +<emphasis>fonts.conf</emphasis> +contains configuration information for the fontconfig library +consisting of directories to look at for font information as well as +instructions on editing program specified font patterns before attempting to +match the available fonts. It is in XML format. + </para> + <para> +<emphasis>conf.d</emphasis> +is the conventional name for a directory of additional configuration files +managed by external applications or the local administrator. The +filenames starting with decimal digits are sorted in lexicographic order +and used as additional configuration files. All of these files are in XML +format. The master fonts.conf file references this directory in an +<include> directive. + </para> + <para> +<emphasis>fonts.dtd</emphasis> +is a DTD that describes the format of the configuration files. + </para> + <para> +<emphasis>~/.fonts.conf.d</emphasis> +is the conventional name for a per-user directory of (typically +auto-generated) configuration files, although the +actual location is specified in the global fonts.conf file. + </para> + <para> +<emphasis>~/.fonts.conf</emphasis> +is the conventional location for per-user font configuration, although the +actual location is specified in the global fonts.conf file. + </para> + <para> +<emphasis> ~/.fonts.cache-*</emphasis> +is the conventional repository of font information that isn't found in the +per-directory caches. This file is automatically maintained by fontconfig. + </para> +</refsect1> +<refsect1><title>See Also</title> + <para> +fc-cat(1), fc-cache(1), fc-list(1), fc-match(1), fc-query(1) + </para> +</refsect1> +<refsect1><title>Version</title> + <para> +Fontconfig version &version; + </para> +</refsect1> +</refentry> |