Finish reformatting developer documentation

10 files changed, 795 insertions, 438 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 6b18c1ae..543f1284 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -17,7 +17,13 @@ DOC_FUNCS_FNCS=\
 	fcobjecttype.fncs \
 	fcconstant.fncs \
 	fcblanks.fncs \
-	fcconfig.fncs
+	fcconfig.fncs \
+	fcinit.fncs \
+	fcatomic.fncs \
+	fcfreetype.fncs \
+	fcfile.fncs \
+	fcstrset.fncs \
+	fcstring.fncs
 	
 DOC_FUNCS_SGML=\
 	fcmatrix.sgml \
@@ -29,7 +35,13 @@ DOC_FUNCS_SGML=\
 	fcobjecttype.sgml \
 	fcconstant.sgml \
 	fcblanks.sgml \
-	fcconfig.sgml
+	fcconfig.sgml \
+	fcinit.sgml \
+	fcatomic.sgml \
+	fcfreetype.sgml \
+	fcfile.sgml \
+	fcstrset.sgml \
+	fcstring.sgml
 	
 man3_MANS= \
 	FcCharSetAddChar.3 \
diff --git a/doc/edit-sgml.c b/doc/edit-sgml.c
index 6e04e1cb..d40c9b38 100644
--- a/doc/edit-sgml.c
+++ b/doc/edit-sgml.c
@@ -145,6 +145,15 @@ ReplaceDispose (Replace *r)
     Dispose (r);
 }
 
+void
+Bail (char *format, char *arg)
+{
+    fprintf (stderr, "fatal: ");
+    fprintf (stderr, format, arg);
+    fprintf (stderr, "\n");
+    exit (1);
+}
+
 Replace *
 ReplaceRead (FILE *f)
 {
@@ -164,6 +173,8 @@ ReplaceRead (FILE *f)
 	    ReplaceDispose (r);
 	    return 0;
 	}
+	if (isspace (c))
+	    Bail ("invalid character after tag %s", r->tag->buf);
 	StringAdd (r->tag, c);
     }
     if (r->tag->buf[0] == '\0')
@@ -408,10 +419,12 @@ main (int argc, char **argv)
     FILE	*f;
     ReplaceSet	*s;
 
+    if (!argv[1])
+	Bail ("usage: %s <template.sgml>", argv[0]);
     f = fopen (argv[1], "r");
     if (!f)
     {
-	perror (argv[1]);
+	Bail ("can't open file %s", argv[1]);
 	exit (1);
     }
     while ((s = ReplaceSetRead (stdin)))
@@ -421,6 +434,6 @@ main (int argc, char **argv)
 	rewind (f);
     }
     if (ferror (stdout))
-	exit (1);
+	Bail ("%s", "error writing output");
     exit (0);
 }
diff --git a/doc/fcatomic.fncs b/doc/fcatomic.fncs
new file mode 100644
index 00000000..d99a1104
--- /dev/null
+++ b/doc/fcatomic.fncs
@@ -0,0 +1,93 @@
+/*
+ * $Id$
+ *
+ * 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 Keith Packard not be used in
+ * advertising or publicity pertaining to distribution of the software without
+ * specific, written prior permission.  Keith Packard makes no
+ * representations about the suitability of this software for any purpose.  It
+ * is provided "as is" without express or implied warranty.
+ *
+ * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+ * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+ * EVENT SHALL KEITH PACKARD 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.
+ */
+
+@RET@           FcAtomic *
+@FUNC@          FcAtomicCreate
+@TYPE1@         const FcChar8   *           	@ARG1@          file
+@PURPOSE@	create an FcAtomic object
+@DESC@
+Creates a data structure containing data needed to control access to <parameter>file</parameter>.
+Writing is done to a separate file.  Once that file is complete, the original
+configuration file is atomically replaced so that reading process always see
+a consistent and complete file without the need to lock for reading.
+@@
+
+@RET@           FcBool
+@FUNC@          FcAtomicLock
+@TYPE1@         FcAtomic *                      @ARG1@          atomic
+@PURPOSE@	lock a file
+@DESC@
+Attempts to lock the file referenced by <parameter>atomic</parameter>.  Returns FcFalse if the
+file is locked by another process, else returns FcTrue and leaves the file
+locked.
+@@
+
+@RET@           FcChar8 *
+@FUNC@          FcAtomicNewFile
+@TYPE1@         FcAtomic *                      @ARG1@          atomic
+@PURPOSE@	return new temporary file name 
+@DESC@
+Returns the filename for writing a new version of the file referenced
+by <parameter>atomic</parameter>.
+@@
+
+@RET@           FcChar8 *
+@FUNC@          FcAtomicOrigFile
+@TYPE1@         FcAtomic *                      @ARG1@          atomic
+@PURPOSE@	return original file name
+@DESC@
+Returns the file refernced by <parameter>atomic</parameter>.
+@@
+
+@RET@           FcBool
+@FUNC@          FcAtomicReplaceOrig
+@TYPE1@         FcAtomic *                      @ARG1@          atomic
+@PURPOSE@	replace original with new
+@DESC@
+Replaces the original file referenced by <parameter>atomic</parameter> with the new file.
+@@
+
+@RET@           void
+@FUNC@          FcAtomicDeleteNew
+@TYPE1@         FcAtomic *                      @ARG1@          atomic
+@PURPOSE@	delete new file
+@DESC@
+Deletes the new file.  Used in error recovery to back out changes.
+@@
+
+@RET@           void
+@FUNC@          FcAtomicUnlock
+@TYPE1@         FcAtomic *                      @ARG1@          atomic
+@PURPOSE@	unlock a file
+@DESC@
+Unlocks the file.
+@@
+
+@RET@           void
+@FUNC@          FcAtomicDestroy
+@TYPE1@         FcAtomic *                      @ARG1@          atomic
+@PURPOSE@	destroy an FcAtomic object
+@DESC@
+Destroys <parameter>atomic</parameter>.
+@@
diff --git a/doc/fcconfig.fncs b/doc/fcconfig.fncs
index d6119f2f..b52f4e6d 100644
--- a/doc/fcconfig.fncs
+++ b/doc/fcconfig.fncs
@@ -21,7 +21,7 @@
  * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  * PERFORMANCE OF THIS SOFTWARE.
  */
-@RET@           FcConfig *      		
+@RET@           FcConfig *
 @FUNC@          FcConfigCreate
 @TYPE1@		void
 @PURPOSE@	Create a configuration
@@ -29,9 +29,9 @@
 Creates an empty configuration.
 @@
 
-@RET@           void       			
-@FUNC@          FcConfigDestroy       
-@TYPE1@         FcConfig *                      @ARG1@          config      
+@RET@           void
+@FUNC@          FcConfigDestroy
+@TYPE1@         FcConfig *                      @ARG1@          config
 @PURPOSE@	Destroy a configuration
 @DESC@
 Destroys a configuration and any data associated with it.  Note that calling
@@ -39,16 +39,16 @@ this function with the return from FcConfigGetCurrent will place the library
 in an indeterminate state.
 @@
 
-@RET@           FcBool       			
-@FUNC@          FcConfigSetCurrent       
-@TYPE1@         FcConfig *                      @ARG1@          config      
+@RET@           FcBool
+@FUNC@          FcConfigSetCurrent
+@TYPE1@         FcConfig *                      @ARG1@          config
 @PURPOSE@	Set configuration as default
 @DESC@
 Sets the current default configuration to <parameter>config</parameter>.  Implicitly calls
 FcConfigBuildFonts if necessary, returning FcFalse if that call fails.
 @@
 
-@RET@           FcConfig *      		
+@RET@           FcConfig *
 @FUNC@          FcConfigGetCurrent
 @TYPE1@		void
 @PURPOSE@	Return current configuration
@@ -56,18 +56,18 @@ FcConfigBuildFonts if necessary, returning FcFalse if that call fails.
 Returns the current default configuration.
 @@
 
