Move existing fonts.conf to fonts.conf.bak

[fontconfig.git] / doc / fontconfig-user.sgml

diff --git a/doc/fontconfig-user.sgml b/doc/fontconfig-user.sgml
index d5c4be8b92c082352dc99b2a6fd01795b1d2b901..ca0f9b79620e9e38b6909b6831d3ca1da4fed98f 100644 (file)
--- a/doc/fontconfig-user.sgml
+++ b/doc/fontconfig-user.sgml
@@ -1,5 +1,6 @@
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
 <!ENTITY version SYSTEM "version.sgml">
+<!ENTITY confdir SYSTEM "confdir.sgml">
 ]>
 <!--
     $Id$
@@ -35,8 +36,8 @@
 </refnamediv>
 <refsynopsisdiv>
 <synopsis>
-   /etc/fonts/fonts.conf
-   /etc/fonts/fonts.dtd
+   &confdir;/fonts.conf
+   &confdir;/fonts.dtd
    ~/.fonts.conf
 </synopsis>
 </refsynopsisdiv>
@@ -90,14 +91,18 @@ convenience for the applications rendering mechanism.
     <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
@@ -231,7 +236,7 @@ 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 (/etc/fonts).  Each configuration file should contain the
+directory (&confdir;).  Each configuration file should contain the
 following structure:
     <programlisting>
        &lt;?xml version="1.0"?&gt;
@@ -282,6 +287,43 @@ The <sgmltag>rescan</> element holds an <sgmltag>int</> element which indicates
 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
@@ -348,6 +390,7 @@ symbolic names for common font values:
   italic          slant           100
   oblique         slant           110
   proportional    spacing         0
+  dual            spacing         90
   mono            spacing         100
   charcell        spacing         110
   unknown         rgba            0
@@ -404,7 +447,7 @@ This is an example of a system-wide configuration file
     <programlisting>
 &lt;?xml version="1.0"?&gt;
 &lt;!DOCTYPE fontconfig SYSTEM "fonts.dtd"&gt;
-&lt;!-- /etc/fonts/fonts.conf file to configure system font access --&gt;
+&lt;!-- &confdir;/fonts.conf file to configure system font access --&gt;
 &lt;fontconfig&gt;
 &lt;!-- 
        Find fonts in these directories