Bug 20411 - fontconfig doesn't match FreeDesktop directories specs

Allows reading configuration files, fonts and cache files from
the directories where the XDG Base Directory Specification defines.

the old directories are still in the configuration files for
the backward compatibility.

1 files changed, 20 insertions, 17 deletions

diff --git a/doc/fontconfig-user.sgml b/doc/fontconfig-user.sgml
index 22d2ad3..5c9d362 100644
--- a/doc/fontconfig-user.sgml
+++ b/doc/fontconfig-user.sgml
@@ -37,6 +37,8 @@
    &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>
@@ -299,21 +301,22 @@ following structure:
 This is the top level element for a font configuration and can contain
 <literal>&lt;dir&gt;</literal>, <literal>&lt;cachedir&gt;</literal>, <literal>&lt;include&gt;</literal>, <literal>&lt;match&gt;</literal> and <literal>&lt;alias&gt;</literal> elements in any order.
   </para></refsect2>
-  <refsect2><title><literal>&lt;dir&gt;</literal></title><para>
+  <refsect2><title><literal>&lt;dir prefix="default"&gt;</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>&lt;cachedir&gt;</literal></title><para>
+  <refsect2><title><literal>&lt;cachedir prefix="default"&gt;</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>&lt;hash value&gt;</literal>-<literal>&lt;architecture&gt;</literal>.cache-<literal>&lt;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>&lt;hash value&gt;</literal>-<literal>&lt;architecture&gt;</literal>.cache-<literal>&lt;version</literal>'',
 where <literal>&lt;version&gt;</literal> is the font configureation file
 version number (currently 3).
   </para></refsect2>
-  <refsect2><title><literal>&lt;include ignore_missing="no"&gt;</literal></title><para>
+  <refsect2><title><literal>&lt;include ignore_missing="no" prefix="default"&gt;</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
@@ -321,7 +324,7 @@ 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.
+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>&lt;config&gt;</literal></title><para>
 This element provides a place to consolidate additional configuration
@@ -577,7 +580,7 @@ This is an example of a system-wide configuration file
 	Load per-user customization file, but don't complain
 	if it doesn't exist
 --&gt;
-&lt;include ignore_missing="yes"&gt;~/.fonts.conf&lt;/include&gt;
+&lt;include ignore_missing="yes" prefix="xdg"&gt;fontconfig/fonts.conf&lt;/include&gt;
 
 &lt;!--
 	Load local customization files, but don't complain
@@ -630,18 +633,18 @@ This is an example of a system-wide configuration file
   <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>
 &lt;?xml version="1.0"?&gt;
 &lt;!DOCTYPE fontconfig SYSTEM "fonts.dtd"&gt;
-&lt;!-- ~/.fonts.conf for per-user font configuration --&gt;
+&lt;!-- $XDG_CONFIG_HOME/fontconfig/fonts.conf for per-user font configuration --&gt;
 &lt;fontconfig&gt;
 
 &lt;!--
 	Private font directory
 --&gt;
-&lt;dir&gt;~/.fonts&lt;/dir&gt;
+&lt;dir prefix="xdg"&gt;fonts&lt;/dir&gt;
 
 &lt;!--
 	use rgb sub-pixel ordering to improve glyph appearance on
@@ -677,20 +680,20 @@ format.  The master fonts.conf file references this directory in an
 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>