-@RET@           FcBool       			
-@FUNC@          FcConfigUptoDate       
-@TYPE1@         FcConfig *                      @ARG1@          config      
+@RET@           FcBool
+@FUNC@          FcConfigUptoDate
+@TYPE1@         FcConfig *                      @ARG1@          config
 @PURPOSE@	Check timestamps on config files
 @DESC@
 Checks all of the files related to <parameter>config</parameter> and returns whether the
 in-memory version is in sync with the disk version.
 @@
 
-@RET@           FcBool       			
-@FUNC@          FcConfigBuildFonts       
-@TYPE1@         FcConfig *                      @ARG1@          config      
+@RET@           FcBool
+@FUNC@          FcConfigBuildFonts
+@TYPE1@         FcConfig *                      @ARG1@          config
 @PURPOSE@	Build font database
 @DESC@
 Builds the set of available fonts for the given configuration.  Note that
@@ -75,18 +75,18 @@ any changes to the configuration after this call have indeterminate effects.
 Returns FcFalse if this operation runs out of memory.
 @@
 
-@RET@           FcStrList *      		
-@FUNC@          FcConfigGetConfigDirs       
-@TYPE1@         FcConfig *                      @ARG1@          config      
+@RET@           FcStrList *
+@FUNC@          FcConfigGetConfigDirs
+@TYPE1@         FcConfig *                      @ARG1@          config
 @PURPOSE@	Get config directories
 @DESC@
 Returns the list of font directories specified in the configuration files
 for <parameter>config</parameter>.  Does not include any subdirectories.
 @@
 
-@RET@           FcStrList *      		
-@FUNC@          FcConfigGetFontDirs       
-@TYPE1@         FcConfig *                      @ARG1@          config      
+@RET@           FcStrList *
+@FUNC@          FcConfigGetFontDirs
+@TYPE1@         FcConfig *                      @ARG1@          config
 @PURPOSE@	Get font directories
 @DESC@
 Returns the list of font directories in <parameter>config</parameter>. This includes the
@@ -94,45 +94,45 @@ configured font directories along with any directories below those in the
 filesystem.
 @@
 
-@RET@           FcStrList *      		
-@FUNC@          FcConfigGetConfigFiles       
-@TYPE1@         FcConfig *                      @ARG1@          config      
+@RET@           FcStrList *
+@FUNC@          FcConfigGetConfigFiles
+@TYPE1@         FcConfig *                      @ARG1@          config
 @PURPOSE@	Get config files
 @DESC@
 Returns the list of known configuration files used to generate <parameter>config</parameter>.
 Note that this will not include any configuration done with FcConfigParse.
 @@
 
-@RET@           char *      			
-@FUNC@          FcConfigGetCache       
-@TYPE1@         FcConfig *                      @ARG1@          config      
+@RET@           char *
+@FUNC@          FcConfigGetCache
+@TYPE1@         FcConfig *                      @ARG1@          config
 @PURPOSE@	Get cache filename
 @DESC@
 Returns the name of the file used to store per-user font information.
 @@
 
-@RET@           FcFontSet *      		
-@FUNC@          FcConfigGetFonts       
+@RET@           FcFontSet *
+@FUNC@          FcConfigGetFonts
 @TYPE1@         FcConfig *			@ARG1@		config
-@TYPE2@		FcSetName                       @ARG2@          set      
+@TYPE2@		FcSetName                       @ARG2@          set
 @PURPOSE@	Get config font set
 @DESC@
-Returns one of the two sets of fonts from the configuration as specified 
+Returns one of the two sets of fonts from the configuration as specified
 by <parameter>set</parameter>.
 @@
 
-@RET@           FcBlanks *      		
-@FUNC@          FcConfigGetBlanks       
-@TYPE1@         FcConfig *                      @ARG1@          config      
+@RET@           FcBlanks *
+@FUNC@          FcConfigGetBlanks
+@TYPE1@         FcConfig *                      @ARG1@          config
 @PURPOSE@	Get config blanks
 @DESC@
 Returns the FcBlanks object associated with the given configuration, if no
 blanks were present in the configuration, this function will return 0.
 @@
 
-@RET@           int       			
-@FUNC@          FcConfigGetRescanInverval       
-@TYPE1@         FcConfig *                      @ARG1@          config      
+@RET@           int
+@FUNC@          FcConfigGetRescanInverval
+@TYPE1@         FcConfig *                      @ARG1@          config
 @PURPOSE@	Get config rescan interval
 @DESC@
 Returns the interval between automatic checks of the configuration (in
@@ -140,8 +140,8 @@ seconds) specified in <parameter>config</parameter>.  The configuration is check
 a call to FcFontList when this interval has passed since the last check.
 @@
 
-@RET@           FcBool       			
-@FUNC@          FcConfigSetRescanInverval       
+@RET@           FcBool
+@FUNC@          FcConfigSetRescanInverval
 @TYPE1@         FcConfig *			@ARG1@		config
 @TYPE2@		int                       	@ARG2@          rescanInterval
 @PURPOSE@	Set config rescan interval
@@ -149,62 +149,62 @@ a call to FcFontList when this interval has passed since the last check.
 Sets the rescan interval; returns FcFalse if an error occurred.
 @@
 
-@RET@           FcBool       			
-@FUNC@          FcConfigAppFontAddFile       
+@RET@           FcBool
+@FUNC@          FcConfigAppFontAddFile
 @TYPE1@         FcConfig *			@ARG1@		config
-@TYPE2@		const char *                    @ARG2@          file      
+@TYPE2@		const char *                    @ARG2@          file
 @PURPOSE@	Add font file to font database
 @DESC@
 Adds an application-specific font to the configuration.
 @@
 
-@RET@           FcBool       			
-@FUNC@          FcConfigAppFontAddDir       
+@RET@           FcBool
+@FUNC@          FcConfigAppFontAddDir
 @TYPE1@         FcConfig *			@ARG1@		config
-@TYPE2@		const char *                    @ARG1@          dir      
+@TYPE2@		const char *                    @ARG1@          dir
 @PURPOSE@	Add fonts from directory to font database
 @DESC@
 Scans the specified directory for fonts, adding each one found to the
 application-specific set of fonts.
 @@
 
-@RET@           void       			
-@FUNC@          FcConfigAppFontClear       
-@TYPE1@         FcConfig *                      @ARG1@          config      
+@RET@           void
+@FUNC@          FcConfigAppFontClear
+@TYPE1@         FcConfig *                      @ARG1@          config
 @PURPOSE@	Remove all app fonts from font database
 @DESC@
 Clears the set of application-specific fonts.
 @@
 
-@RET@           FcBool       			
-@FUNC@          FcConfigSubstituteWithPat       
+@RET@           FcBool
+@FUNC@          FcConfigSubstituteWithPat
 @TYPE1@         FcConfig *			@ARG1@		config
 @TYPE2@		FcPattern *			@ARG2@		p
 @TYPE3@		FcPattern *			@ARG3@		p_pat
-@TYPE4@		FcMatchKind                     @ARG4@          kind      
+@TYPE4@		FcMatchKind                     @ARG4@          kind
 @PURPOSE@	Execute substitutions
 @DESC@
 Performs the sequence of pattern modification operations, if <parameter>kind</parameter> is
-FcMatchPattern, then those tagged as pattern operations are applied, else 
+FcMatchPattern, then those tagged as pattern operations are applied, else
 if <parameter>kind</parameter> is FcMatchFont, those tagged as font operations are applied and
 p_pat is used for &lt;test&gt; elements with target=pattern.
 @@
 
-@RET@           FcBool       			
-@FUNC@          FcConfigSubstitute       
+@RET@           FcBool
+@FUNC@          FcConfigSubstitute
 @TYPE1@         FcConfig *			@ARG1@		config
 @TYPE2@		FcPattern *			@ARG2@		p
