&confdir;/fonts.conf
&confdir;/fonts.dtd
&confdir;/conf.d
+ $XDG_CONFIG_HOME/fontconfig/conf.d
+ $XDG_CONFIG_HOME/fontconfig/fonts.conf
~/.fonts.conf.d
~/.fonts.conf
</synopsis>
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
+ globaladvance Bool Use font global advance data (deprecated)
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
</para>
</refsect2>
</refsect1>
-<refsect1><title>Debugging Applications</title>
+<refsect1 id="debug"><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
This is the top level element for a font configuration and can contain
<literal><dir></literal>, <literal><cachedir></literal>, <literal><include></literal>, <literal><match></literal> and <literal><alias></literal> elements in any order.
</para></refsect2>
- <refsect2><title><literal><dir></literal></title><para>
+ <refsect2><title><literal><dir
prefix="default"></literal></title><para>
This element contains a directory name which will be scanned for font files
-to include in the set of available fonts.
+to include in the set of available fonts. If 'prefix' is set to "xdg", the value in the XDG_DATA_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details.
</para></refsect2>
- <refsect2><title><literal><cachedir></literal></title><para>
+ <refsect2><title><literal><cachedir
prefix="default"></literal></title><para>
This element contains a directory name that is supposed to be stored or read
the cache of font information. If multiple elements are specified in
the configuration file, the directory that can be accessed first in the list
will be used to store the cache files. If it starts with '~', it refers to
-a directory in the users home directory. The default directory is ``~/.fontconfig''
-and it contains the cache files named ``<literal><hash value></literal>-<literal><architecture></literal>.cache-<literal><version</literal>'',
+a directory in the users home directory. If 'prefix' is set to "xdg", the value in the XDG_CACHE_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details.
+The default directory is ``$XDG_CACHE_HOME/fontconfig'' and it contains the cache files
+named ``<literal><hash value></literal>-<literal><architecture></literal>.cache-<literal><version</literal>'',
where <literal><version></literal> is the font configureation file
version number (currently 3).
</para></refsect2>
- <refsect2><title><literal><include ignore_missing="no"></literal></title><para>
+ <refsect2><title><literal><include ignore_missing="no"
prefix="default"></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
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.
+the library. If 'prefix' is set to "xdg", the value in the XDG_CONFIG_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details.
</para></refsect2>
<refsect2><title><literal><config></literal></title><para>
This element provides a place to consolidate additional configuration
<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
+above). 'compare' can be one of "eq", "not_eq", "less", "less_eq", "more", "more_eq", "contains" or
+"not_contains". '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,
+match the test value. 'ignore-blanks' takes a boolean value. if 'ignore-blanks' is set "true", any blanks in the string will be ignored on its comparison. this takes effects only when compare="eq" or compare="not_eq".
+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.
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.
+This element holds four numerical expressions of an affine transformation.
+At their simplest these will be four <literal><double></literal> elements
+but they can also be more involved expressions.
</para></refsect2>
<refsect2><title><literal><range></literal></title><para>
This element holds the two <literal><int></literal> elements of a range
</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.
+the pattern. If the 'target' attribute is not present, it will default to
+'default', in which case the property is returned from the font pattern
+during a target="font" match, and to the pattern during a target="pattern"
+match. The attribute can also take the values 'font' or 'pattern' to
+explicitly choose which pattern to use. It is an error to use a target
+of 'font' in a match that has target="pattern".
</para></refsect2>
<refsect2><title><literal><const></literal></title><para>
Holds the name of a constant; these are always integers and serve as
</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>
+ <title><literal><eq></literal>, <literal><not_eq></literal>, <literal><less></literal>, <literal><less_eq></literal>, <literal><more></literal>, <literal><more_eq></literal>, <literal><contains></literal>, <literal><not_contains</literal></title>
<para>
These elements compare two values, producing a boolean result.
</para></refsect2>
</match>
<!--
- Names not including any well known alias are given 'sans'
+ Names not including any well known alias are given 'sans-serif'
-->
<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>
+ <test qual="all" name="family" mode="not_eq"><string>sans-serif</string></test>
+ <test qual="all" name="family" mode="not_eq"><string>serif</string></test>
+ <test qual="all" name="family" mode="not_eq"><string>monospace</string></test>
+ <edit name="family" mode="append_last"><string>sans-serif</string></edit>
</match>
<!--
Load per-user customization file, but don't complain
if it doesn't exist
-->
-<include ignore_missing="yes">~/.fonts.conf</include>
+<include ignore_missing="yes" prefix="xdg">fontconfig/fonts.conf</include>
<!--
Load local customization files, but don't complain
<family>monospace</family>
<prefer><family>Andale Mono</family></prefer>
</alias>
+
+<--
+ The example of the requirements of OR operator;
+ If the 'family' contains 'Courier New' OR 'Courier'
+ add 'monospace' as the alternative
+-->
+<match target="pattern">
+ <test name="family" mode="eq">
+ <string>Courier New</string>
+ </test>
+ <edit name="family" mode="prepend">
+ <string>monospace</string>
+ </edit>
+</match>
+<match target="pattern">
+ <test name="family" mode="eq">
+ <string>Courier</string>
+ </test>
+ <edit name="family" mode="prepend">
+ <string>monospace</string>
+ </edit>
+</match>
+
</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
+$XDG_CONFIG_HOME/fontconfig/fonts.conf
</para>
<programlisting>
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
-<!-- ~/.fonts.conf for per-user font configuration -->
+<!-- $XDG_CONFIG_HOME/fontconfig/fonts.conf for per-user font configuration -->
<fontconfig>
<!--
Private font directory
-->
-<dir>~/.fonts</dir>
+<dir prefix="xdg">fonts</dir>
<!--
use rgb sub-pixel ordering to improve glyph appearance on
<match target="font">
<edit name="rgba" mode="assign"><const>rgb</const></edit>
</match>
+<!--
+ use WenQuanYi Zen Hei font when serif is requested for Chinese
+-->
+<match>
+ <!--
+ If you don't want to use WenQuanYi Zen Hei font for zh-tw etc,
+ you can use zh-cn instead of zh.
+ Please note, even if you set zh-cn, it still matches zh.
+ if you don't like it, you can use compare="eq"
+ instead of compare="contains".
+ -->
+ <test name="lang" compare="contains">
+ <string>zh</string>
+ </test>
+ <test name="family">
+ <string>serif</string>
+ </test>
+ <edit name="family" mode="prepend">
+ <string>WenQuanYi Zen Hei</string>
+ </edit>
+</match>
+<!--
+ use VL Gothic font when sans-serif is requested for Japanese
+-->
+<match>
+ <test name="lang" compare="contains">
+ <string>ja</string>
+ </test>
+ <test name="family">
+ <string>sans-serif</string>
+ </test>
+ <edit name="family" mode="prepend">
+ <string>VL Gothic</string>
+ </edit>
+</match>
</fontconfig>
</programlisting>
</refsect2>
is a DTD that describes the format of the configuration files.
</para>
<para>
-<emphasis>~/.fonts.conf.d</emphasis>
+<emphasis>$XDG_CONFIG_HOME/fontconfig/conf.d</emphasis> and <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.
+actual location is specified in the global fonts.conf file. please note that ~/.fonts.conf.d is deprecated now. it will not be read by default in the future version.
</para>
<para>
-<emphasis>~/.fonts.conf</emphasis>
+<emphasis>$XDG_CONFIG_HOME/fontconfig/fonts.conf</emphasis> and <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.
+actual location is specified in the global fonts.conf file. please note that ~/.fonts.conf is deprecated now. it will not be read by default in the future version.
</para>
<para>
-<emphasis> ~/.fontconfig/*.cache-*</emphasis>
+<emphasis>$XDG_CACHE_HOME/fontconfig/*.cache-*</emphasis> and <emphasis> ~/.fontconfig/*.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.
+per-directory caches. This file is automatically maintained by fontconfig. please note that ~/.fontconfig/*.cache-* is deprecated now. it will not be read by default in the future version.
+ </para>
+</refsect1>
+<refsect1><title>Environment variables</title>
+ <para>
+<emphasis>FONTCONFIG_FILE</emphasis>
+is used to override the default configuration file.
+ </para>
+ <para>
+<emphasis>FONTCONFIG_PATH</emphasis>
+is used to override the default configuration directory.
+ </para>
+ <para>
+<emphasis>FC_DEBUG</emphasis>
+is used to output the detailed debugging messages. see <link linkend="debug">Debugging Applications</link> section for more details.
+ </para>
+ <para>
+<emphasis>FONTCONFIG_USE_MMAP</emphasis>
+is used to control the use of mmap(2) for the cache files if available. this take a boolean value. fontconfig will checks if the cache files are stored on the filesystem that is safe to use mmap(2). explicitly setting this environment variable will causes skipping this check and enforce to use or not use mmap(2) anyway.
</para>
</refsect1>
<refsect1><title>See Also</title>
projects / platform / upstream / fontconfig.git / blobdiff