Document previously undocumented functions. (bug 12963)

16 files changed, 638 insertions, 30 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 7b40eb4..e5c922b 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -42,13 +42,16 @@ FNCS_TMPL = ${DOC_SRC}/func.sgml
 DOC_FUNCS_FNCS=\
 	fcatomic.fncs \
 	fcblanks.fncs \
+	fccache.fncs \
 	fccharset.fncs \
 	fcconfig.fncs \
 	fcconstant.fncs \
+	fcdircache.fncs \
 	fcfile.fncs \
 	fcfontset.fncs \
 	fcfreetype.fncs \
 	fcinit.fncs \
+	fclangset.fncs \
 	fcmatrix.fncs \
 	fcobjectset.fncs \
 	fcobjecttype.fncs \
diff --git a/doc/check-missing-doc b/doc/check-missing-doc
index 13d1eb9..3eef93a 100644
--- a/doc/check-missing-doc
+++ b/doc/check-missing-doc
@@ -1,7 +1,7 @@
 #!/bin/sh
 header=fontconfig-header
 doc=fontconfig-doc
-#trap "rm $header $doc"  0 1 15
+trap "rm $header $doc"  0 1 15
 top_srcdir=${top_srcdir-".."}
 (
 cat $top_srcdir/fontconfig/*.h  | grep '^Fc' | 
@@ -10,7 +10,7 @@ cat $top_srcdir/fontconfig/*.h  | grep '^Fc' |
  sed -n 's/#define \(Fc[a-zA-Z]*\)(.*$/\1/p') |
  sort -u > $header
 
-grep '@FUNC@' $top_srcdir/doc/*.fncs |
+grep '@FUNC[+]*@' $top_srcdir/doc/*.fncs |
 awk '{print $2}' |
 sort -u > $doc
 
diff --git a/doc/fccache.fncs b/doc/fccache.fncs
new file mode 100644
index 0000000..0a08632
--- /dev/null
+++ b/doc/fccache.fncs
@@ -0,0 +1,68 @@
+/*
+ * Copyright © 2007 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@           const FcChar8 *
+@FUNC@          FcCacheDir
+@TYPE1@		const FcCache *			@ARG1@		cache
+@PURPOSE@	Return directory of <parameter>cache</parameter>
+@DESC@
+This function returns the directory from which the cache was constructed.
+@@
+
+@RET@		FcFontSet *
+@FUNC@		FcCacheCopySet
+@TYPE1@		const FcCache *			@ARG1@		cache
+@PURPOSE@	Returns a copy of the fontset from <parameter>cache</parameter>
+@DESC
+The returned fontset contains each of the font patterns from
+<parameter>cache</parameter>. This fontset may be modified, but the patterns
+from the cache are read-only.
+@@
+
+@RET@		const FcChar8 *
+@FUNC@		FcCacheSubdir
+@TYPE1@		const FcCache *			@ARG1@		cache
+@TYPE2@		int				@ARG2@		i
+@PURPOSE@	Return the <parameter>i</parameter>'th subdirectory.
+@DESC
+The set of subdirectories stored in a cache file are indexed by this
+function, <parameter>i</parameter> should range from 0 to
+<parameter>n</parameter>-1, where <parameter>n</parameter> is the return
+value from FcCacheNumSubdir.
+@@
+
+@RET@		int
+@FUNC@		FcCacheNumSubdir
+@TYPE1@		const FcCache *			@ARG1@		cache
+@PURPOSE@	Return the number of subdirectories in <parameter>cache</parameter>.
+@DESC
+This returns the total number of subdirectories in the cache.
+@@
+
+@RET@		int
+@FUNC@		FcCacheNumFont
+@TYPE1@		const FcCache *			@ARG1@		cache
+@PURPOSE@	Returns the number of fonts in <parameter>cache</parameter>.
+@DESC
+This returns the number of fonts which would be included in the return from
+FcCacheCopySet.
+@@
diff --git a/doc/fccharset.fncs b/doc/fccharset.fncs
index cb07680..f4e81a7 100644
--- a/doc/fccharset.fncs
+++ b/doc/fccharset.fncs
@@ -165,3 +165,27 @@ Builds an array of bits marking the Unicode coverage of <parameter>a</parameter>
 <parameter>*next</parameter>. Returns the base of the array. <parameter>next</parameter> contains the next page in
 the font. 
 @@
+
+@RET@		FcChar32
+@FUNC@		FcCharSetCoverage
+@TYPE1@		const FcCharSet *	@ARG1@		a
+@TYPE2@		FcChar32		@ARG2@		page
+@TYPE3@		FcChar32[8] 		@ARG3@		result
+@PURPOSE@	DEPRECATED return coverage for a Unicode page
+@DESC@
+DEPRECATED
+This function returns a bitmask in <parameter>result</parameter> which
+indicates which code points in
+<parameter>page</parameter> are included in <parameter>a</parameter>.
+<function>FcCharSetCoverage</function> returns the next page in the charset which has any
+coverage.
+@@
+
+@RET@		FcCharSet *
+@FUNC@		FcCharSetNew
+@TYPE1@		void
+@PURPOSE@	DEPRECATED alias for FcCharSetCreate
+@DESC@
+<function>FcCharSetNew</function> is a DEPRECATED alias for FcCharSetCreate.
+@@
+
diff --git a/doc/fcconfig.fncs b/doc/fcconfig.fncs
index d252d60..998974f 100644
--- a/doc/fcconfig.fncs
+++ b/doc/fcconfig.fncs
@@ -65,6 +65,27 @@ Checks all of the files related to <parameter>config</parameter> and returns
 whether any of them has been modified since the configuration was created.
 @@
 
+@RET@		FcBool
+@FUNC@		FcConfigHome
+@TYPE1@		void
+@PURPOSE@	return the current home directory.
+@DESC@
+Return the current user's home directory, if it is available, and if using it
+is enabled. See also <function>FcConfigEnableHome</function>).
+@@
+
+@RET@		FcBol
+@FUNC@		FcConfigEnableHome
+@TYPE1@		FcBool%				@ARG1@		enable
+@PURPOSE@	controls use of the home directory.
+@DESC@
+If <parameter>enable</parameter> is FcTrue, then Fontconfig will use various
+files which are specified relative to the user's home directory (using the ~
+notation in the configuration). When <parameter>enable</parameter> is
+FcFalse, then all use of the home directory in these contexts will be
+disabled. The previous setting of the value is returned.
+@@
+
 @RET@           FcBool
 @FUNC@          FcConfigBuildFonts
 @TYPE1@         FcConfig *                      @ARG1@          config
@@ -111,6 +132,16 @@ Note that this will not include any configuration done with FcConfigParse.
 Returns the name of the file used to store per-user font information.
 @@
 
+@RET@		FcStrList *
+@FUNC@		FcConfigGetCacheDirs
+@TYPE1@		FcConfig *			@ARG1@		config
+@PURPOSE@	return the list of directories searched for cache files
+@DESC@
+<function>FcConfigGetCacheDirs</function> returns a string list containing
+all of the directories that fontconfig will search when attempting to load a
+cache file for a font directory.
+@@
+
 @RET@           FcFontSet *
 @FUNC@          FcConfigGetFonts
 @TYPE1@         FcConfig *			@ARG1@		config
diff --git a/doc/fcdircache.fncs b/doc/fcdircache.fncs
new file mode 100644
index 0000000..24dea8b
--- /dev/null
+++ b/doc/fcdircache.fncs
@@ -0,0 +1,88 @@
+/*
+ * Copyright © 2007 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 the copyright holders not be used in advertising or
+ * publicity pertaining to distribution of the software without specific,
+ * written prior permission.  The copyright holders make no representations
+ * about the suitability of this software for any purpose.  It is provided "as
+ * is" without express or implied warranty.
+ *
+ * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+ * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+ * EVENT SHALL THE COPYRIGHT HOLDERS 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@		FcDirCacheUnlink
+@TYPE1@		const FcChar8 *			@ARG1@		dir
+@TYPE2@		FcConfig *			@ARG2@		config
+@PURPOSE@	Remove all caches related to <parameter>dir</parameter>
+@DESC@
+Scans the cache directories in <parameter>config</parameter>, removing any
+instances of the cache file for <parameter>dir</parameter>. Returns FcFalse
+when some internal error occurs (out of memory, etc). Errors actually
+unlinking any files are ignored.
+@@
+
+@RET@		FcBool 	
+@FUNC@		FcDirCacheValid 
+@TYPE1@		const FcChar8 *			@ARG1@		dir
+@PURPOSE@	check directory cache 
+@DESC@
+Returns FcTrue if <parameter>dir</parameter> has an associated valid cache
+file, else returns FcFalse
+@@
+
+@RET@		FcCache *
+@FUNC@		FcDirCacheLoad
+@TYPE1@		const FcChar8 *			@ARG1@		dir
+@TYPE2@		FcConfig *			@ARG2@		config
+@TYPE3@		FcChar8 **			@ARG3@		cache_file
+@PURPOSE@	load a directory cache
+@DESC@
+Loads the cache related to <parameter>dir</parameter>. If no cache file
+exists, returns NULL. The name of the cache file is returned in
+<parameter>cache_file</parameter>, unless that is NULL. See also
+FcDirCacheRead.
+@@
+
+@RET@		FcCache *
+@FUNC@		FcDirCacheRead
+@TYPE1@		const FcChar8 *			@ARG1@		dir
+@TYPE2@		FcBool%				@ARG2@		force
+@TYPE3@		FcConfig *			@ARG3@		config
+@PURPOSE@	read or construct a directory cache
+@DESC@
+This returns a cache for <parameter>dir</parameter>. If
+<parameter>force</parameter> is FcFalse, then an existing, valid cache file
+will be used. Otherwise, a new cache will be created by scanning the
+directory and that returned.
+@@
+
+@RET@		FcCache *
+@FUNC@		FcDirCacheLoadFile
+@TYPE1@		const FcChar8 *			@ARG1@		cache_file
+@TYPE2@		struct stat *			@ARG2@		file_stat
+@PURPOSE@	load a cache file
+@DESC@
+This function loads a directory cache from
+<parameter>cache_file</parameter>. If <parameter>file_stat</parameter> is
+non-NULL, it will be filled with the results of stat(2) on the cache file.
+@@
+
+@RET@		void
+@FUNC@		FcDirCacheUnload
+@TYPE1@		FcCache *			@ARG1@		cache
+@PURPOSE@	unload a cache file
+@DESC@
+This function dereferences <parameter>cache</parameter>. When no other
+references to it remain, all memory associated with the cache will be freed.
+@@
diff --git a/doc/fcfile.fncs b/doc/fcfile.fncs
index df7400b..98b8f81 100644
--- a/doc/fcfile.fncs
+++ b/doc/fcfile.fncs
@@ -37,7 +37,20 @@ 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>. Whether fonts are found depends on fontconfig
-poliy as well as the current configuration.
+policy as well as the current configuration. Internally, fontconfig will
+ignore BDF and PCF fonts which are not in Unicode (or the effectively
+equivalent ISO Latin-1) encoding as those are not usable by Unicode-based
+applications. The configuration can ignore fonts based on filename or
+contents of the font file itself.
+@@
+
+@RET@		FcBool
+@FUNC@		FcFileIsDir
+@TYPE1@		const FcChar8 *			@ARG1@		file
+@PURPOSE@	check whether a file is a directory
+@DESC@
+Returns FcTrue if <parameter>file</parameter> is a directory, otherwise
+returns FcFalse.
 @@
 
 @RET@		FcBool 	
@@ -54,9 +67,9 @@ 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>. Whether fonts
-or directories are found depends on fontconfig
-policy as well as the current configuration.
+subdirectories found are added to <parameter>dirs</parameter>. See the
+manual for <function>FcFileScan</function> for a description of how
+fontconfig selects which fonts to include.
 @@
 
 @RET@		FcBool 	
@@ -71,11 +84,3 @@ 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/fcfontset.fncs b/doc/fcfontset.fncs
index 9c739c6..bcf4bd3 100644
--- a/doc/fcfontset.fncs
+++ b/doc/fcfontset.fncs
@@ -47,3 +47,86 @@ well.
 Adds a pattern to a font set.  Note that the pattern is not copied before
 being inserted into the set.
 @@
+
+@RET@		FcFontSet *
+@FUNC@		FcFontSetList
+@TYPE1@		FcConfig *			@ARG1@		config
+@TYPE2@		FcFontSet **			@ARG2@		sets
+@TYPE3@		int				@ARG3@		nsets
+@TYPE4@		FcPattern *			@ARG4@		pattern
+@TYPE5@		FcObjectSet *			@ARG5@		object_set
+@PURPOSE@	List fonts from a set of font sets
+@DESC@
+Selects fonts matching <parameter>pattern</parameter> from
+<parameter>sets</parameter>, creates patterns from those
+fonts containing only the objects in <parameter>object_set</parameter> and returns
+the set of unique such patterns.
+@@
+
+@RET@		FcPattern *
+@FUNC@		FcFontSetMatch
+@TYPE1@		FcConfig *			@ARG1@		config
+@TYPE2@		FcFontSet **			@ARG2@		sets
+@TYPE3@		int				@ARG3@		nsets
+@TYPE4@		FcPattern *			@ARG4@		pattern
+@TYPE5@		FcResult *			@ARG5@		result
+@PURPOSE@	Return the best font from a set of font sets
+@DESC@
+Returns the font in <parameter>sets</parameter> most close matching
+<parameter>pattern</parameter>.  This function should be called only after
+FcConfigSubstitute and FcDefaultSubstitute have been called for
+<parameter>pattern</parameter>; otherwise the results will not be correct.
+@@
+
+@RET@		void
+@FUNC@		FcFontSetPrint
+@TYPE1@		FcFontSet *			@ARG1@		set
+@PURPOSE@	Print a set of patterns to stdout
+@DESC@
+This function is useful for diagnosing font related issues, printing the
+complete contents of every pattern in <parameter>set</parameter>. The format
+of the output is designed to be of help to users and developers, and may
+change at any time.
+@@
+
+@RET@		
+@FUNC@		FcFontSetSort
+@TYPE1@         FcConfig *			@ARG1@		config
+@TYPE2@		FcFontSet **			@ARG2@		sets
+@TYPE3@		int				@ARG3@		nsets
+@TYPE4@		FcPattern *			@ARG4@		pattern
+@TYPE5@		FcBool%				@ARG5@		trim
+@TYPE6@		FcCharSet **			@ARG6@		csp
+@TYPE7@		FcResult *                      @ARG7@          result
+@PURPOSE@	Add to a font set
+@DESC@
+Returns the list of fonts from <parameter>sets</parameter>
+sorted by closeness to <parameter>pattern</parameter>.  
+If <parameter>trim</parameter> is FcTrue,
+elements in the list which don't include Unicode coverage not provided by
+earlier elements in the list are elided.  The union of Unicode coverage of
+all of the fonts is returned in <parameter>csp</parameter>,
+if <parameter>csp</parameter> is not NULL.  This function
+should be called only after FcConfigSubstitute and FcDefaultSubstitute have
+been called for <parameter>p</parameter>;
+otherwise the results will not be correct.
+    </para><para>
+The returned FcFontSet references FcPattern structures which may be shared
+by the return value from multiple FcFontSort calls, applications cannot
+modify these patterns.  Instead, they should be passed, along with
+<parameter>pattern</parameter> to
+FcFontRenderPrepare which combines them into a complete pattern.
+    </para><para>
+The FcFontSet returned by FcFontSetSort is destroyed by caling FcFontSetDestroy.
+@@
+
+@RET@		
+@FUNC@		FcFontSetSortDestroy
+@TYPE1@		FcFontSet *			@ARG1@		set
+@PURPOSE@	DEPRECATED destroy a font set
+@DESC@
+This function is DEPRECATED. <function>FcFontSetSortDestroy</function>
+destroys <parameter>set</parameter> by calling
+<function>FcFontSetDestroy</function>. Applications should use
+<function>FcFontSetDestroy</function> directly instead.
+@@
diff --git a/doc/fcfreetype.fncs b/doc/fcfreetype.fncs
index 6ecedda..935eacf 100644
--- a/doc/fcfreetype.fncs
+++ b/doc/fcfreetype.fncs
@@ -56,6 +56,28 @@ not in 'blanks' are not placed in the returned FcCharSet.
 @SYNOPSIS@
 #include &lt;fontconfig.h&gt;
 #include &lt;fcfreetype.h&gt;
+@RET@           FcCharSet *      
+@FUNC@          FcFreeTypeCharSetAndSpacing 
+@TYPE1@         FT_Face%			@ARG1@          face      
+@TYPE2@         FcBlanks *			@ARG2@          blanks
+@TYPE3@		int *				@ARG3@		spacing
+@PURPOSE@	compute unicode coverage and spacing type
+@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.
+<parameter>spacing</parameter> receives the computed spacing type of the
+font, one of FC_MONO for a font where all glyphs have the same width,
+FC_DUAL, where the font has glyphs in precisely two widths, one twice as
+wide as the other, or FC_PROPORTIONAL where the font has glyphs of many
+widths.  
+@@
+
+@SYNOPSIS@
+#include &lt;fontconfig.h&gt;
+#include &lt;fcfreetype.h&gt;
 @RET@           FcPattern *      
 @FUNC@          FcFreeTypeQuery 
 @TYPE1@         const char *			@ARG1@          file      
diff --git a/doc/fclangset.fncs b/doc/fclangset.fncs
new file mode 100644
index 0000000..eb4a937
--- /dev/null
+++ b/doc/fclangset.fncs
@@ -0,0 +1,124 @@
+/*
+ * Copyright © 2007 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 the copyright holders not be used in advertising or
+ * publicity pertaining to distribution of the software without specific,
+ * written prior permission.  The copyright holders make no representations
+ * about the suitability of this software for any purpose.  It is provided "as
+ * is" without express or implied warranty.
+ *
+ * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+ * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+ * EVENT SHALL THE COPYRIGHT HOLDERS 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@		FcLangSet *
+@FUNC@		FcLangSetCreate
+@TYPE1@		void
+@PURPOSE@	create a langset object
+@DESC@
+<function>FcLangSetCreate</function> creates a new FcLangSet object.
+@@
+
+@RET@		void
+@FUNC@		FcLangSetDestroy
+@TYPE1@		FcLangSet *			@ARG1@		ls
+@PURPOSE@	destroy a langset object
+@DESC@
+<function>FcLangSetDestroy</function> destroys a FcLangSet object, freeing
+all memory associated with it.
+@@
+
+@RET@		FcLangSet *
+@FUNC@		FcLangSetCopy
+@TYPE1@		const FcLangSet *		@ARG1@		ls
+@PURPOSE@	copy a langset object
+@DESC@
+<function>FcLangSetCopy</function> creates a new FcLangSet object and
+populates it with the contents of <parameter>ls</parameter>.
+@@
+
+@RET@		FcBool
+@FUNC@		FcLangSetAdd
+@TYPE1@		FcLangSet *			@ARG1@		ls
+@TYPE2@		const FcChar8 *			@ARG2@		lang
+@PURPOSE@	add a language to a langset
+@DESC@
+<parameter>lang</parameter> is added to <parameter>ls</parameter>.
+<parameter>lang</parameter> should be of the form Ll-Tt where Ll is a
+two or three letter language from ISO 639 and Tt is a territory from ISO
+3166.
+@@
+
+@RET@		FcLangResult
+@FUNC@		FcLangSetCompare
+@TYPE1@		const FcLangSet *		@ARG1@		ls_a
+@TYPE2@		const FcLangSet *		@ARG2@		ls_b
+@PURPOSE@	compare language sets
+@DESC@
+<function>FcLangSetCompare</function> compares language coverage for
+<parameter>ls_a</parameter> and <parameter>ls_b</parameter>. If they share
+any language and territory pair, this function returns FcLangEqual. If they
+share a language but differ in which territory that language is for, this
+function returns FcLangDiffentTerritory. If they share no languages in
+common, this function returns FcLangDifferentLang.
+@@
+
+@RET@		FcBool
+@FUNC@		FcLangSetContains
+@TYPE1@		const FcLangSet *		@ARG1@		ls_a
+@TYPE2@		const FcLangSet *		@ARG2@		ls_b
+@PURPOSE@	check langset subset relation
+@DESC@
+<function>FcLangSetContains</function> returns FcTrue if
+<parameter>ls_a</parameter> contains every language in
+<parameter>ls_b</parameter>. <parameter>ls_a</parameter> will 'contain' a
+language from <parameter>ls_b</parameter> if <parameter>ls_a</parameter>
+has exactly the language, or either the language or
+<parameter>ls_a</parameter> has no territory.
+@@
+
+@RET@		FcBool
+@FUNC@		FcLangSetEqual
+@TYPE1@		const FcLangSet *		@ARG1@		ls_a
+@TYPE2@		const FcLangSet *		@ARG2@		ls_b
+@PURPOSE@	test for matching langsets
+@DESC@
+Returns FcTrue if and only if <parameter>ls_a</parameter> supports precisely
+the same language and territory combinations as <parameter>ls_b</parameter>.
+@@
+
+@RET@		FcChar32
+@FUNC@		FcLangSetHash
+@TYPE1@		const FcLangSet *		@ARG1@		ls
+@PURPOSE@	return a hash value for a langset
+@DESC@
+This function returns a value which depends solely on the languages
+supported by <parameter>ls</parameter>. Any language which equals
+<parameter>ls</function> will have the same result from
+<function>FcLangSetHash</function>. However, two langsets with the same hash
+value may not be equal.
+@@
+
+@RET@		FcLangResult
+@FUNC@		FcLangSetHasLang
+@TYPE1@		const FcLangSet *		@ARG1@		ls
+@TYPE2@		const FcChar8 *			@ARG2@		lang
+@PURPOSE@	test langset for language support
+@DESC@
+<function>FcLangSetHasLang</function> checks whether
+<parameter>ls</parameter> supports <parameter>lang</parameter>. If 
+<parameter>ls</parameter> has a matching language and territory pair,
+this function returns FcLangEqual. If <parameter>ls</parameter> has
+a matching language but differs in which territory that language is for, this
+function returns FcLangDiffentTerritory. If <parameter>ls</parameter> 
+has no matching language, this function returns FcLangDifferentLang.
+@@
diff --git a/doc/fcmatrix.fncs b/doc/fcmatrix.fncs
index 2d48b1e..0159555 100644
--- a/doc/fcmatrix.fncs
+++ b/doc/fcmatrix.fncs
@@ -21,6 +21,8 @@
  * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  * PERFORMANCE OF THIS SOFTWARE.
  */
+
+@RET@		void
 @FUNC@		FcMatrixInit
 @PURPOSE@	initialize an FcMatrix structure
 @TYPE1@		FcMatrix *
diff --git a/doc/fcpattern.fncs b/doc/fcpattern.fncs
index c04d9b3..74f3675 100644
--- a/doc/fcpattern.fncs
+++ b/doc/fcpattern.fncs
@@ -29,12 +29,32 @@
 Creates a pattern with no properties; used to build patterns from scratch.
 @@
 
+@RET@		FcPattern *	
+@FUNC@		FcPatternDuplicate
+@TYPE1@		FcPattern * 			@ARG1@		 p
+@PURPOSE@	Copy a pattern
+@DESC@
+Copy a pattern, returning a new pattern that matches
+<parameter>p</parameter>. Each pattern may be modified without affecting the
+other.
+@@
+
+@RET@		void
+@FUNC@		FcPatternReference
+@TYPE1@		FcPattern * 			@ARG1@		 p
+@PURPOSE@	Increment pattern reference count
+@DESC@
+Add another reference to <parameter>p</parameter>. Patterns are freed only
+when the reference count reaches zero.
+@@
+
 @RET@		void
 @FUNC@		FcPatternDestroy
 @TYPE1@		FcPattern * 			@ARG1@		 p
 @PURPOSE@	Destroy a pattern
 @DESC@
-Destroys a pattern, in the process destroying all related values.
+Decrement the pattern reference count. If all references are gone, destroys
+the pattern, in the process destroying all related values.
 @@
 
 @RET@		FcBool
@@ -134,6 +154,21 @@ values added to the list have binding <parameter>weak</parameter> instead of <pa
 @TYPE1+++++@ 	FcPattern * 			@ARG1+++++@ 	p
 @TYPE2+++++@	const char *			@ARG2+++++@	object
 @TYPE3+++++@	FcBool%				@ARG3+++++@	b
+
+@PROTOTYPE++++++@
+@RET++++++@	FcBool
+@FUNC++++++@	FcPatternAddFTFace
+@TYPE1++++++@ 	FcPattern * 			@ARG1++++++@ 	p
+@TYPE2++++++@	const char *			@ARG2++++++@	object
+@TYPE3++++++@	const FT_Face 			@ARG3++++++@	f
+
+@PROTOTYPE+++++++@
+@RET+++++++@	FcBool
+@FUNC+++++++@	FcPatternAddLangSet
+@TYPE1+++++++@ 	FcPattern * 			@ARG1+++++++@ 	p
+@TYPE2+++++++@	const char *			@ARG2+++++++@	object
+@TYPE3+++++++@	const FcLangSet *		@ARG3+++++++@	l
+
 @PURPOSE@	Add a typed value to a pattern
 @DESC@
 These are all convenience functions that insert objects of the specified
@@ -204,6 +239,21 @@ within the pattern directly.  Applications must not free this value.
 @TYPE2+++++@ 	const char * 			@ARG2+++++@ 	object 
 @TYPE3+++++@ 	int%  				@ARG3+++++@ 	n 
 @TYPE4+++++@ 	FcBool * 			@ARG4+++++@ 	b 
+
+@PROTOTYPE++++++@
+@RET++++++@	FcBool
+@FUNC++++++@	FcPatternGetFTFace
+@TYPE1++++++@ 	FcPattern * 			@ARG1++++++@ 	p
+@TYPE2++++++@	const char *			@ARG2++++++@	object
+@TYPE3++++++@	const FT_Face *			@ARG3++++++@	f
+
+@PROTOTYPE+++++++@
+@RET+++++++@	FcBool
+@FUNC+++++++@	FcPatternGetLangSet
+@TYPE1+++++++@ 	FcPattern * 			@ARG1+++++++@ 	p
+@TYPE2+++++++@	const char *			@ARG2+++++++@	object
+@TYPE3+++++++@	const FcLangSet **		@ARG3+++++++@	l
+
 @PURPOSE@	Return a typed value from a pattern
 @DESC@
 These are convenience functions that call FcPatternGet and verify that the
diff --git a/doc/fcstring.fncs b/doc/fcstring.fncs
index bac5444..cea8981 100644
--- a/doc/fcstring.fncs
+++ b/doc/fcstring.fncs
@@ -97,6 +97,33 @@ indicates whether <parameter>string</parameter> is a well-formed UTF16
 string.
 @@
 
+@RET@		FcBool
+@FUNC@		FcIsLower
+@TYPE1@		FcChar8				@ARG1@		c
+@PURPOSE@	check for lower case ASCII character
+@DESC@
+This macro checks whether <parameter>c</parameter> is an lower case ASCII
+letter.
+@@
+
+@RET@		FcBool
+@FUNC@		FcIsUpper
+@TYPE1@		FcChar8				@ARG1@		c
+@PURPOSE@	check for upper case ASCII character
+@DESC@
+This macro checks whether <parameter>c</parameter> is a upper case ASCII
+letter.
+@@
+
+@RET@		FcChar8
+@FUNC@		FcToLower
+@TYPE1@		FcChar8				@ARG1@		c
+@PURPOSE@	convert upper case ASCII to lower case
+@DESC@
+This macro converts upper case ASCII <parameter>c</parameter> to the
+equivalent lower case letter.
+@@
+
 @RET@		FcChar8 *
 @FUNC@		FcStrCopy
 @TYPE1@		const FcChar8 *			@ARG1@		s
@@ -127,45 +154,70 @@ Returns NULL if '~' is present in <parameter>s</parameter> and HOME is unset.
 @@
 
 @RET@		int
+@FUNC@		FcStrCmp
+@TYPE1@		const FcChar8 *			@ARG1@		s1
+@TYPE2@		const FcChar8 *			@ARG2@		s2
+@PURPOSE@	compare UTF-8 strings
+@DESC@
+Returns the usual &lt;0, 0, &gt;0 result of comparing
+<parameter>s1</parameter> and <parameter>s2</parameter>. 
+@@
+
+@RET@		int
 @FUNC@		FcStrCmpIgnoreCase
 @TYPE1@		const FcChar8 *			@ARG1@		s1
 @TYPE2@		const FcChar8 *			@ARG2@		s2
-@PURPOSE@	compare UTF-8 strings ignoring ASCII case
+@PURPOSE@	compare UTF-8 strings ignoring 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.
+<parameter>s1</parameter> and <parameter>s2</parameter>. This test is
+case-insensitive for all proper UTF-8 encoded strings.
 @@
 
 @RET@		FcChar8 *
 @FUNC@		FcStrStr
-@TYPE1@		const char *			@ARG1@		s1
-@TYPE2@		const char *			@ARG2@		s2
+@TYPE1@		const FcChar8 *			@ARG1@		s1
+@TYPE2@		const FcChar8 *			@ARG2@		s2
 @PURPOSE@	locate UTF-8 substring
 @DESC@
 Returns the location of <parameter>s2</parameter> in
 <parameter>s1</parameter>.  Returns NULL if <parameter>s2</parameter>
 is not present in <parameter>s1</parameter>. This test will operate properly
-with UTF8 encoded strings, although it does not check for well formed
-strings.
+with UTF8 encoded strings.
 @@
 
 @RET@		FcChar8 *
 @FUNC@		FcStrStrIgnoreCase
-@TYPE1@		const char *			@ARG1@		s1
-@TYPE2@		const char *			@ARG2@		s2
+@TYPE1@		const FcChar8 *			@ARG1@		s1
+@TYPE2@		const FcChar8 *			@ARG2@		s2
 @PURPOSE@	locate UTF-8 substring ignoring ASCII case
 @DESC@
 Returns the location of <parameter>s2</parameter> in 
-<parameter>s1</parameter>, ignoring ASCII case.  Returns NULL if
+<parameter>s1</parameter>, ignoring case.  Returns NULL if
 <parameter>s2</parameter> is not present in <parameter>s1</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.
+This test is case-insensitive for all proper UTF-8 encoded strings.
 @@
 
 @RET@		FcChar8 *
+@FUNC@		FcStrPlus
+@TYPE1@		const FcChar8 *			@ARG1@		s1
+@TYPE2@		const FcChar8 *			@ARG2@		s2
+@PURPOSE@	concatenate two strings
+@DESC@
+This function allocates new storage and places the concatenation of
+<parameter>s1</parameter> and <parameter>s2</parameter> there, returning the
+new string.
+@@
+
+@RET@		void
+@FUNC@		FcStrFree
+@TYPE1@		FcChar8 *			@ARG1@		s
+@PURPOSE@	free a string
+@DESC@
+This is just a wrapper around free(3) which helps track memory usage of
+strings within the fontconfig library.
+
+@RET@		FcChar8 *
 @FUNC@		FcStrDirname
 @TYPE1@		const FcChar8 *			@ARG1@		file
 @PURPOSE@	directory part of filename
diff --git a/doc/fcstrset.fncs b/doc/fcstrset.fncs
index c6dd819..d6b0520 100644
--- a/doc/fcstrset.fncs
+++ b/doc/fcstrset.fncs
@@ -42,6 +42,17 @@ Returns whether <parameter>s</parameter> is a member of
 @@
 
 @RET@		FcBool
+@FUNC@		FcStrSetEqual
+@TYPE1@		FcStrSet *			@ARG1@		set_a
+@TYPE2@		FcStrSet *			@ARG2@		set_b
+@PURPOSE@	check sets for equality
+@DESC@
+Returns whether <parameter>set_a</parameter> contains precisely the same
+strings as <parameter>set_b</parameter>. Ordering of strings within the two
+sets is not considered.
+@@
+
+@RET@		FcBool
 @FUNC@		FcStrSetAdd
 @TYPE1@		FcStrSet *			@ARG1@		set
 @TYPE2@		const FcChar8 *			@ARG2@		s	
diff --git a/doc/fcvalue.fncs b/doc/fcvalue.fncs
index 88ccaf3..14d043b 100644
--- a/doc/fcvalue.fncs
+++ b/doc/fcvalue.fncs
@@ -38,3 +38,24 @@ FcTypeMatrix and FcTypeCharSet reference memory, the other types do not.
 Returns a copy of <parameter>v</parameter> duplicating any object referenced by it so that <parameter>v</parameter>
 may be safely destroyed without harming the new value.
 @@
+
+@RET@		void
+@FUNC@		FcValuePrint
+@TYPE1@		FcValue%		@ARG1@		v
+@PURPOSE@	Print a value to stdout
+@DESC@
+Prints a human-readable representation of <parameter>v</parameter> to
+stdout. The format should not be considered part of the library
+specification as it may change in the future.
+@@
+
+@RET@		FcBool
+@FUNC@		FcValueEqual
+@TYPE1@		FcValue%		@ARG1@		v_a
+@TYPE2@		FcValue%		@ARG2@		v_b
+@PURPOSE@	Test two values for equality
+@DESC@
+Compares two values. Integers and Doubles are compared as numbers; otherwise
+the two values have to be the same type to be considered equal. Strings are
+compared ignoring case.
+@@
diff --git a/doc/fontconfig-devel.sgml b/doc/fontconfig-devel.sgml
index 5bad9a5..d448524 100644
--- a/doc/fontconfig-devel.sgml
+++ b/doc/fontconfig-devel.sgml
@@ -178,7 +178,7 @@ convenience for the applications rendering mechanism.
                                                 spacing
     charset        FC_CHARSET           CharSet Unicode chars encoded by
                                                 the font
-    lang           FC_LANG              String  List of RFC-3066-style
+    lang           FC_LANG              LangSet Set of RFC-3066-style
                                                 languages this font supports
     fontversion    FC_FONTVERSION       Int     Version number of the font
     capability     FC_CAPABILITY        String  List of layout capabilities in
@@ -217,6 +217,26 @@ 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>
   </sect2>
+  <sect2><title>FcLangSet</title>
+    <para>
+An FcLangSet is an abstract type that holds the set of languages supported
+by a font.  Operations to build and compare these sets are provided. These
+are computed for a font based on orthographic information built into the
+fontconfig library. Fontconfig has orthographies for all of the ISO 639-1
+languages except for MS, NA, PA, PS, QU, RN, RW, SD, SG, SN, SU and ZA. If
+you have orthographic information for any of these languages, please submit
+them.
+    </para>
+  </sect2>
+  <sect2><title>FcLangResult</title>
+    <para>
+An FcLangResult is an enumeration used to return the results of comparing
+two language strings or FcLangSet objects. FcLangEqual means the
+objects match language and territory. FcLangDifferentTerritory means
+the objects match in language but differ in territory.
+FcLangDifferentLang means the objects differ in language.
+    </para>
+  </sect2>
   <sect2><title>FcType</title>
     <para>
 Tags the kind of data stored in an FcValue.
@@ -236,6 +256,8 @@ types.  The 'type' tag indicates which member is valid.
                         double d;
                         const FcMatrix *m;
                         const FcCharSet *c;
+			void *f;
+			const FcLangSet *l;
                 } u;
         } FcValue;
     </programlisting>
@@ -251,6 +273,8 @@ types.  The 'type' tag indicates which member is valid.
         FcTypeBool      b               b
         FcTypeMatrix    m               FcMatrix *
         FcTypeCharSet   c               FcCharSet *
+	FcTypeFTFace	f		void * (FT_Face)
+	FcTypeLangSet	l		FcLangSet *
     </programlisting>
     </para>
   </sect2>