-@TYPE3@		FcMatchKind                     @ARG3@          kind      
+@TYPE3@		FcMatchKind                     @ARG3@          kind
 @PURPOSE@	Execute substitutions
 @DESC@
 Calls FcConfigSubstituteWithPat setting p_pat to NULL.
 @@
 
-@RET@           FcPattern *      		
-@FUNC@          FcFontMatch       
+@RET@           FcPattern *
+@FUNC@          FcFontMatch
 @TYPE1@         FcConfig *			@ARG1@		config
 @TYPE2@		FcPattern *			@ARG2@		p
-@TYPE3@		FcResult *                      @ARG3@          result      
+@TYPE3@		FcResult *                      @ARG3@          result
 @PURPOSE@	Return best font
 @DESC@
 Returns the font in <parameter>config</parameter> most close matching <parameter>p</parameter>.  This function
@@ -212,13 +212,13 @@ should be called only after FcConfigSubstitute and FcDefaultSubstitute have
 been called for <parameter>p</parameter>; otherwise the results will not be correct.
 @@
 
-@RET@           FcFontSet *      		
-@FUNC@          FcFontSort       
+@RET@           FcFontSet *
+@FUNC@          FcFontSort
 @TYPE1@         FcConfig *			@ARG1@		config
 @TYPE2@		FcPattern *			@ARG2@		p
 @TYPE3@		FcBool				@ARG3@		trim
 @TYPE4@		FcCharSet **			@ARG4@		csp
-@TYPE5@		FcResult *                      @ARG5@          result      
+@TYPE5@		FcResult *                      @ARG5@          result
 @PURPOSE@	Return list of matching fonts
 @DESC@
 Returns the list of fonts sorted by closeness to <parameter>p</parameter>.  If <parameter>trim</parameter> is FcTrue,
@@ -236,11 +236,11 @@ FcFontRenderPrepare which combines them into a complete pattern.
 The FcFontSet returned by FcFontSort is destroyed by caling FcFontSetDestroy.
 @@
 
-@RET@           FcPattern *      		
-@FUNC@          FcFontRenderPrepare       
+@RET@           FcPattern *
+@FUNC@          FcFontRenderPrepare
 @TYPE1@         FcConfig *			@ARG1@		config
 @TYPE2@		FcPattern *			@ARG2@		pat
-@TYPE3@		FcPattern *                     @ARG3@          font      
+@TYPE3@		FcPattern *                     @ARG3@          font
 @PURPOSE@	Prepare pattern for loading font file
 @DESC@
 Creates a new pattern consisting of elements of <parameter>font</parameter> not appearing
@@ -249,25 +249,25 @@ value from <parameter>pat</parameter> for elements appearing in both.  The resul
 FcConfigSubstitute with <parameter>kind</parameter> FcMatchFont and then returned.
 @@
 
-@RET@           FcFontSet *      		
-@FUNC@          FcFontList       
+@RET@           FcFontSet *
+@FUNC@          FcFontList
 @TYPE1@         FcConfig *			@ARG1@		config
 @TYPE2@		FcPattern *			@ARG2@		p
-@TYPE3@		FcObjectSet *                   @ARG3@          os      
+@TYPE3@		FcObjectSet *                   @ARG3@          os
 @PURPOSE@	List fonts
 @DESC@
 Selects fonts matching <parameter>p</parameter>, creates patterns from those fonts containing
 only the objects in <parameter>os</parameter> and returns the set of unique such patterns.
 @@
 
-@RET@           char *      			
-@FUNC@          FcConfigFilename       
-@TYPE1@         const char *                    @ARG1@          name      
+@RET@           char *
+@FUNC@          FcConfigFilename
+@TYPE1@         const char *                    @ARG1@          name
 @PURPOSE@	Find a config file
 @DESC@
 Given the specified external entity name, return the associated filename.
 This provides applications a way to convert various configuration file
-references into filename form. 
+references into filename form.
     </para><para>
 A null or empty <parameter>name</parameter> indicates that the default configuration file should
 be used; which file this references can be overridden with the
@@ -277,3 +277,16 @@ doesn't start with '/', it refers to a file in the default configuration
 directory; the built-in default directory can be overridden with the
 FC_CONFIG_DIR environment variable.
 @@
