diff --git a/doc/fontconfig-devel.sgml b/doc/fontconfig-devel.sgml
new file mode 100644
index 0000000..f5d958f
--- /dev/null
+++ b/doc/fontconfig-devel.sgml
@@ -0,0 +1,1257 @@
+
+
+
+
+ Fontconfig Developers Guide
+ Fontconfig
+ Keith>Packard>
+ krp
+
+NAME
+
+ fontconfig - Font configuration and customization library
+
+
+SYNOPSIS
+
+ #include <fontconfig/fontconfig.h>
+ #include <fontconfig/fcfreetype.h>
+
+
+DESCRIPTION
+
+Fontconfig is a library designed to provide system-wide font configuration,
+customization and application access.
+
+
+FUNCTIONAL OVERVIEW
+
+Fontconfig contains two essential modules, the configuration module which
+builds an internal configuration from XML files and the matching module
+which accepts font patterns and returns the nearest matching font.
+
+ FONT CONFIGURATION
+
+The configuration module consists of the FcConfig datatype, libexpat and
+FcConfigParse which walks over an XML tree and ammends a configuration with
+data found within. From an external perspective, configuration of the
+library consists of generating a valid XML tree and feeding that to
+FcConfigParse. The only other mechanism provided to applications for
+changing the running configuration is to add fonts and directories to the
+list of application-provided font files.
+
+The intent is to make font configurations relatively static, and shared by
+as many applications as possible. It is hoped that this will lead to more
+stable font selection when passing names from one application to another.
+XML was chosen as a configuration file format because it provides a format
+which is easy for external agents to edit while retaining the correct
+structure and syntax.
+
+Font configuration is separate from font matching; applications needing to
+do their own matching can access the available fonts from the library and
+perform private matching. The intent is to permit applications to pick and
+choose appropriate functionality from the library instead of forcing them to
+choose between this library and a private configuration mechanism. The hope
+is that this will ensure that configuration of fonts for all applications
+can be centralized in one place. Centralizing font configuration will
+simplify and regularize font installation and customization.
+
+
+
+ FONT PROPERTIES
+
+While font patterns may contain essentially any properties, there are some
+well known properties with associated types. Fontconfig uses some of these
+properties for font matching and font completion. Others are provided as a
+convenience for the applications rendering mechanism.
+
+
+ Property Definitions
+
+
+
+
+
+
+
+ Property
+ CPP Symbol
+ Type
+ Description
+
+
+
+familyFC_FAMILYStringFont family name
+styleFC_STYLEStringFont style. Overrides weight and slant
+slantFC_SLANTIntItalic, oblique or roman
+weightFC_WEIGHTIntLight, medium, demibold, bold or black
+sizeFC_SIZEDoublePoint size
+aspectFC_ASPECTDoubleStretches glyphs horizontally before hinting
+pixelsizeFC_PIXEL_SIZEDoublePixel size
+spacingFC_SPACINGIntProportional, monospace or charcell
+foundryFC_FOUNDRYStringFont foundry name
+antialiasFC_ANTIALIASBoolWhether glyphs can be antialiased
+hintingFC_HINTINGBoolWhether the rasterizer should use hinting
+verticallayoutFC_VERTICAL_LAYOUTBoolUse vertical layout
+autohintFC_AUTOHINTBoolUse autohinter instead of normal hinter
+globaladvanceFC_GLOBAL_ADVANCEBoolUse font global advance data
+fileFC_FILEStringThe filename holding the font
+indexFC_INDEXIntThe index of the font within the file
+ftfaceFC_FT_FACEFT_FaceUse the specified FreeType face object
+rasterizerFC_RASTERIZERStringWhich rasterizer is in use
+outlineFC_OUTLINEBoolWhether the glyphs are outlines
+scalableFC_SCALABLEBoolWhether glyphs can be scaled
+scaleFC_SCALEDoubleScale factor for point->pixel conversions
+dpiFC_DPIDoubleTarget dots per inch
+rgbaFC_RGBAIntunknown, rgb, bgr, vrgb, vbgr, none - subpixel geometry
+minspaceFC_MINSPACEBoolEliminate leading from line spacing
+charsetFC_CHARSETCharSetUnicode chars encoded by the font
+langFC_LANGStringList of RFC-3066-style languages this font supports
+
+
+
+
+DATATYPES
+
+Fontconfig uses abstract datatypes to hide internal implementation details
+for most data structures. A few structures are exposed where appropriate.
+
+ FcChar8, FcChar16, FcChar32, FcBool
+
+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.
+
+
+ FcMatrix
+
+An FcMatrix holds an affine transformation, usually used to reshape glyphs.
+A small set of matrix operations are provided to manipulate these.
+
+ typedef struct _FcMatrix {
+ double xx, xy, yx, yy;
+ } FcMatrix;
+
+
+
+
+ FcCharSet
+
+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.
+
+
+
+ FcType
+
+Tags the kind of data stored in an FcValue.
+
+
+ FcValue
+
+An FcValue object holds a single value with one of a number of different
+types. The 'type' tag indicates which member is valid.
+
+ typedef struct _FcValue {
+ FcType type;
+ union {
+ const FcChar8 *s;
+ int i;
+ FcBool b;
+ double d;
+ const FcMatrix *m;
+ const FcCharSet *c;
+ } u;
+ } FcValue;
+
+
+ FcValue Members
+
+
+ Type
+ Union member
+ Datatype
+
+
+FcTypeVoid(none)(none)
+FcTypeIntegeriint
+FcTypeDoubleddouble
+FcTypeStringschar *
+FcTypeBoolbb
+FcTypeMatrixmFcMatrix *
+FcTypeCharSetcFcCharSet *
+
+
+
+
+ FcPattern
+
+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
+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.
+
+
+ FcFontSet
+
+
+ typedef struct _FcFontSet {
+ int nfont;
+ int sfont;
+ FcPattern **fonts;
+ } FcFontSet;
+
+An FcFontSet contains a list of FcPatterns. Internally fontconfig uses this
+data structure to hold sets of fonts. Externally, fontconfig returns the
+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.
+
+
+
+ FcStrSet, FcStrList
+
+FcStrSet holds a list of strings that can be appended to and enumerated.
+Its unique characteristic is that the enumeration works even while strings
+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.
+
+
+
+ FcObjectSet
+
+
+ typedef struct _FcObjectSet {
+ int nobject;
+ int sobject;
+ const char **objects;
+ } FcObjectSet;
+
+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.
+
+
+
+ FcObjectType
+
+
+ typedef struct _FcObjectType {
+ const char *object;
+ FcType type;
+ } FcObjectType;
+
+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.
+
+
+
+ FcConstant
+
+
+ typedef struct _FcConstant {
+ const FcChar8 *name;
+ const char *object;
+ int value;
+ } FcConstant;
+
+Provides for symbolic constants for new pattern elements. When 'name' is
+seen in a font name, an 'object' element is created with value 'value'.
+
+
+
+ FcBlanks
+
+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.
+
+
+
+ FcFileCache
+
+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.
+
+
+
+ FcConfig
+
+holds a complete configuration of the library; there is one default
+configuration, other can be constructed from XML data structures. All
+public entry points that need global data can take an optional FcConfig*
+argument; passing 0 uses the default configuration. FcConfig objects hold two
+sets of fonts, the first contains those specified by the configuration, the
+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.
+
+
+
+ FcSetName
+
+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.
+
+
+
+ FcResult
+
+Used as a return type for functions manipulating FcPattern objects.
+
+ FcResult Values
+
+
+ Result Code
+ Meaning
+
+
+FcResultMatchObject exists with the specified ID
+FcResultNoMatchObject doesn't exist at all
+FcResultTypeMismatchObject exists, but the type doesn't match
+FcResultNoIdObject exists, but has fewer values than specified
+
+
+
+
+
+
+ FcAtomic
+
+Used for locking access to config files. Provides a safe way to update
+configuration files.
+
+
+
+FUNCTIONS
+
+Functions are grouped by the main datatype involved
+
+ FcMatrix
+
+FcMatrix structures hold an affine transformation in matrix form.
+
+ FcMatrixInit
+#define FcMatrixInit(m) ((m)->xx = (m)->yy = 1, (m)->xy = (m)->yx = 0)
+
+Initializes a matrix to the identify transformation.
+
+ FcMatrixCopy
+FcMatrix *FcMatrixCopy (const FcMatrix *mat)
+
+Allocates a new FcMatrix and copies 'mat' into it.
+
+ FcMatrixEqual
+FcBool FcMatrixEqual (const FcMatrix *mat1, const FcMatrix *mat2)
+
+Returns FcTrue if 'mat1' and 'mat2' are equal, else FcFalse.
+
+ FcMatrixMultiply
+void FcMatrixMultiply (FcMatrix *result, const FcMatrix *a, const FcMatrix *b)
+
+Multiplies 'a' and 'b' together, placing the result in 'result'. 'result'
+may refer to the sam matrix as either 'a' or 'b'.
+
+ FcMatrixRotate
+void FcMatrixRotate (FcMatrix *m, double c, double s)
+
+If 'c' is cos(angle) and 's' is sin(angle), FcMatrixRotate rotates the
+matrix by 'angle'.
+
+ FcMatrixScale
+void FcMatrixScale (FcMatrix *m, double sx, double sy)
+
+Scales 'm' by 'sx' in the horizontal dimension and 'sy' in the
+vertical dimension.
+
+ FcMatrixShear
+void FcMatrixShear (FcMatrix *m, double sh, double sv)
+
+Shears 'm' by 'sh' in the horizontal direction and 'sv' in the
+vertical direction.
+
+
+ FcCharSet
+
+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.
+
+ FcCharSetCreate
+FcCharSet *FcCharSetCreate (void)
+
+Creates an empty FcCharSet object.
+
+ FcCharSetDestroy
+void FcCharSetDestroy (FcCharSet *fcs)
+
+Frees an FcCharSet object.
+
+ FcCharSetAddChar
+FcBool FcCharSetAddChar (FcCharSet *fcs, FcChar32 ucs4)
+
+Adds a single unicode char to the set, returning FcFalse on
+failure, either as a result of a constant set or from running out of memory.
+
+ FcCharSetCopy
+FcCharSet *FcCharSetCopy (FcCharSet *src)
+
+Makes a copy of 'src'; note that this may not actually do anything more than
+increment the reference count on 'src'.
+
+ FcCharSetEqual
+FcBool FcCharSetEqual (const FcCharSet *a, const FcCharSet *b)
+
+Returns whether 'a' and 'b' contain the same set of unicode chars.
+
+ FcCharSetIntersect
+FcCharSet *FcCharSetIntersect (const FcCharSet *a, const FcCharSet *b)
+
+Returns a set including only those chars found in both 'a' and 'b'.
+
+ FcCharSetUnion
+FcCharSet *FcCharSetUnion (const FcCharSet *a, const FcCharSet *b);
+
+Returns a set including only those chars found in either 'a' or 'b'.
+
+ FcCharSetSubtract
+FcCharSet *FcCharSetSubtract (const FcCharSet *a, const FcCharSet *b)
+
+Returns a set including only those chars found in 'a' but not 'b'.
+
+ FcCharSetHasChar
+FcBool FcCharSetHasChar (const FcCharSet *fcs, FcChar32 ucs4)
+
+Returns whether 'fcs' contains the char 'ucs4'.
+
+ FcCharSetCount
+FcChar32 FcCharSetCount (const FcCharSet *a)
+
+Returns the total number of unicode chars in 'a'.
+
+ FcCharSetIntersectCount
+FcChar32 FcCharSetIntersectCount (const FcCharSet *a, const FcCharSet *b)
+
+Returns the number of chars that are in both 'a' and 'b'.
+
+ FcCharSetSubtractCount
+FcChar32 FcCharSetSubtractCount (const FcCharSet *a, const FcCharSet *b)
+
+Returns the number of chars that are in 'a' but not in 'b'.
+
+ FcCharSetIsSubset
+FcBool FcCharSetIsSubset (const FcCharSet *a, const FcCharSet *b)
+
+Returns whether 'a' is a subset of 'b'.
+
+ FcCharSetFirstPage
+FcChar32 FcCharSetFirstPage (const FcCharSet *a, FcChar32 [FC_CHARSET_MAP_SIZE], FcChar32 *next)
+
+Builds an array of bits marking the first page of Unicode coverage of 'a'.
+Returns the base of the array. 'next' contains the next page in the font.
+
+ FcCharSetNextPage
+FcChar32 FcCharSetNextPage (const FcCharSet *a, FcChar32 [FC_CHARSET_MAP_SIZE], FcChar32 *next)
+
+Builds an array of bits marking the Unicode coverage of 'a' for page '*next'.
+Returns the base of the array. 'next' contains the next page in the font.
+
+
+ FcValue
+
+FcValue is a structure containing a type tag and a union of all possible
+datatypes. The tag is an enum of type
+FcType
+and is intended to provide a measure of run-time
+typechecking, although that depends on careful programming.
+
+ FcValueDestroy
+void FcValueDestroy (FcValue v)
+
+Frees any memory referenced by `v'. Values of type FcTypeString,
+FcTypeMatrix and FcTypeCharSet reference memory, the other types do not.
+
+ FcValueSave
+FcValue FcValueSave (FcValue v)
+
+Returns a copy of `v' duplicating any object referenced by it so that `v'
+may be safely destroyed without harming the new value.
+
+
+ FcPattern
+
+An FcPattern is an opaque type that holds both patterns to match against the
+available fonts, as well as the information about each font.
+
+ FcPatternCreate
+FcPattern *FcPatternCreate (void)
+
+Creates a pattern with no properties; used to build patterns from scratch.
+
+ FcPatternDestroy
+void FcPatternDestroy (FcPattern *p)
+
+Destroys a pattern, in the process destroying all related values.
+
+ FcPatternEqual
+FcBool FcPatternEqual (const FcPattern *pa, const FcPattern *pb);
+
+Returns whether 'pa' and 'pb' are exactly alike.
+
+ FcPatternEqualSubset
+FcBool FcPatternEqualSubset (const FcPattern *pa, const FcPattern *pb, const FcObjectSet *os)
+
+Returns whether 'pa' and 'pb' have exactly the same values for all of the
+objects in 'os'.
+
+ FcPatternHash
+FcChar32 FcPatternHash (const FcPattern *p)
+
+Returns a 32-bit number which is the same for any two patterns which are
+exactly alike.
+
+ FcPatternAdd
+FcBool FcPatternAdd (FcPattern *p, const char *object, FcValue value, FcBool append)
+
+Adds a single value to the list of values associated with the property named
+`object'. If `append' is FcTrue, the value is added at the end of any
+existing list, otherwise it is inserted at the begining. `value' is saved
+(with FcValueSave) when inserted into the pattern so that the library
+retains no reference to any application-supplied data structure.
+
+ FcPatternAddWeak
+FcBool FcPatternAddWeak (FcPattern *p, const char *object, FcValue value, FcBool append)
+
+FcPatternAddWeak is essentially the same as FcPatternAdd except that any
+values added to the list have binding 'weak' instead of 'strong'.
+
+ FcPatternAdd Type
+FcBool FcPatternAddInteger (FcPattern *p, const char *object, int i)
+FcBool FcPatternAddDouble (FcPattern *p, const char *object, double d)
+FcBool FcPatternAddString (FcPattern *p, const char *object, const char *s)
+FcBool FcPatternAddMatrix (FcPattern *p, const char *object, const FcMatrix *s)
+FcBool FcPatternAddCharSet (FcPattern *p, const char *object, const FcCharSet *c)
+FcBool FcPatternAddBool (FcPattern *p, const char *object, FcBool b)
+
+These are all convenience functions that insert objects of the specified
+type into the pattern. Use these in preference to FcPatternAdd as they
+will provide compile-time typechecking. These all append values to
+any existing list of values.
+
+ FcPatternGet
+FcResult FcPatternGet (FcPattern *p, const char *object, int id, FcValue *v)
+
+Returns in `v' the `id'th value associated with the property `object'.
+The value returned is not a copy, but rather refers to the data stored
+within the pattern directly. Applications must not free this value.
+
+ FcPatternGet Type
+FcResult FcPatternGetInteger (FcPattern *p, const char *object, int n, int *i);
+FcResult FcPatternGetDouble (FcPattern *p, const char *object, int n, double *d);
+FcResult FcPatternGetString (FcPattern *p, const char *object, int n, char **const s);
+FcResult FcPatternGetMatrix (FcPattern *p, const char *object, int n, FcMatrix **s);
+FcResult FcPatternGetCharSet (FcPattern *p, const char *object, int n, FcCharSet **c);
+FcResult FcPatternGetBool (FcPattern *p, const char *object, int n, FcBool *b);
+
+These are convenience functions that call FcPatternGet and verify that the
+returned data is of the expected type. They return FcResultTypeMismatch if
+this is not the case. Note that these (like FcPatternGet) do not make a
+copy of any data structure referenced by the return value. Use these
+in preference to FcPatternGet to provide compile-time typechecking.
+
+ FcPatternBuild, FcPatternVaBuild
+FcPattern *FcPatternBuild (FcPattern *orig, ...);
+FcPattern *FcPatternVaBuild (FcPattern *orig, va_list va)
+
+Builds a pattern using a list of objects, types and values. Each
+value to be entered in the pattern is specified with three arguments:
+
+
+
+Object name, a string describing the property to be added.
+
+Object type, one of the FcType enumerated values
+
+Value, not an FcValue, but the raw type as passed to any of the
+FcPatternAdd<type> functions. Must match the type of the second
+argument.
+
+
+The argument list is terminated by a null object name, no object type nor
+value need be passed for this. The values are added to `pattern', if
+`pattern' is null, a new pattern is created. In either case, the pattern is
+returned. Example
+
+
+pattern = FcPatternBuild (0, FC_FAMILY, FtTypeString, "Times", (char *) 0);
+
+
+FcPatternVaBuild is used when the arguments are already in the form of a
+varargs value.
+
+ FcPatternDel
+FcBool FcPatternDel (FcPattern *p, const char *object)
+
+Deletes all values associated with the property `object', returning
+whether the property existed or not.
+
+ FcPatternPrint
+void FcPatternPrint (const FcPattern *p)
+
+Prints an easily readable version of the pattern to stdout. There is
+no provision for reparsing data in this format, it's just for diagnostics
+and debugging.
+
+ FcDefaultSubstitute
+void FcDefaultSubstitute (FcPattern *pattern)
+
+Supplies default values for underspecified font patterns:
+
+
+Patterns without a specified style or weight are set to Medium
+
+
+Patterns without a specified style or slant are set to Roman
+
+
+Patterns without a specified pixel size are given one computed from any
+specified point size (default 12), dpi (default 75) and scale (default 1).
+
+
+
+ FcNameParse
+FcPattern *FcNameParse (const char *name)
+
+Converts 'name' from the standard text format described above into a pattern.
+
+ FcNameUnparse
+FcChar8 *FcNameUnparse (FcPattern *pat)
+
+Converts the given pattern into the standard text format described above.
+The return value is not static, but instead refers to newly allocated memory
+which should be freed by the caller.
+
+
+ FcFontSet
+
+An FcFontSet simply holds a list of patterns; these are used to return the
+results of listing available fonts.
+
+ FcFontSetCreate
+FcFontSet *FcFontSetCreate (void)
+
+Creates an empty font set.
+
+ FcFontSetDestroy
+void FcFontSetDestroy (FcFontSet *s);
+
+Destroys a font set. Note that this destroys any referenced patterns as
+well.
+
+ FcFontSetAdd
+FcBool FcFontSetAdd (FcFontSet *s, FcPattern *font)
+
+Adds a pattern to a font set. Note that the pattern is not copied before
+being inserted into the set.
+
+
+ FcObjectSet
+
+An FcObjectSet holds a list of pattern property names; it is used to
+indiciate which properties are to be returned in the patterns from
+FcFontList.
+
+ FcObjectSetCreate
+FcObjectSet *FcObjectSetCreate (void)
+
+Creates an empty set.
+
+ FcObjectSetAdd
+FcBool FcObjectSetAdd (FcObjectSet *os, const char *object)
+
+Adds a proprety name to the set.
+
+ FcObjectSetDestroy
+void FcObjectSetDestroy (FcObjectSet *os)
+
+Destroys an object set.
+
+ FcObjectSetBuild, FcObjectSetVaBuild
+FcObjectSet *FcObjectSetBuild (const char *first, ...)
+FcObjectSet *FcObjectSetVaBuild (const char *first, va_list va)
+
+These build an object set from a null-terminated list of property names.
+
+
+ FcObjectType
+
+Provides for applcation-specified font name object types so that new
+pattern elements can be generated from font names.
+
+ FcNameRegisterObjectTypes
+FcBool FcNameRegisterObjectTypes (const FcObjectType *types, int ntype)
+
+Register 'ntype' new object types.
+
+ FcNameUnregisterObjectTypes
+FcBool FcNameUnregisterObjectTypes (const FcObjectType *types, int ntype)
+
+Unregister 'ntype' object types.
+
+ FcNameGetObjectType
+const FcObjectType *FcNameGetObjectType (const char *object)
+
+Return the object type for the pattern element named 'object'.
+
+
+ FcConstant
+
+Provides for application-specified symbolic constants for font names.
+
+ FcNameRegisterConstants
+FcBool FcNameRegisterConstants (const FcConstant *consts, int nconsts)
+
+Register 'nconsts' new symbolic constants.
+
+ FcNameUnregisterConstants
+FcBool FcNameUnregisterConstants (const FcConstant *consts, int nconsts)
+
+Unregister 'nconsts' symbolic constants.
+
+ FcNameGetConstant
+const FcConstant *FcNameGetConstant (FcChar8 *string)
+
+Return the FcConstant structure related to symbolic constant 'string'.
+
+ FcNameConstant
+FcBool FcNameConstant (FcChar8 *string, int *result);
+
+Returns whether a symbolic constant with name 'string' is registered,
+placing the value of the constant in 'result' if present.
+
+
+ FcBlanks
+
+An FcBlanks object holds a list of Unicode chars which are expected to
+be blank when drawn. When scanning new fonts, any glyphs which are
+empty and not in this list will be assumed to be broken and not placed in
+the FcCharSet associated with the font. This provides a significantly more
+accurate CharSet for applications.
+
+ FcBlanksCreate
+FcBlanks *FcBlanksCreate (void)
+
+Creates an empty FcBlanks object.
+
+ FcBlanksDestroy
+void FcBlanksDestroy (FcBlanks *b)
+
+Destroys an FcBlanks object, freeing any associated memory.
+
+ FcBlanksAdd
+FcBool FcBlanksAdd (FcBlanks *b, FcChar32 ucs4)
+
+Adds a single character to an FcBlanks object, returning FcFalse
+if this process ran out of memory.
+
+ FcBlanksIsMember
+FcBool FcBlanksIsMember (FcBlanks *b, FcChar32 ucs4)
+
+Returns whether the specified FcBlanks object contains the indicated Unicode
+value.
+
+
+ FcConfig
+
+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.
+
+ FcConfigCreate
+FcConfig *FcConfigCreate (void)
+
+Creates an empty configuration.
+
+ FcConfigDestroy
+void FcConfigDestroy (FcConfig *config)
+
+Destroys a configuration and any data associated with it. Note that calling
+this function with the return from FcConfigGetCurrent will place the library
+in an indeterminate state.
+
+ FcConfigSetCurrent
+FcBool FcConfigSetCurrent (FcConfig *config)
+
+Sets the current default configuration to 'config'. Implicitly calls
+FcConfigBuildFonts if necessary, returning FcFalse if that call fails.
+
+ FcConfigGetCurrent
+FcConfig *FcConfigGetCurrent (void)
+
+Returns the current default configuration.
+
+ FcConfigUptoDate
+FcBool FcConfigUptoDate (FcConfig *config)
+
+Checks all of the files related to 'config' and returns whether the
+in-memory version is in sync with the disk version.
+
+ FcConfigBuildFonts
+FcBool FcConfigBuildFonts (FcConfig *config)
+
+Builds the set of available fonts for the given configuration. Note that
+any changes to the configuration after this call have indeterminate effects.
+Returns FcFalse if this operation runs out of memory.
+
+ FcConfigGetConfigDirs
+FcStrList *FcConfigGetConfigDirs (FcConfig *config)
+
+Returns the list of font directories specified in the configuration files
+for 'config'. Does not include any subdirectories.
+
+ FcConfigGetFontDirs
+FcStrList *FcConfigGetFontDirs (FcConfig *config)
+
+Returns the list of font directories in 'config'. This includes the
+configured font directories along with any directories below those in the
+filesystem.
+
+ FcConfigGetConfigFiles
+FcStrList *FcConfigGetConfigFiles (FcConfig *config)
+
+Returns the list of known configuration files used to generate 'config'.
+Note that this will not include any configuration done with FcConfigParse.
+
+ FcConfigGetCache
+char *FcConfigGetCache (FcConfig *config)
+
+Returns the name of the file used to store per-user font information.
+
+ FcConfigGetFonts
+FcFontSet *FcConfigGetFonts (FcConfig *config, FcSetName set)
+
+Returns one of the two sets of fonts from the configuration as specified
+by 'set'.
+
+ FcConfigGetBlanks
+FcBlanks *FcConfigGetBlanks (FcConfig *config)
+
+Returns the FcBlanks object associated with the given configuration, if no
+blanks were present in the configuration, this function will return 0.
+
+ FcConfigGetRescanInverval
+int FcConfigGetRescanInverval (FcConfig *config)
+
+Returns the interval between automatic checks of the configuration (in
+seconds) specified in 'config'. The configuration is checked during
+a call to FcFontList when this interval has passed since the last check.
+
+ FcConfigSetRescanInverval
+FcBool FcConfigSetRescanInverval (FcConfig *config, int rescanInterval)
+
+Sets the rescan interval; returns FcFalse if an error occurred.
+
+ FcConfigAppFontAddFile
+FcBool FcConfigAppFontAddFile (FcConfig *config, const char *file)
+
+Adds an application-specific font to the configuration.
+
+ FcConfigAppFontAddDir
+FcBool FcConfigAppFontAddDir (FcConfig *config, const char *dir)
+
+Scans the specified directory for fonts, adding each one found to the
+application-specific set of fonts.
+
+ FcConfigAppFontClear
+void FcConfigAppFontClear (FcConfig *config)
+
+Clears the set of application-specific fonts.
+
+ FcConfigSubstituteWithPat
+FcBool FcConfigSubstituteWithPat (FcConfig *config, FcPattern *p, FcPattern *p_pat FcMatchKind kind)
+
+Performs the sequence of pattern modification operations, if 'kind' is
+FcMatchPattern, then those tagged as pattern operations are applied, else
+if 'kind' is FcMatchFont, those tagged as font operations are applied and
+p_pat is used for <test> elements with target=pattern.
+
+ FcConfigSubstitute
+FcBool FcConfigSubstitute (FcConfig *config, FcPattern *p, FcMatchKind kind)
+
+Calls FcConfigSubstituteWithPat setting p_pat to NULL.
+
+ FcFontMatch
+FcPattern *FcFontMatch (FcConfig *config, FcPattern *p, FcResult *result)
+
+Returns the font in 'config' most close matching 'p'. This function
+should be called only after FcConfigSubstitute and FcDefaultSubstitute have
+been called for 'p'; otherwise the results will not be correct.
+
+ FcFontSort
+FcFontSet *FcFontSort (FcConfig *config, FcPattern *p, FcBool trim, FcCharSet **csp, FcResult *result)
+
+Returns the list of fonts sorted by closeness to 'p'. If 'trim' 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 'csp', if 'csp' is not NULL. This function
+should be called only after FcConfigSubstitute and FcDefaultSubstitute have
+been called for 'p'; otherwise the results will not be correct.
+
+The returned FcFontSet references FcPattern structures which may be shared
+by the return value from multiple FcFontSort calls, applications must not
+modify these patterns. Instead, they should be passed, along with 'p' to
+FcFontRenderPrepare which combines them into a complete pattern.
+
+The FcFontSet returned by FcFontSort is destroyed by caling FcFontSetDestroy.
+
+ FcFontRenderPrepare
+FcPattern *FcFontRenderPrepare (FcConfig *config, FcPattern *pat, FcPattern *font)
+
+Creates a new pattern consisting of elements of 'font' not appearing
+in 'pat', elements of 'pat' not appearing in 'font' and the best matching
+value from 'pat' for elements appearing in both. The result is passed to
+FcConfigSubstitute with 'kind' FcMatchFont and then returned.
+
+ FcFontList
+FcFontSet *FcFontList (FcConfig *config, FcPattern *p, FcObjectSet *os)
+
+Selects fonts matching 'p', creates patterns from those fonts containing
+only the objects in 'os' and returns the set of unique such patterns.
+
+ FcConfigFilename
+char *FcConfigFilename (const char *name)
+
+Given the specified external entity name, return the associated filename.
+This provides applications a way to convert various configuration file
+references into filename form.
+
+A null or empty 'name' indicates that the default configuration file should
+be used; which file this references can be overridden with the
+FC_CONFIG_FILE environment variable. Next, if the name starts with '~', it
+refers to a file in the current users home directory. Otherwise if the name
+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.
+
+
+ Initialization
+
+These functions provide some control over how the library is initialized.
+
+ FcInitLoadConfig
+FcConfig *FcInitLoadConfig (void)
+
+Loads the default configuration file and returns the resulting configuration.
+Does not load any font information.
+
+ FcInitLoadConfigAndFonts
+FcConfig *FcInitLoadConfigAndFonts (void)
+
+Loads the default configuration file and builds information about the
+available fonts. Returns the resulting configuration.
+
+ FcInit
+FcBool FcInit (void)
+
+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.
+
+ FcGetVersion
+int FcGetVersion (void)
+
+Returns the version number of the library.
+
+ FcInitReinitialize
+FcBool FcInitReinitialize (void)
+
+Forces the default configuration file to be reloaded and resets the default
+configuration.
+
+ FcInitBringUptoDate
+FcBool FcInitBringUptoDate (void)
+
+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.
+
+
+ FcAtomic
+
+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.
+
+ FcAtomicCreate
+FcAtomic * FcAtomicCreate (const FcChar8 *file)
+
+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.
+
+ FcAtomicLock
+FcBool FcAtomicLock (FcAtomic *atomic)
+
+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.
+
+ FcAtomicNewFile
+FcChar8 *FcAtomicNewFile (FcAtomic *atomic)
+
+Returns the filename for writing a new version of the file referenced
+by 'atomic'.
+
+ FcAtomicOrigFile
+FcChar8 *FcAtomicOrigFile (FcAtomic *atomic)
+
+Returns the file refernced by 'atomic'.
+
+ FcAtomicReplaceOrig
+FcBool FcAtomicReplaceOrig (FcAtomic *atomic)
+
+Replaces the original file referenced by 'atomic' with the new file.
+
+ FcAtomicDeleteNew
+void FcAtomicDeleteNew (FcAtomic *atomic)
+
+Deletes the new file.
+
+ FcAtomicUnlock
+void FcAtomicUnlock (FcAtomic *atomic)
+
+Unlocks the file.
+
+ FcAtomicDestroy
+void FcAtomicDestroy (FcAtomic *atomic)
+
+Destroys 'atomic'.
+
+
+ FreeType specific functions
+
+
+#include <fontconfig/fcfreetype.h>
+
+While the fontconfig library doesn't insist that FreeType be used as the
+rasterization mechanism for fonts, it does provide some convenience
+functions.
+
+ FcFreeTypeCharIndex
+FT_UInt FcFreeTypeCharIndex (FT_Face face, FcChar32 ucs4)
+
+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.
+
+ FcFreeTypeCharSet
+FcCharSet *FcFreeTypeCharSet (FT_Face face, FcBlanks *blanks) 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.
+
+ FcFreeTypeQuery
+FcPattern *FcFreeTypeQuery (const char *file, int id, FcBlanks *blanks, int *count)
+
+Constructs a pattern representing the 'id'th font in 'file'. The number
+of fonts in 'file' is returned in 'count'.
+
+
+ XML specific functions
+ FcConfigParseAndLoad
+FcBool FcConfigParseAndLoad (FcConfig *config, const FcChar8 *file, FcBool complain)
+
+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.
+
+
+ File and Directory routines
+ FcFileScan
+FcBool FcFileScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *file, FcBool force)
+
+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'.
+
+ FcDirScan
+FcBool FcDirScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache, FcBlanks *blanks, const char *dir, FcBool force)
+
+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'.
+
+ FcDirSave
+FcBool FcDirSave (FcFontSet *set, FcStrSet *dirs, const char *dir)
+
+Creates the per-directory cache file for 'dir' and populates it with the
+fonts in 'set' and subdirectories in 'dirs'.
+
+ FcDirCacheValid
+FcBool FcDirCacheValid (const FcChar8 *cache_file)
+
+Returns FcTrue if 'cache_file' is no older than the directory containing it,
+else FcFalse.
+
+
+ FcStrSet and FcStrList
+
+A data structure for enumerating strings, used to list directories while
+scanning the configuration as directories are added while scanning.
+
+ FcStrSetCreate
+FcStrSet *FcStrSetCreate (void)
+
+Create an empty set.
+
+ FcStrSetMember
+FcBool FcStrSetMember (FcStrSet *set, const FcChar8 *s)
+
+Returns whether 's' is a member of 'set'.
+
+ FcStrSetAdd
+FcBool FcStrSetAdd (FcStrSet *set, const FcChar8 *s)
+
+Adds a copy of 's' to 'set'.
+
+ FcStrSetAddFilename
+FcBool FcStrSetAddFilename (FcStrSet *set, const FcChar8 *s)
+
+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.
+
+ FcStrSetDel
+FcBool FcStrSetDel (FcStrSet *set, const FcChar8 *s)
+
+Removes 's' from 'set', returning FcTrue if 's' was a member else FcFalse.
+
+ FcStrSetDestroy
+void FcStrSetDestroy (FcStrSet *set)
+
+Destroys 'set'.
+
+ FcStrListCreate
+FcStrList *FcStrListCreate (FcStrSet *set)
+
+Creates an enumerator to list the strings in 'set'.
+
+ FcStrListNext
+FcChar8 *FcStrListNext (FcStrList *list)
+
+Returns the next string in 'set'.
+
+ FcStrListDone
+void FcStrListDone (FcStrList *list)
+
+Destroys the enumerator 'list'.
+
+
+ String utilities
+ FcUtf8ToUcs4
+
+int FcUtf8ToUcs4 (FcChar8 *src, FcChar32 *dst, int len)
+
+
+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.
+
+
+ FcUcs4ToUtf8
+int FcUcs4ToUtf8 (FcChar32 src, FcChar8 dst[FC_UTF8_MAX_LEN])
+
+Converts the Unicode char from 'src' into 'dst' and returns the
+number of bytes needed to encode the char.
+
+ FcUtf8Len
+FcBool FcUtf8Len (FcChar8 *src, int len, int *nchar, int *wchar)
+
+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.
+
+ FcUtf16ToUcs4
+int FcUtf16ToUcs4 (FcChar8 *src, FcEndian endian, FcChar32 *dst, int len)
+
+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'.
+
+ FcUtf16Len
+FcBool FcUtf16Len (FcChar8 *src, FcEndian endian, int len, int *nchar, int *wchar)
+
+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.
+
+ FcStrCopy
+FcChar8 *FcStrCopy (const FcChar8 *s)
+
+Allocates memory, copies 's' and returns the resulting buffer. Yes, this
+is 'strdup', but that function isn't available on every platform.
+
+ FcStrCopyFilename
+FcChar8 *FcStrCopyFilename (const FcChar8 *s)
+
+Just like FcStrCopy except that it converts any leading '~' characters
+in 's' to the value of the HOME environment variable.
+
+ FcStrCmpIgnoreCase
+int FcStrCmpIgnoreCase (const char *s1, const char *s2)
+
+Returns the usual <0, 0, >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.
+
+ FcStrDirname
+FcChar8 *FcStrDirname (const FcChar8 *file)
+
+Returns the directory containing 'file'.
+
+ FcStrBasename
+FcChar8 *FcStrBasename (const FcChar8 *file)
+
+Returns the filename of 'file' stripped of any leading directory names.
+
+
+
+
diff --git a/doc/fontconfig-user.sgml b/doc/fontconfig-user.sgml
new file mode 100644
index 0000000..f243f6d
--- /dev/null
+++ b/doc/fontconfig-user.sgml
@@ -0,0 +1,559 @@
+
+
+
+
+ Fontconfig Users Guide
+ Fontconfig
+ Keith>Packard>
+ krp
+
+NAME
+
+ fontconfig - Font configuration and customization library
+
+
+DESCRIPTION
+
+Fontconfig is a library designed to provide system-wide font configuration,
+customization and application access.
+
+
+FUNCTIONAL OVERVIEW
+
+Fontconfig contains two essential modules, the configuration module which
+builds an internal configuration from XML files and the matching module
+which accepts font patterns and returns the nearest matching font.
+
+ FONT CONFIGURATION
+
+The configuration module consists of the FcConfig datatype, libexpat and
+FcConfigParse which walks over an XML tree and ammends a configuration with
+data found within. From an external perspective, configuration of the
+library consists of generating a valid XML tree and feeding that to
+FcConfigParse. The only other mechanism provided to applications for
+changing the running configuration is to add fonts and directories to the
+list of application-provided font files.
+
+The intent is to make font configurations relatively static, and shared by
+as many applications as possible. It is hoped that this will lead to more
+stable font selection when passing names from one application to another.
+XML was chosen as a configuration file format because it provides a format
+which is easy for external agents to edit while retaining the correct
+structure and syntax.
+
+Font configuration is separate from font matching; applications needing to
+do their own matching can access the available fonts from the library and
+perform private matching. The intent is to permit applications to pick and
+choose appropriate functionality from the library instead of forcing them to
+choose between this library and a private configuration mechanism. The hope
+is that this will ensure that configuration of fonts for all applications
+can be centralized in one place. Centralizing font configuration will
+simplify and regularize font installation and customization.
+
+
+
+ FONT PROPERTIES
+
+While font patterns may contain essentially any properties, there are some
+well known properties with associated types. Fontconfig uses some of these
+properties for font matching and font completion. Others are provided as a
+convenience for the applications rendering mechanism.
+
+
+ Property Definitions
+
+
+
+
+
+
+ Property
+ Type
+ Description
+
+
+
+familyStringFont family name
+styleStringFont style. Overrides weight and slant
+slantIntItalic, oblique or roman
+weightIntLight, medium, demibold, bold or black
+sizeDoublePoint size
+aspectDoubleStretches glyphs horizontally before hinting
+pixelsizeDoublePixel size
+spacingIntProportional, monospace or charcell
+foundryStringFont foundry name
+antialiasBoolWhether glyphs can be antialiased
+hintingBoolWhether the rasterizer should use hinting
+verticallayoutBoolUse vertical layout
+autohintBoolUse autohinter instead of normal hinter
+globaladvanceBoolUse font global advance data
+fileStringThe filename holding the font
+indexIntThe index of the font within the file
+ftfaceFT_FaceUse the specified FreeType face object
+rasterizerStringWhich rasterizer is in use
+outlineBoolWhether the glyphs are outlines
+scalableBoolWhether glyphs can be scaled
+scaleDoubleScale factor for point->pixel conversions
+dpiDoubleTarget dots per inch
+rgbaIntunknown, rgb, bgr, vrgb, vbgr, none - subpixel geometry
+minspaceBoolEliminate leading from line spacing
+charsetCharSetUnicode chars encoded by the font
+langStringList of RFC-3066-style languages this font supports
+
+
+
+
+
+ FONT MATCHING
+
+Fontconfig performs matching by measuring the distance from a provided
+pattern to all of the available fonts in the system. The closest matching
+font is selected. This ensures that a font will always be returned, but
+doesn't ensure that it is anything like the requested pattern.
+
+Font matching starts with an application constructed pattern. The desired
+attributes of the resulting font are collected together in a pattern. Each
+property of the pattern can contain one or more values; these are listed in
+priority order; matches earlier in the list are considered "closer" than
+matches later in the list.
+
+The initial pattern is modified by applying the list of editing instructions
+specific to patterns found in the configuration; each consists of a match
+predicate and a set of editing operations. They are executed in the order
+they appeared in the configuration. Each match causes the associated
+sequence of editing operations to be applied.
+
+After the pattern has been edited, a sequence of default substitutions are
+performed to canonicalize the set of available properties; this avoids the
+need for the lower layers to constantly provide default values for various
+font properties during rendering.
+
+The canonical font pattern is finally matched against all available fonts.
+The distance from the pattern to the font is measured for each of several
+properties: foundry, charset, family, lang, spacing, pixelsize, style,
+slant, weight, antialias, rasterizer and outline. This list is in priority
+order -- results of comparing earlier elements of this list weigh more
+heavily than later elements.
+
+There is one special case to this rule; family names are split into two
+bindings; strong and weak. Strong family names are given greater precedence
+in the match than lang elements while weak family names are given lower
+precedence than lang elements. This permits the document language to drive
+font selection when any document specified font is unavailable.
+
+The pattern representing that font is augmented to include any properties
+found in the pattern but not found in the font itself; this permits the
+application to pass rendering instructions or any other data through the
+matching system. Finally, the list of editing instructions specific to
+fonts found in the configuration are applied to the pattern. This modified
+pattern is returned to the application.
+
+The return value contains sufficient information to locate and rasterize the
+font, including the file name, pixel size and other rendering data. As
+none of the information involved pertains to the FreeType library,
+applications are free to use any rasterization engine or even to take
+the identified font file and access it directly.
+
+The match/edit sequences in the configuration are performed in two passes
+because there are essentially two different operations necessary -- the
+first is to modify how fonts are selected; aliasing families and adding
+suitable defaults. The second is to modify how the selected fonts are
+rasterized. Those must apply to the selected font, not the original pattern
+as false matches will often occur.
+
+
+ FONT NAMES
+
+Fontconfig provides a textual representation for patterns that the library
+can both accept and generate. The representation is in three parts, first a
+list of family names, second a list of point sizes and finally a list of
+additional properties:
+
+
+ <families>-<point sizes>:<name1>=<values1>:<name2>=<values2>...
+
+
+Values in a list are separated with commas. The name needn't include either
+families or point sizes; they can be elided. In addition, there are
+symbolic constants that simultaneously indicate both a name and a value.
+Here are some examples:
+
+
+ Sample Font Names
+
+
+ Name
+ Meaning
+
+
+Times-1212 point Times Roman
+Times-12:bold12 point Times Bold
+Courier:italicCourier Italic in the default size
+Monospace:matrix=1 .1 0 1The users preferred monospace font
+with artificial obliquing
+
+
+
+
+
+LANG TAGS
+
+Each font in the database contains a list of languages it supports. This is
+computed by comparing the Unicode coverage of the font with the orthography
+of each language. Languages are tagged using an RFC-3066 compatible naming
+and occur in two parts -- the ISO639 language tag followed a hyphen and then
+by the ISO 3166 country code. The hyphen and country code may be elided.
+
+Fontconfig has orthographies for several languages built into the library.
+No provision has been made for adding new ones aside from rebuilding the
+library. It currently supports 122 of the 139 languages named in ISO 639-1,
+141 of the languages with two-letter codes from ISO 639-2 and another 30
+languages with only three-letter codes.
+
+
+CONFIGURATION FILE FORMAT
+
+Configuration files for fontconfig are stored in XML format; this
+format makes external configuration tools easier to write and ensures that
+they will generate syntactically correct configuration files. As XML
+files are plain text, they can also be manipulated by the expert user using
+a text editor.
+
+The fontconfig document type definition resides in the external entity
+"fonts.dtd"; this is normally stored in the default font configuration
+directory (/etc/fonts). Each configuration file should contain the
+following structure:
+
+ <?xml version="1.0"?>
+ <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
+ <fontconfig>
+ ...
+ </fontconfig>
+
+
+ <fontconfig>
+This is the top level element for a font configuration and can contain
+<dir>, <cache>, <include>, <match> and <alias> elements in any order.
+
+ <dir>
+This element contains a directory name which will be scanned for font files
+to include in the set of available fonts.
+
+ <cache>
+This element contains a file name for the per-user cache of font
+information. If it starts with '~', it refers to a file in the users
+home directory. This file is used to hold information about fonts that
+isn't present in the per-directory cache files. It is automatically
+maintained by the fontconfig library. The default for this file
+is ``~/.fonts.cache-<version>'', where <version> is the font configuration
+file version number (currently 1).
+
+ <include ignore_missing="no">
+This element contains the name of an additional configuration file. When
+the XML datatype is traversed by FcConfigParse, the contents of the file
+will also be incorporated into the configuration by passing the filename to
+FcConfigLoadAndParse. If 'ignore_missing' is set to "yes" instead of the
+default "no", a missing file will elicit no warning message from the library.
+
+ <config>
+This element provides a place to consolodate additional configuration
+information. <config> can contain <blank> and <rescan> elements in any
+order.
+
+ <blank>
+Fonts often include "broken" glyphs which appear in the encoding but are
+drawn as blanks on the screen. Within the <blank> element, place each
+Unicode characters which is supposed to be blank in an <int> element.
+Characters outside of this set which are drawn as blank will be elided from
+the set of characters supported by the font.
+
+ <rescan>
+The <rescan> element holds an <int> element which indicates the default
+interval between automatic checks for font configuration changes.
+Fontconfig will validate all of the configuration files and directories and
+automatically rebuild the internal datastructures when this interval passes.
+
+ <match target="pattern">
+This element holds first a (possibly empty) list of <test> elements and then
+a (possibly empty) list of <edit> elements. Patterns which match all of the
+tests are subjected to all the edits. If 'target' is set to "font" instead
+of the default "pattern", then this element applies to the font name
+resulting from a match rather than a font pattern to be matched.
+
+ <test qual="any" name="property" compare="eq">
+This element contains a single value which is compared with the pattern
+property "property" (substitute any of the property names seen
+above). 'compare' can be one of "eq", "not_eq", "less", "less_eq", "more", or
+"more_eq". 'qual' may either be the default, "any", in which case the match
+succeeds if any value associated with the property matches the test value, or
+"all", in which case all of the values associated with the property must
+match the test value.
+
+ <edit name="property" mode="assign" binding="weak">
+This element contains a list of expression elements (any of the value or
+operator elements). The expression elements are evaluated at run-time and
+modify the property "property". The modification depends on whether
+"property" was matched by one of the associated <test> elements, if so, the
+modification may affect the first matched value. Any values inserted into
+the property are given the indicated binding. 'mode' is one of:
+
+ Edit Element Modes
+
+
+
+ Mode
+ Operation With Match
+ Operation Without Match
+
+
+
+"assign"Replace matching valueReplace all values
+"assign_replace"Replace all valuesReplace all values
+"prepend"Insert before matching valueInsert at head of list
+"prepend_first"Insert at head of listInsert at head of list
+"append"Append after matching valueAppend at end of list
+"append_last"Append at end of listAppend at end of list
+
+
+
+
+ <int>, <double>, <string>, <bool>
+These elements hold a single value of the indicated type. <bool> elements
+hold either true or false.
+
+ <matrix>
+This element holds the four <double> elements of an affine
+transformation.
+
+ <name>
+Holds a property name. Evaluates to the first value from the property of
+the font, not the pattern.
+
+ <const>
+Holds the name of a constant; these are always integers and serve as
+symbolic names for common font values:
+
+ Symbolic Constants
+
+
+
+ Constant
+ Property
+ CPP Symbol
+
+
+
+lightweight
+mediumweight
+demiboldweight
+boldweight
+blackweight
+romanslant
+italicslant
+obliqueslant
+proportionalspacing
+monospacing
+charcellspacing
+unknownrgba
+rgbrgba
+bgrrgba
+vrgbrgba
+vbgrrgba
+nonergba
+
+
+
+ <or>,
+ <and>,
+ <plus>,
+ <minus>,
+ <times>,
+ <divide>
+These elements perform the specified operation on a list of expression
+elements. <or> and <and> are boolean, not bitwise.
+ <eq>,
+ <not_eq>,
+ <less>,
+ <less_eq>,
+ <more>,
+ <more_eq>
+These elements compare two values, producing a boolean result.
+
+ <not>
+Inverts the boolean sense of its one expression element
+
+ <if>
+This element takes three expression elements; if the value of the first is
+true, it produces the value of the second, otherwise it produces the value
+of the third.
+
+ <alias>
+Alias elements provide a shorthand notation for the set of common match
+operations needed to substitute one font family for another. They contain a
+<family> element followed by optional <prefer>, <accept> and <default>
+elements. Fonts matching the <family> element are edited to prepend the
+list of <prefer>ed families before the matching <family>, append the
+<accept>able familys after the matching <family> and append the <default>
+families to the end of the family list.
+
+ <family>
+Holds a single font family name
+
+ <prefer>, <accept>, <default>
+These hold a list of <family> elements to be used by the <alias> element.
+</article>
+
+
+EXAMPLE CONFIGURATION FILE
+ System configuration file
+
+This is an example of a system-wide configuration file
+
+
+<?xml version="1.0"?>
+<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
+<!-- /etc/fonts/fonts.conf file to configure system font access -->
+<fontconfig>
+<!--
+ Find fonts in these directories
+-->
+<dir>/usr/X11R6/lib/X11/fonts/truetype</dir>
+<dir>/usr/X11R6/lib/X11/fonts/Type1</dir>
+
+<!--
+ Accept deprecated 'mono' alias, replacing it with 'monospace'
+-->
+<match target="pattern">
+ <test qual="any" name="family"><string>mono</string></test>
+ <edit name="family" mode="assign"><string>monospace</string></edit>
+</match>
+
+<!--
+ Names not including any well known alias are given 'sans'
+-->
+<match target="pattern">
+ <test qual="all" name="family" mode="not_eq">sans</test>
+ <test qual="all" name="family" mode="not_eq">serif</test>
+ <test qual="all" name="family" mode="not_eq">monospace</test>
+ <edit name="family" mode="append_last"><string>sans</string></edit>
+</match>
+
+<!--
+ Load per-user customization file, but don't complain
+ if it doesn't exist
+-->
+<include ignore_missing="yes">~/.fonts.conf</include>
+
+<!--
+ Alias well known font names to available TrueType fonts.
+ These substitute TrueType faces for similar Type1
+ faces to improve screen appearance.
+-->
+<alias>
+ <family>Times</family>
+ <prefer><family>Times New Roman</family></prefer>
+ <default><family>serif</family></default>
+</alias>
+<alias>
+ <family>Helvetica</family>
+ <prefer><family>Verdana</family></prefer>
+ <default><family>sans</family></default>
+</alias>
+<alias>
+ <family>Courier</family>
+ <prefer><family>Courier New</family></prefer>
+ <default><family>monospace</family></default>
+</alias>
+
+<!--
+ Provide required aliases for standard names
+ Do these after the users configuration file so that
+ any aliases there are used preferentially
+-->
+<alias>
+ <family>serif</family>
+ <prefer><family>Times New Roman</family></prefer>
+</alias>
+<alias>
+ <family>sans</family>
+ <prefer><family>Verdana</family></prefer>
+</alias>
+<alias>
+ <family>monospace</family>
+ <prefer><family>Andale Mono</family></prefer>
+</alias>
+</fontconfig>
+
+ User configuration file
+
+This is an example of a per-user configuration file that lives in
+~/.fonts.conf
+
+
+<?xml version="1.0"?>
+<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
+<!-- ~/.fonts.conf for per-user font configuration -->
+<fontconfig>
+
+<!--
+ Private font directory
+-->
+<dir>~/misc/fonts</dir>
+
+<!--
+ use rgb sub-pixel ordering to improve glyph appearance on
+ LCD screens. Changes affecting rendering, but not matching
+ should always use target="font".
+-->
+<match target="font">
+ <edit name="rgba" mode="assign"><const>rgb</const></edit>
+</match>
+</fontconfig>
+
+
+FILES
+
+fonts.conf
+contains configuration information for the fontconfig library
+consisting of directories to look at for font information as well as
+instructions on editing program specified font patterns before attempting to
+match the available fonts. It is in xml format.
+
+
+fonts.dtd
+is a DTD that describes the format of the configuration files.
+
+
+~/.fonts.conf
+is the conventional location for per-user font configuration, although the
+actual location is specified in the global fonts.conf file.
+
+
+ ~/.fonts.cache-*
+is the conventional repository of font information that isn't found in the
+per-directory caches. This file is automatically maintained by fontconfig.
+
+
+
diff --git a/doc/fontconfig.tex b/doc/fontconfig.tex
deleted file mode 100644
index 2e60a51..0000000
--- a/doc/fontconfig.tex
+++ /dev/null
@@ -1,55 +0,0 @@
-\documentclass[10pt]{article}
-\usepackage{latexsym}
-\usepackage{epsfig}
-\usepackage{times}
-
-\begin{document}
-\date{}
-\title{The Fontconfig Library:\\
-Architecture and Users Guide}
-\author{Keith Packard\\
-{\em XFree86 Core Team}\\
-keithp@keithp.com}
-\maketitle
-\thispagestyle{empty}
-
-\abstract
-
-The Fontconfig library provides for central administration and configuration
-of fonts in a POSIX system. All font consumers can share a common database
-of fonts and use common matching rules for font names. The set of available
-fonts can be configured for each user and a set of configurable matching
-rules allow for customizing the selection of fonts and configuring various
-parameters related to rasterizing of those fonts for display in a variety of
-media. The Fontconfig library is designed to co-exist peacefully with
-existing font configuration and rasterization mechanisms; while it uses the
-FreeType library to discover characteristics of available fonts, there
-is no requirement to use FreeType for rasterization.
-
-\section {Introduction}
-
-\section {Configuration Files}
-
-\section {Application Interface}
-
-\subsection {Datatypes}
-
-\subsection {Font Set Interface}
-
-\subsection {Font Patterns}
-
-\subsection {Listing Available Fonts}
-
-\subsection {Using Font Names}
-
-\subsection {Manipulating Matrices}
-
-\subsection {UTF-8 Helper Functions}
-
-\section {Font Sub-System Interface}
-
-\subsection {Extending Font Names}
-
-\subsection {Executing Configuration Rules}
-
-\end{document}