-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+<!ENTITY version SYSTEM "version.sgml">
+<!ENTITY confdir SYSTEM "confdir.sgml">
+]>
<!--
$Id$
-->
<refentry>
<refmeta>
- <refentrytitle>fonts.conf</refentrytitle>
+ <refentrytitle>fonts-conf</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
</refnamediv>
<refsynopsisdiv>
<synopsis>
- /etc/fonts/fonts.conf
- /etc/fonts/fonts.dtd
+ &confdir;/fonts.conf
+ &confdir;/fonts.dtd
~/.fonts.conf
</synopsis>
</refsynopsisdiv>
-<refsect1><title>DESCRIPTION</title>
+<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>
+<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>
+ <refsect2><title>Font Configuration</title>
<para>
The configuration module consists of the FcConfig datatype, libexpat and
FcConfigParse which walks over an XML tree and ammends a configuration with
</para>
</refsect2>
<refsect2>
- <title>FONT PROPERTIES</title>
+ <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
<programlisting>
Property Type Description
--------------------------------------------------------------
- family String Font family name
+ family String Font family names
+ familylang String Languages cooresponding to each family
style String Font style. Overrides weight and slant
+ stylelang String Languages cooresponding to each style
+ fullname String Font full names (often includes style)
+ fullnamelang String Languages cooresponding to each fullname
slant Int Italic, oblique or roman
weight Int Light, medium, demibold, bold or black
size Double Point size
aspect Double Stretches glyphs horizontally before hinting
pixelsize Double Pixel size
- spacing Int Proportional, monospace or charcell
+ 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
</programlisting>
</refsect2>
<refsect2>
- <title>FONT MATCHING</title>
+ <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
as false matches will often occur.
</para>
</refsect2>
- <refsect2><title>FONT NAMES</title>
+ <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
</programlisting>
</refsect2>
</refsect1>
-<refsect1><title>LANG TAGS</title>
+<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
languages with only three-letter codes.
</para>
</refsect1>
-<refsect1><title>CONFIGURATION FILE FORMAT</title>
+<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
</para><para>
The fontconfig document type definition resides in the external entity
"fonts.dtd"; this is normally stored in the default font configuration
-directory (/etc/fonts). Each configuration file should contain the
+directory (&confdir;). Each configuration file should contain the
following structure:
<programlisting>
<?xml version="1.0"?>
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><sgmltag>selectfont</></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><sgmltag>acceptfont</></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><sgmltag>rejectfont</></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><sgmltag>glob</></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.
+ </para></refsect2>
+ <refsect2><title><sgmltag>pattern</></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.
+ <refsect2><title><sgmltag>patelt name="property"</></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><sgmltag>match target="pattern"</></title><para>
This element holds first a (possibly empty) list of <sgmltag>test</> elements and then
</programlisting>
</para></refsect2>
<refsect2><title><sgmltag>int</>, <sgmltag>double</>, <sgmltag>string</>, <sgmltag>bool</></title><para>
-These elements hold a single value of the indicated type. <sgmltag>bool</> elements
-hold either true or false.
+These elements hold a single value of the indicated type. <sgmltag>bool</>
+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><sgmltag>matrix</></title><para>
This element holds the four <sgmltag>double</> elements of an affine
italic slant 100
oblique slant 110
proportional spacing 0
+ dual spacing 90
mono spacing 100
charcell spacing 110
unknown rgba 0
<programlisting>
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
-<!-- /etc/fonts/fonts.conf file to configure system font access -->
+<!-- &confdir;/fonts.conf file to configure system font access -->
<fontconfig>
<!--
Find fonts in these directories
</programlisting>
</refsect2>
</refsect1>
-<refsect1><title>FILES</title>
+<refsect1><title>Files</title>
<para>
<emphasis>fonts.conf</emphasis>
contains configuration information for the fontconfig library
per-directory caches. This file is automatically maintained by fontconfig.
</para>
</refsect1>
+<refsect1><title>Version</title>
+ <para>
+Fontconfig version &version;
+ </para>
+</refsect1>
</refentry>
git.wh0rd.org / fontconfig.git / blobdiff