+
+@RET@		FcBool
+@FUNC@		FcConfigParseAndLoad
+@TYPE1@		FcConfig *			@ARG1@		config
+@TYPE2@		const FcChar8 *			@ARG2@		file
+@TYPE2@		FcBool				@ARG3@		complain
+@PURPOSE@	load a configuration file
+@DESC@
+Walks the configuration in 'file' and constructs the internal representation
+in 'config'.  Any include files referenced from within 'file' will be loaded
+with FcConfigLoad and also parsed.  If 'complain' is FcFalse, no warning
+will be displayed if 'file' does not exist.
+@@
diff --git a/doc/fcfile.fncs b/doc/fcfile.fncs
new file mode 100644
index 00000000..b20b099f
--- /dev/null
+++ b/doc/fcfile.fncs
@@ -0,0 +1,78 @@
+/*
+ * $Id$
+ *
+ * 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 Keith Packard not be used in
+ * advertising or publicity pertaining to distribution of the software without
+ * specific, written prior permission.  Keith Packard makes no
+ * representations about the suitability of this software for any purpose.  It
+ * is provided "as is" without express or implied warranty.
+ *
+ * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+ * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+ * EVENT SHALL KEITH PACKARD 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.
+ */
+
+@RET@		FcBool 	
+@FUNC@		FcFileScan 
+@TYPE1@		FcFontSet *			@ARG1@		set	
+@TYPE2@		FcStrSet *			@ARG2@		dirs	
+@TYPE3@		FcFileCache *			@ARG3@		cache	
+@TYPE4@		FcBlanks *			@ARG4@		blanks	
+@TYPE5@		const char *			@ARG5@		file	
+@TYPE6@		FcBool 				@ARG6@		force	
+@PURPOSE@	scan a font file
+@DESC@
+Scans a single file and adds all fonts found to <parameter>set</parameter>.
+If <parameter>force</parameter> is FcTrue, then the file is scanned even if
+associated information is found in <parameter>cache</parameter>.  If
+<parameter>file</parameter> is a directory, it is added to
+<parameter>dirs</parameter>.
+@@
+
+@RET@		FcBool 	
+@FUNC@		FcDirScan 
+@TYPE1@		FcFontSet *			@ARG1@		set	
+@TYPE2@		FcStrSet *			@ARG2@		dirs	
+@TYPE3@		FcFileCache *			@ARG3@		cache	
+@TYPE4@		FcBlanks *			@ARG4@		blanks	
+@TYPE5@		const char *			@ARG5@		dir	
+@TYPE6@		FcBool 				@ARG6@		force	
+@PURPOSE@	scan a font directory
+@DESC@
+Scans an entire directory and adds all fonts found to
+<parameter>set</parameter>.  If <parameter>force</parameter> is FcTrue, then
+the directory and all files within it are scanned even if information is
+present in the per-directory cache file or <parameter>cache</parameter>.  Any
+subdirectories found are added to <parameter>dirs</parameter>.
+@@
+
+@RET@		FcBool 	
+@FUNC@		FcDirSave 
+@TYPE1@		FcFontSet *			@ARG1@		set	
+@TYPE2@		FcStrSet *			@ARG2@		dirs	
+@TYPE3@		const char *			@ARG3@		dir	
+@PURPOSE@	save a directory cache
+@DESC@
+Creates the per-directory cache file for <parameter>dir</parameter> and
+populates it with the fonts in <parameter>set</parameter> and subdirectories
+in <parameter>dirs</parameter>.
+@@
+
+@RET@		FcBool 	
+@FUNC@		FcDirCacheValid 
+@TYPE1@		const FcChar8 *			@ARG1@		cache_file	
+@PURPOSE@	check directory cache timestamp
+@DESC@
+Returns FcTrue if <parameter>cache_file</parameter> is no older than the
+directory containing it, else FcFalse.
+@@
diff --git a/doc/fcfreetype.fncs b/doc/fcfreetype.fncs
new file mode 100644
index 00000000..7e22582c
--- /dev/null
+++ b/doc/fcfreetype.fncs
@@ -0,0 +1,69 @@
+/*
+ * $Id$
+ *
+ * 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 Keith Packard not be used in
+ * advertising or publicity pertaining to distribution of the software without
+ * specific, written prior permission.  Keith Packard makes no
+ * representations about the suitability of this software for any purpose.  It
+ * is provided "as is" without express or implied warranty.
+ *
+ * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+ * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+ * EVENT SHALL KEITH PACKARD 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.
+ */
+
+@SYNOPSIS@
+#include &lt;fontconfig.h&gt;
+#include &lt;fcfreetype.h&gt;
+@RET@           FT_UInt       
+@FUNC@          FcFreeTypeCharIndex 
+@TYPE1@         FT_Face				@ARG1@          face      
+@TYPE2@         FcChar32			@ARG2@          ucs4      
+@PURPOSE@	map Unicode to glyph id
+@DESC@
+Maps a Unicode char to a glyph index.  This function uses information from
+several possible underlying encoding tables to work around broken fonts.
+As a result, this function isn't designed to be used in performance
+sensitive areas; results from this function are intended to be cached by
+higher level functions.
+@@
+
+@SYNOPSIS@
+#include &lt;fontconfig.h&gt;
+#include &lt;fcfreetype.h&gt;
+@RET@           FcCharSet *      
+@FUNC@          FcFreeTypeCharSet 
+@TYPE1@         FT_Face				@ARG1@          face      
+@TYPE2@         FcBlanks *			@ARG2@          blanks
+@PURPOSE@	compute unicode coverage
+@DESC@
+Scans a FreeType face and returns the set of encoded Unicode chars.  This scans
+several encoding tables to build as complete a list as possible.  
+If 'blanks' is not 0, the glyphs in the font are examined and any blank glyphs
+not in 'blanks' are not placed in the returned FcCharSet.
+@@
+
+@SYNOPSIS@
+#include &lt;fontconfig.h&gt;
+#include &lt;fcfreetype.h&gt;
+@RET@           FcPattern *      
+@FUNC@          FcFreeTypeQuery 
+@TYPE1@         const char *			@ARG1@          file      
+@TYPE2@         int				@ARG2@          id      
+@TYPE3@         FcBlanks *			@ARG3@          blanks      
+@TYPE4@         int *				@ARG4@          count      
+@PURPOSE@	compute font file pattern
+@DESC@
+Constructs a pattern representing the 'id'th font in 'file'.  The number
+of fonts in 'file' is returned in 'count'.
+@@
diff --git a/doc/fcinit.fncs b/doc/fcinit.fncs
new file mode 100644
index 00000000..bdf83fd8
--- /dev/null
+++ b/doc/fcinit.fncs
@@ -0,0 +1,78 @@
+/*
+ * $Id$
+ *
+ * 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 Keith Packard not be used in
+ * advertising or publicity pertaining to distribution of the software without
+ * specific, written prior permission.  Keith Packard makes no
+ * representations about the suitability of this software for any purpose.  It
+ * is provided "as is" without express or implied warranty.
+ *
+ * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+ * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+ * EVENT SHALL KEITH PACKARD 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.
+ */
+@RET@		FcConfig *
+@FUNC@		FcInitLoadConfig
+@TYPE1@		void
+@PURPOSE@	load configuration
+@DESC@
+Loads the default configuration file and returns the resulting configuration.
+Does not load any font information.
+@@
+
+@RET@           FcConfig *      
+@FUNC@          FcInitLoadConfigAndFonts 
+@TYPE1@		void
+@PURPOSE@	load configuration and font data
+@DESC@
+Loads the default configuration file and builds information about the
+available fonts.  Returns the resulting configuration.
+@@
+
+@RET@           FcBool       
+@FUNC@          FcInit 
+@TYPE1@		void
+@PURPOSE@	initialize fontconfig library
+@DESC@
+Loads the default configuration file and the fonts referenced therein and
+sets the default configuration to that result.  Returns whether this
+process succeeded or not.  If the default configuration has already
+been loaded, this routine does nothing and returns FcTrue.
+@@
+
+@RET@           int       
+@FUNC@          FcGetVersion 
+@TYPE1@		void
+@PURPOSE@	library version number
+@DESC@
+Returns the version number of the library.
+@@
+
+@RET@           FcBool       
+@FUNC@          FcInitReinitialize 
+@TYPE1@		void
+@PURPOSE@	re-initialize library
+@DESC@
+Forces the default configuration file to be reloaded and resets the default
+configuration.
+@@
+
+@RET@           FcBool       
+@FUNC@          FcInitBringUptoDate 
+@TYPE1@		void
+@PURPOSE@	reload configuration files if needed
+@DESC@
+Checks the rescan interval in the default configuration, checking the
+configuration if the interval has passed and reloading the configuration if
+when any changes are detected.
+@@
diff --git a/doc/fcstring.fncs b/doc/fcstring.fncs
new file mode 100644
index 00000000..56254f9e
--- /dev/null
+++ b/doc/fcstring.fncs
@@ -0,0 +1,150 @@
+/*
+ * $Id$
+ *
+ * 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 Keith Packard not be used in
+ * advertising or publicity pertaining to distribution of the software without
+ * specific, written prior permission.  Keith Packard makes no
+ * representations about the suitability of this software for any purpose.  It
+ * is provided "as is" without express or implied warranty.
+ *
+ * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+ * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+ * EVENT SHALL KEITH PACKARD 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.
+ */
+    <variablelist>
+
+@RET@		int
+@FUNC@		FcUtf8ToUcs4 
+@TYPE1@		FcChar8 *			@ARG1@		src
+@TYPE2@		FcChar32 *			@ARG2@		dst
+@TYPE3@		int 				@ARG3@		len
+@PURPOSE@	convert UTF-8 to UCS4
+@DESC@
+Converts the next Unicode char from <parameter>src</parameter> into
+<parameter>dst</parameter> and returns the number of bytes containing the
+char.  <parameter>src</parameter> nust be at least
+<parameter>len</parameter> bytes long.
+@@
+
+@RET@		int 
+@FUNC@		FcUcs4ToUtf8
+@TYPE1@		FcChar32 			@ARG1@		src	 
+@TYPE2@		FcChar8 			@ARG2@		dst[FC_UTF8_MAX_LEN]
+@PURPOSE@	convert UCS4 to UTF-8
+@DESC@
+Converts the Unicode char from <parameter>src</parameter> into
+<parameter>dst</parameter> and returns the number of bytes needed to encode
+the char.
+@@
+
+@RET@		FcBool 
+@FUNC@		FcUtf8Len
+@TYPE1@		FcChar8 *			@ARG1@		src
+@TYPE2@		int 				@ARG2@		len
+@TYPE3@		int *				@ARG3@		nchar
+@TYPE4@		int *				@ARG4@		wchar
+@PURPOSE@	count UTF-8 encoded chars
+@DESC@
+Counts the number of Unicode chars in <parameter>len</parameter> bytes of
+<parameter>src</parameter>.  Places that count in
+<parameter>nchar</parameter>.  <parameter>wchar</parameter> contains 1, 2 or
+4 depending on the number of bytes needed to hold the largest unicode char
+counted.  The return value indicates whether <parameter>src</parameter> is a
+well-formed UTF8 string.
+@@
+
+@RET@		int 
+@FUNC@		FcUtf16ToUcs4
+@TYPE1@		FcChar8 *			@ARG1@		src
+@TYPE2@		FcEndian 			@ARG2@		endian
+@TYPE3@		FcChar32 *			@ARG3@		dst
+@TYPE4@		int 				@ARG4@		len
+@PURPOSE@	convert UTF-16 to UCS4
+@DESC@
+Converts the next Unicode char from <parameter>src</parameter> into
+<parameter>dst</parameter> and returns the number of bytes containing the
+char. <parameter>src</parameter> must be at least <parameter>len</parameter>
+bytes long.  Bytes of <parameter>src</parameter> are combined into 16-bit
+units according to <parameter>endian</parameter>.
+@@
+
+@RET@		FcBool
+@FUNC@		FcUtf16Len
+@TYPE1@		FcChar8 *			@ARG1@		src
+@TYPE2@		FcEndian 			@ARG2@		endian
+@TYPE3@		int 				@ARG3@		len
+@TYPE4@		int *				@ARG4@		nchar
+@TYPE5@		int *				@ARG5@		wchar
+@PURPOSE@	count UTF-16 encoded chars
+@DESC@
+Counts the number of Unicode chars in <parameter>len</parameter> bytes of
+<parameter>src</parameter>.  Bytes of <parameter>src</parameter> are
+combined into 16-bit units according to <parameter>endian</parameter>.
+Places that count in <parameter>nchar</parameter>.
+<parameter>wchar</parameter> contains 1, 2 or 4 depending on the number of
+bytes needed to hold the largest unicode char counted.  The return value
+indicates whether <parameter>string</parameter> is a well-formed UTF16
+string.
+@@
+
+@RET@		FcChar8 *
+@FUNC@		FcStrCopy
+@TYPE1@		const FcChar8 *			@ARG1@		s
+@PURPOSE@	duplicate a string
+@DESC@
+Allocates memory, copies <parameter>s</parameter> and returns the resulting
+buffer.  Yes, this is <function>strdup</function>, but that function isn't
+available on every platform.
+@@
+
+@RET@		FcChar8 *
+@FUNC@		FcStrCopyFilename
+@TYPE1@		const FcChar8 *			@ARG1@		s
+@PURPOSE@	copy a string, expanding '~'
+@DESC@
+Just like FcStrCopy except that it converts any leading '~' characters in
+<parameter>s</parameter> to the value of the HOME environment variable.
+Returns NULL if '~' is present in <parameter>s</parameter> and HOME is unset.
+@@
+
+@RET@		int
+@FUNC@		FcStrCmpIgnoreCase
+@TYPE1@		const char *			@ARG1@		s1
+@TYPE2@		const char *			@ARG2@		s2
+@PURPOSE@	compare UTF-8 strings ignoring ASCII case
+@DESC@
+Returns the usual &lt;0, 0, &gt;0 result of comparing
+<parameter>s1</parameter> and <parameter>s2</parameter>.  This test is
+case-insensitive in the ASCII range and will operate properly with UTF8
+encoded strings, although it does not check for well formed strings.
+@@
+
+@RET@		FcChar8 *
+@FUNC@		FcStrDirname
+@TYPE1@		const FcChar8 *			@ARG1@		file
+@PURPOSE@	directory part of filename
+@DESC@
+Returns the directory containing <parameter>file</parameter>.  This
+is returned in newly allocated storage which should be freed when no longer
+needed.
+@@
+
+@RET@		FcChar8 *
+@FUNC@		FcStrBasename
+@TYPE1@		const FcChar8 *			@ARG1@		file
+@PURPOSE@	last component of filename
+@DESC@
+Returns the filename of <parameter>file</parameter> stripped of any leading
+directory names.  This is returned in newly allocated storage which should
+be freed when no longer needed.
+@@
diff --git a/doc/fcstrset.fncs b/doc/fcstrset.fncs
new file mode 100644
index 00000000..9013bc9d
--- /dev/null
+++ b/doc/fcstrset.fncs
@@ -0,0 +1,104 @@
+/*
+ * $Id$
+ *
+ * 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 Keith Packard not be used in
+ * advertising or publicity pertaining to distribution of the software without
+ * specific, written prior permission.  Keith Packard makes no
+ * representations about the suitability of this software for any purpose.  It
+ * is provided "as is" without express or implied warranty.
+ *
+ * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+ * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+ * EVENT SHALL KEITH PACKARD 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.
+ */
+    <variablelist>
+
+@RET@		FcStrSet *	
+@FUNC@		FcStrSetCreate 
+@TYPE1@		void
+@PURPOSE@	create a string set
+@DESC@
+Create an empty set.
+@@
+
+@RET@		FcBool
+@FUNC@		FcStrSetMember
+@TYPE1@		FcStrSet *			@ARG1@		set
+@TYPE2@		const FcChar8 *			@ARG2@		s	
+@PURPOSE@	check set for membership
+@DESC@
+Returns whether <parameter>s</parameter> is a member of
+<parameter>set</parameter>.
+@@
+
+@RET@		FcBool
+@FUNC@		FcStrSetAdd
+@TYPE1@		FcStrSet *			@ARG1@		set
+@TYPE2@		const FcChar8 *			@ARG2@		s	
+@PURPOSE@	add to a string set
+@DESC@
+Adds a copy of <parameter>s</parameter> to <parameter>set</parameter>.
+@@
+
+@RET@		FcBool
+@FUNC@		FcStrSetAddFilename
+@TYPE1@		FcStrSet *			@ARG1@		set
+@TYPE2@		const FcChar8 *			@ARG2@		s	
+@PURPOSE@	add a filename to a string set
+@DESC@
+Adds a copy <parameter>s</parameter> to <parameter>set</parameter>, The copy
+is created with FcStrCopyFilename so that leading '~' values are replaced
+with the value of the HOME environment variable.
+@@
+
+@RET@		FcBool
+@FUNC@		FcStrSetDel
+@TYPE1@		FcStrSet *			@ARG1@		set
+@TYPE2@		const FcChar8 *			@ARG2@		s	
+@PURPOSE@	delete from a string set
+@DESC@
+Removes <parameter>s</parameter> from <parameter>set</parameter>, returning
+FcTrue if <parameter>s</parameter> was a member else FcFalse.
+@@
+
+@RET@		void
+@FUNC@		FcStrSetDestroy
+@TYPE1@		FcStrSet *			@ARG1@		set	
+@PURPOSE@	destroy a string set
+@DESC@
+Destroys <parameter>set</parameter>.
+@@
+
+@RET@		FcStrList *
+@FUNC@		FcStrListCreate
+@TYPE1@		FcStrSet *			@ARG1@		set	
+@PURPOSE@	create a string iterator
+@DESC@
+Creates an iterator to list the strings in <parameter>set</parameter>.
+@@
+
+@RET@		FcChar8 *
+@FUNC@		FcStrListNext
+@TYPE1@		FcStrList *			@ARG1@		list	
+@PURPOSE@	get next string in iteration
+@DESC@
+Returns the next string in <parameter>set</parameter>.
+@@
+
+@RET@		void
+@FUNC@		FcStrListDone
+@TYPE1@		FcStrList *			@ARG1@		list	
+@PURPOSE@	destroy a string iterator
+@DESC@
+Destroys the enumerator <parameter>list</parameter>.
+@@
diff --git a/doc/fontconfig-devel.sgml b/doc/fontconfig-devel.sgml
index b8be3f18..1528fbc7 100644
--- a/doc/fontconfig-devel.sgml
+++ b/doc/fontconfig-devel.sgml
@@ -1,19 +1,25 @@
 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
-<!ENTITY fcmatrix SYSTEM "fcmatrix.sgml">
+<!ENTITY fcatomic SYSTEM "fcatomic.sgml">
+<!ENTITY fcblanks SYSTEM "fcblanks.sgml">
 <!ENTITY fccharset SYSTEM "fccharset.sgml">
-<!ENTITY fcvalue SYSTEM "fcvalue.sgml">
-<!ENTITY fcpattern SYSTEM "fcpattern.sgml">
+<!ENTITY fcconfig SYSTEM "fcconfig.sgml">
+<!ENTITY fcconstant SYSTEM "fcconstant.sgml">
+<!ENTITY fcfile SYSTEM "fcfile.sgml">
 <!ENTITY fcfontset SYSTEM "fcfontset.sgml">
+<!ENTITY fcfreetype SYSTEM "fcfreetype.sgml">
+<!ENTITY fcinit SYSTEM "fcinit.sgml">
+<!ENTITY fcmatrix SYSTEM "fcmatrix.sgml">
 <!ENTITY fcobjectset SYSTEM "fcobjectset.sgml">
 <!ENTITY fcobjecttype SYSTEM "fcobjecttype.sgml">
-<!ENTITY fcconstant SYSTEM "fcconstant.sgml">
-<!ENTITY fcblanks SYSTEM "fcblanks.sgml">
-<!ENTITY fcconfig SYSTEM "fcconfig.sgml">
+<!ENTITY fcpattern SYSTEM "fcpattern.sgml">
+<!ENTITY fcstring SYSTEM "fcstring.sgml">
+<!ENTITY fcstrset SYSTEM "fcstrset.sgml">
+<!ENTITY fcvalue SYSTEM "fcvalue.sgml">
 ]>
 <!--
     $Id$
    
-    Copyright © 2002 Keith Packard
+    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
@@ -173,25 +179,19 @@ convenience for the applications rendering mechanism.
     </programlisting>
   </sect2>
 </sect1>
-<sect1><title>DATATYPES</title>
+<sect1><title>Datatypes</title>
   <para>
 Fontconfig uses abstract datatypes to hide internal implementation details
 for most data structures.  A few structures are exposed where appropriate.
   </para>
-  <variablelist>
-  <varlistentry>
-    <term>FcChar8<term>
-    <term>FcChar16<term>
-    <term>FcChar32<term>
-    <term>FcBool</term>
-    <listitem>
+  <sect2><title>FcChar8, FcChar16, FcChar32, FcBool</title>
     <para>
 These are primitive datatypes; the FcChar* types hold precisely the number
 of bits stated (if supported by the C implementation).  FcBool holds
 one of two CPP symbols: FcFalse or FcTrue.
     </para>
-  </listitem></varlistentry>
-  <varlistentry><term>FcMatrix</term><listitem>
+  </sect2>
+  <sect2><title>FcMatrix</title>
     <para>
 An FcMatrix holds an affine transformation, usually used to reshape glyphs.
 A small set of matrix operations are provided to manipulate these.
@@ -201,19 +201,19 @@ A small set of matrix operations are provided to manipulate these.
         } FcMatrix;
     </programlisting>
     </para>
-  </listitem></varlistentry>
-  <varlistentry><term>FcCharSet</term><listitem>
+  </sect2>
+  <sect2><title>FcCharSet</title>
     <para>
 An FcCharSet is an abstract type that holds the set of encoded unicode chars
 in a font.  Operations to build and compare these sets are provided.
     </para>
-  </listitem></varlistentry>
-  <varlistentry><term>FcType</term><listitem>
+  </sect2>
+  <sect2><title>FcType</title>
     <para>
 Tags the kind of data stored in an FcValue.
     </para>
-  </listitem></varlistentry>
-  <varlistentry><term>FcValue</term><listitem>
+  </sect2>
+  <sect2><title>FcValue</title>
     <para>
 An FcValue object holds a single value with one of a number of different
 types.  The 'type' tag indicates which member is valid.
@@ -244,8 +244,8 @@ types.  The 'type' tag indicates which member is valid.
         FcTypeCharSet   c               FcCharSet *
     </programlisting>
     </para>
-  </listitem></varlistentry>
-  <varlistentry><term>FcPattern</term><listitem>
+  </sect2>
+  <sect2><title>FcPattern</title>
     <para>
 holds a set of names with associated value lists; each name refers to a
 property of a font.  FcPatterns are used as inputs to the matching code as
@@ -253,8 +253,8 @@ well as holding information about specific fonts.  Each property can hold
 one or more values; conventionally all of the same type, although the
 interface doesn't demand that.
     </para>
-  </listitem></varlistentry>
-  <varlistentry><term>FcFontSet</term><listitem>
+  </sect2>
+  <sect2><title>FcFontSet</title>
     <para>
     <programlisting>
         typedef struct _FcFontSet {
@@ -269,8 +269,8 @@ results of listing fonts in this format.  'nfont' holds the number of
 patterns in the 'fonts' array; 'sfont' is used to indicate the size of that
 array.
     </para>
-  </listitem></varlistentry>
-  <varlistentry><term>FcStrSet</term><term>FcStrList</term><listitem>
+  </sect2>
+  <sect2><title>FcStrSet, FcStrList</title>
     <para>
 FcStrSet holds a list of strings that can be appended to and enumerated.
 Its unique characteristic is that the enumeration works even while strings
@@ -278,8 +278,8 @@ are appended during enumeration.  FcStrList is used during enumeration to
 safely and correctly walk the list of strings even while that list is edited
 in the middle of enumeration.
     </para>
-  </listitem></varlistentry>
-  <varlistentry><term>FcObjectSet</term><listitem>
+  </sect2>
+  <sect2><title>FcObjectSet</title>
     <para>
       <programlisting>
         typedef struct _FcObjectSet {
@@ -291,8 +291,8 @@ in the middle of enumeration.
 holds a set of names and is used to specify which fields from fonts are
 placed in the the list of returned patterns when listing fonts.
     </para>
-  </listitem></varlistentry>
-  <varlistentry><term>FcObjectType</term><listitem>
+  </sect2>
+  <sect2><title>FcObjectType</title>
     <para>
       <programlisting>
         typedef struct _FcObjectType {
@@ -304,8 +304,8 @@ marks the type of a pattern element generated when parsing font names.
 Applications can add new object types so that font names may contain the new
 elements.
     </para>
-  </listitem></varlistentry>
-  <varlistentry><term>FcConstant</term><listitem>
+  </sect2>
+  <sect2><title>FcConstant</title>
     <para>
       <programlisting>
         typedef struct _FcConstant {
@@ -317,22 +317,22 @@ elements.
 Provides for symbolic constants for new pattern elements.  When 'name' is
 seen in a font name, an 'object' element is created with value 'value'.
     </para>
-  </listitem></varlistentry>
-  <varlistentry><term>FcBlanks</term><listitem>
+  </sect2>
+  <sect2><title>FcBlanks</title>
     <para>
 holds a list of Unicode chars which are expected to be blank; unexpectedly
 blank chars are assumed to be invalid and are elided from the charset
 associated with the font.
     </para>
-  </listitem></varlistentry>
-  <varlistentry><term>FcFileCache</term><listitem>
+  </sect2>
+  <sect2><title>FcFileCache</title>
     <para>
 holds the per-user cache information for use while loading the font
 database. This is built automatically for the current configuration when
 that is loaded.  Applications must always pass '0' when one is requested.
     </para>
-  </listitem></varlistentry>
-  <varlistentry><term>FcConfig</term><listitem>
+  </sect2>
+  <sect2><title>FcConfig</title>
     <para>
 holds a complete configuration of the library; there is one default
 configuration, other can be constructed from XML data structures.  All
@@ -343,15 +343,15 @@ second set holds those added by the application at run-time.  Interfaces
 that need to reference a particulat set use one of the FcSetName enumerated
 values.
     </para>
-  </listitem></varlistentry>
-  <varlistentry><term>FcSetName</term><listitem>
+  </sect2>
+  <sect2><title>FcSetName</title>
     <para>
 Specifies one of the two sets of fonts available in a configuration;
 FcSetSystem for those fonts specified in the configuration and
 FcSetApplication which holds fonts provided by the application.
     </para>
-  </listitem></varlistentry>
-  <varlistentry><term>FcResult</term><listitem>
+  </sect2>
+  <sect2><title>FcResult</title>
     <para>
 Used as a return type for functions manipulating FcPattern objects.
     <programlisting>
@@ -365,44 +365,24 @@ Used as a return type for functions manipulating FcPattern objects.
                                 than specified
     </programlisting>
     </para>
-  </listitem></varlistentry>
-  <varlistentry><term>FcAtomic</term><listitem>
+  </sect2>
+  <sect2><title>FcAtomic</title>
     <para>
 Used for locking access to config files.  Provides a safe way to update
 configuration files.
     </para>
-  </listitem></varlistentry>
-  </variablelist>
+  </sect2>
 </sect1>
 <sect1><title>FUNCTIONS</title>
   <para>
-Functions are grouped by the main datatype involved
+These are grouped by functionality, often using the main datatype being
+manipulated.
   </para>
-  <sect2><title>FcMatrix</title>
-    <para>
-FcMatrix structures hold an affine transformation in matrix form.
-    </para>
-    &fcmatrix;
-  </sect2>
-  <sect2><title>FcCharSet</title>
-    <para>
-An FcCharSet is a boolean array indicating a set of unicode chars.  Those
-associated with a font are marked constant and cannot be edited.
-FcCharSets may be reference counted internally to reduce memory consumption;
-this may be visible to applications as the result of FcCharSetCopy may
-return it's argument, and that CharSet may remain unmodifiable.
-    </para>
-    &fccharset;
-  </sect2>
-  <sect2><title>FcValue</title>
+  <sect2><title>Initialization</title>
     <para>
-FcValue is a structure containing a type tag and a union of all possible
-datatypes.  The tag is an enum of type 
-<emphasis>FcType</emphasis>
-and is intended to provide a measure of run-time
-typechecking, although that depends on careful programming.
+These functions provide some control over how the library is initialized.
     </para>
-    &fcvalue;
+    &fcinit;
   </sect2>
   <sect2><title>FcPattern</title>
     <para>
@@ -426,6 +406,48 @@ FcFontList.
     </para>
     &fcobjectset;
   </sect2>
+  <sect2><title>FreeType specific functions</title>
+    <para>
+While the fontconfig library doesn't insist that FreeType be used as the
+rasterization mechanism for fonts, it does provide some convenience
+functions.
+    </para>
+    &fcfreetype;
+  </sect2>
+  <sect2><title>FcValue</title>
+    <para>
+FcValue is a structure containing a type tag and a union of all possible
+datatypes.  The tag is an enum of type 
+<emphasis>FcType</emphasis>
+and is intended to provide a measure of run-time
+typechecking, although that depends on careful programming.
+    </para>
+    &fcvalue;
+  </sect2>
+  <sect2><title>FcCharSet</title>
+    <para>
+An FcCharSet is a boolean array indicating a set of unicode chars.  Those
+associated with a font are marked constant and cannot be edited.
+FcCharSets may be reference counted internally to reduce memory consumption;
+this may be visible to applications as the result of FcCharSetCopy may
+return it's argument, and that CharSet may remain unmodifiable.
+    </para>
+    &fccharset;
+  </sect2>
+  <sect2><title>FcMatrix</title>
+    <para>
+FcMatrix structures hold an affine transformation in matrix form.
+    </para>
+    &fcmatrix;
+  </sect2>
+  <sect2><title>FcConfig</title>
+    <para>
+An FcConfig object holds the internal representation of a configuration.
+There is a default configuration which applications may use by passing 0 to
+any function using the data within an FcConfig.
+    </para>
+    &fcconfig;
+  </sect2>
   <sect2><title>FcObjectType</title>
     <para>
 Provides for applcation-specified font name object types so that new
@@ -449,309 +471,34 @@ accurate CharSet for applications.
     </para>
     &fcblanks;
   </sect2>
-  <sect2><title>FcConfig</title>
-    <para>
-An FcConfig object holds the internal representation of a configuration.
-There is a default configuration which applications may use by passing 0 to
-any function using the data within an FcConfig.
-    </para>
-    &fcconfig;
-  </sect2>
-  <sect2><title>Initialization</title>
-    <para>
-These functions provide some control over how the library is initialized.
-    </para>
-    <variablelist>
-    <varlistentry><term>
-FcConfig *FcInitLoadConfig (void);
-    </term><listitem><para>
-Loads the default configuration file and returns the resulting configuration.
-Does not load any font information.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcConfig *FcInitLoadConfigAndFonts (void);
-    </term><listitem><para>
-Loads the default configuration file and builds information about the
-available fonts.  Returns the resulting configuration.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcBool FcInit (void);
-    </term><listitem><para>
-Loads the default configuration file and the fonts referenced therein and
-sets the default configuration to that result.  Returns whether this
-process succeeded or not.  If the default configuration has already
-been loaded, this routine does nothing and returns FcTrue.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-int FcGetVersion (void);
-    </term><listitem><para>
-Returns the version number of the library.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcBool FcInitReinitialize (void);
-    </term><listitem><para>
-Forces the default configuration file to be reloaded and resets the default
-configuration.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcBool FcInitBringUptoDate (void);
-    </term><listitem><para>
-Checks the rescan interval in the default configuration, checking the
-configuration if the interval has passed and reloading the configuration if
-when any changes are detected.
-    </para></listitem></varlistentry>
-  </variablelist></sect2>
   <sect2><title>FcAtomic</title>
     <para>
 These functions provide a safe way to update config files, allowing ongoing
 reading of the old config file while locked for writing and ensuring that a
 consistent and complete version of the config file is always available.
     </para>
-    <variablelist>
-    <varlistentry><term>
-FcAtomic * FcAtomicCreate (const FcChar8   *file);
-    </term><listitem><para>
-Creates a data structure containing data needed to control access to 'file'.
-Writing is done to a separate file.  Once that file is complete, the original
-configuration file is atomically replaced so that reading process always see
-a consistent and complete file without the need to lock for reading.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcBool FcAtomicLock (FcAtomic *atomic);
-    </term><listitem><para>
-Attempts to lock the file referenced by 'atomic'.  Returns FcFalse if the
-file is locked by another process, else returns FcTrue and leaves the file
-locked.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcChar8 *FcAtomicNewFile (FcAtomic *atomic);
-    </term><listitem><para>
-Returns the filename for writing a new version of the file referenced
-by 'atomic'.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcChar8 *FcAtomicOrigFile (FcAtomic *atomic);
-    </term><listitem><para>
-Returns the file refernced by 'atomic'.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcBool FcAtomicReplaceOrig (FcAtomic *atomic);
-    </term><listitem><para>
-Replaces the original file referenced by 'atomic' with the new file.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-void FcAtomicDeleteNew (FcAtomic *atomic);
-    </term><listitem><para>
-Deletes the new file.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-void FcAtomicUnlock (FcAtomic *atomic);
-    </term><listitem><para>
-Unlocks the file.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-void FcAtomicDestroy (FcAtomic *atomic);
-    </term><listitem><para>
-Destroys 'atomic'.
-    </para></listitem></varlistentry>
-  </variablelist></sect2>
-  <sect2><title>FreeType specific functions</title>
-    <para>
-      <programlisting>
-#include &lt;fontconfig/fcfreetype.h&gt;
-      </programlisting>
-While the fontconfig library doesn't insist that FreeType be used as the
-rasterization mechanism for fonts, it does provide some convenience
-functions.
-    </para>
-    <variablelist>
-    <varlistentry><term>
-FT_UInt FcFreeTypeCharIndex (FT_Face face, FcChar32 ucs4);
-    </term><listitem><para>
-Maps a Unicode char to a glyph index.  This function uses information from
-several possible underlying encoding tables to work around broken fonts.
-As a result, this function isn't designed to be used in performance
-sensitive areas; results from this function are intended to be cached by
-higher level functions.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcCharSet *FcFreeTypeCharSet (FT_Face face, FcBlanks *blanks) Scans a
-    </term><listitem><para>
-FreeType face and returns the set of encoded Unicode chars.  This scans
-several encoding tables to build as complete a list as possible.  
-If 'blanks' is not 0, the glyphs in the font are examined and any blank glyphs
-not in 'blanks' are not placed in the returned FcCharSet.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcPattern *FcFreeTypeQuery (const char *file, int id, FcBlanks *blanks, int *count);
-    </term><listitem><para>
-Constructs a pattern representing the 'id'th font in 'file'.  The number
-of fonts in 'file' is returned in 'count'.
-    </para></listitem></varlistentry>
-  </variablelist></sect2>
-  <sect2><title>XML specific functions</title>
-    <variablelist>
-    <varlistentry><term>
-FcBool FcConfigParseAndLoad (FcConfig *config, const FcChar8 *file, FcBool complain);
-    </term><listitem><para>
-Walks the configuration in 'file' and constructs the internal representation
-in 'config'.  Any include files referenced from within 'file' will be loaded
-with FcConfigLoad and also parsed.  If 'complain' is FcFalse, no warning
-will be displayed if 'file' does not exist.
-    </para></listitem></varlistentry>
-  </variablelist></sect2>
+    &fcatomic;
+  </sect2>
   <sect2><title>File and Directory routines</title>
-    <variablelist>
-    <varlistentry><term>
-FcBool FcFileScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *file, FcBool force);
-    </term><listitem><para>
-Scans a single file and adds all fonts found to 'set'.  If 'force' is FcTrue,
-then the file is scanned even if associated information is found in 'cache'.
-If 'file' is a directory, it is added to 'dirs'.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcBool FcDirScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *dir, FcBool force);
-    </term><listitem><para>
-Scans an entire directory and adds all fonts found to 'set'.  If 'force' is
-FcTrue, then the directory and all files within it are scanned even if
-information is present in the per-directory cache file or 'cache'.  Any
-subdirectories found are added to 'dirs'.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcBool FcDirSave (FcFontSet *set, FcStrSet *dirs, const char *dir);
-    </term><listitem><para>
-Creates the per-directory cache file for 'dir' and populates it with the
-fonts in 'set' and subdirectories in 'dirs'.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcBool FcDirCacheValid (const FcChar8 *cache_file);
-    </term><listitem><para>
-Returns FcTrue if 'cache_file' is no older than the directory containing it,
-else FcFalse.
-    </para></listitem></varlistentry>
-  </variablelist></sect2>
+    <para>
+These routines work with font files and directories, including font
+directory cache files.
+    &fcfile;
+  </sect2>
   <sect2><title>FcStrSet and FcStrList</title>
     <para>
 A data structure for enumerating strings, used to list directories while
 scanning the configuration as directories are added while scanning.
     </para>
-    <variablelist>
-    <varlistentry><term>
-FcStrSet *FcStrSetCreate (void);
-    </term><listitem><para>
-Create an empty set.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcBool FcStrSetMember (FcStrSet *set, const FcChar8 *s);
-    </term><listitem><para>
-Returns whether 's' is a member of 'set'.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcBool FcStrSetAdd (FcStrSet *set, const FcChar8 *s);
-    </term><listitem><para>
-Adds a copy of 's' to 'set'.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcBool FcStrSetAddFilename (FcStrSet *set, const FcChar8 *s);
-    </term><listitem><para>
-Adds a copy 's' to 'set', The copy is created with FcStrCopyFilename
-so that leading '~' values are replaced with the value of the HOME
-environment variable.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcBool FcStrSetDel (FcStrSet *set, const FcChar8 *s);
-    </term><listitem><para>
-Removes 's' from 'set', returning FcTrue if 's' was a member else FcFalse.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-void FcStrSetDestroy (FcStrSet *set);
-    </term><listitem><para>
-Destroys 'set'.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcStrList *FcStrListCreate (FcStrSet *set);
-    </term><listitem><para>
-Creates an enumerator to list the strings in 'set'.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcChar8 *FcStrListNext (FcStrList *list);
-    </term><listitem><para>
-Returns the next string in 'set'.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-void FcStrListDone (FcStrList *list);
-    </term><listitem><para>
-Destroys the enumerator 'list'.
-    </para></listitem></varlistentry>
-  </variablelist></sect2>
+    &fcstrset;
+  </sect2>
   <sect2><title>String utilities</title>
-    <variablelist>
-    <varlistentry><term>
-int FcUtf8ToUcs4 (FcChar8 *src, FcChar32 *dst, int len);
-    </term><listitem>
-    <para>
-Converts the next Unicode char from 'src' into 'dst' and returns the number
-of bytes containing the char.  'src' nust be at least 'len' bytes long.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-int FcUcs4ToUtf8 (FcChar32 src, FcChar8 dst[FC_UTF8_MAX_LEN]);
-    </term><listitem><para>
-Converts the Unicode char from 'src' into 'dst' and returns the
-number of bytes needed to encode the char.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcBool FcUtf8Len (FcChar8 *src, int len, int *nchar, int *wchar);
-    </term><listitem><para>
-Counts the number of Unicode chars in 'len' bytes of 'src'.  Places that
-count in 'nchar'.  'wchar' contains 1, 2 or 4 depending on the number of
-bytes needed to hold the largest unicode char counted.  The return value
-indicates whether 'src' is a well-formed UTF8 string.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-int FcUtf16ToUcs4 (FcChar8 *src, FcEndian endian, FcChar32 *dst, int len);
-    </term><listitem><para>
-Converts the next Unicode char from 'src' into 'dst' and returns the
-number of bytes containing the char. 'src' must be at least 'len' bytes
-long.  Bytes of 'src' are combined into 16-bit units according to 'endian'.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcBool FcUtf16Len (FcChar8 *src, FcEndian endian, int len, int *nchar, int *wchar);
-    </term><listitem><para>
-Counts the number of Unicode chars in 'len' bytes of 'src'.  Bytes of 'src'
-are combined into 16-bit units according to 'endian'.  Places that
-count in 'nchar'.  'wchar' contains 1, 2 or 4 depending on the number of
-bytes needed to hold the largest unicode char counted.  The return value
-indicates whether 'string' is a well-formed UTF16 string.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcChar8 *FcStrCopy (const FcChar8 *s);
-    </term><listitem><para>
-Allocates memory, copies 's' and returns the resulting buffer.  Yes, this
-is 'strdup', but that function isn't available on every platform.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcChar8 *FcStrCopyFilename (const FcChar8 *s);
-    </term><listitem><para>
-Just like FcStrCopy except that it converts any leading '~' characters 
-in 's' to the value of the HOME environment variable.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-int FcStrCmpIgnoreCase (const char *s1, const char *s2);
-    </term><listitem><para>
-Returns the usual &lt;0, 0, &gt;0 result of comparing 's1' and 's2'.  This test
-is case-insensitive in the ASCII range and will operate properly with UTF8
-encoded strings, although it does not check for well formed strings.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcChar8 *FcStrDirname (const FcChar8 *file);
-    </term><listitem><para>
-Returns the directory containing 'file'.
-    </para></listitem></varlistentry>
-    <varlistentry><term>
-FcChar8 *FcStrBasename (const FcChar8 *file);
-    </term><listitem><para>
-Returns the filename of 'file' stripped of any leading directory names.
-    </para></listitem></varlistentry>
-  </variablelist></sect2>
+    <para>
+Fontconfig manipulates many UTF-8 strings represented with the FcChar8 type.
+These functions are exposed to help applications deal with these UTF-8
+strings in a locale-insensitive manner.
+    </para>
+    &fcstring;
+  </sect2>
 </sect1>
 </article>