From 0da305f7f85ae0dddc411df53ef077709558d369 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Sat, 1 Mar 2003 03:06:37 +0000 Subject: [PATCH] Switch to docbook and split documentation into pieces --- Makefile.am | 2 +- configure.in | 15 + doc/Makefile.am | 35 ++ src/fontconfig.3 | 1466 ---------------------------------------------- 4 files changed, 51 insertions(+), 1467 deletions(-) create mode 100644 doc/Makefile.am delete mode 100644 src/fontconfig.3 diff --git a/Makefile.am b/Makefile.am index 06ccfb5..573f84c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -21,7 +21,7 @@ # TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR # PERFORMANCE OF THIS SOFTWARE. -SUBDIRS=fontconfig fc-lang src fc-cache fc-list +SUBDIRS=fontconfig fc-lang src fc-cache fc-list doc EXTRA_DIST = \ fontconfig.pc.in \ diff --git a/configure.in b/configure.in index bfb8bcb..ed03f1a 100644 --- a/configure.in +++ b/configure.in @@ -289,6 +289,20 @@ AC_SUBST(CONFDIR) ORTH_FILES=`cd fc-lang && echo *.orth` AC_SUBST(ORTH_FILES) +# +# Figure out where to install documentation +# + +AC_ARG_WITH(docdir, [ --with-docdir=DIR Use DIR to store documentation files (default ${datadir}/doc/fontconfig)], confdir="$withval") + +if test "x$with_docdir" = "x" ; then + DOCDIR='${datadir}/doc/fontconfig' +else + DOCDIR=$with_docdir +fi + +AC_SUBST(DOCDIR) + AC_OUTPUT([ Makefile fontconfig/Makefile @@ -296,6 +310,7 @@ fc-lang/Makefile src/Makefile fc-cache/Makefile fc-list/Makefile +doc/Makefile fontconfig.spec fontconfig.pc fonts.conf diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..dc6cb7c --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,35 @@ +DOC_MODULE=fontconfig +DOC2HTML=docbook2html -u +DOC2TXT=docbook2txt + +TXT=fontconfig-user.txt fontconfig-devel.txt +HTML=fontconfig-user.html fontconfig-devel.html +SGML=fontconfig-user.sgml fontconfig-devel.sgml + +DOCDIR=@DOCDIR@ +TARGET_DIR=$(DOCDIR) + +SUFFIXES=.sgml .txt .html + +.sgml.html: + $(RM) $@ + $(DOC2HTML) $*.sgml + $(RM) index.html + +.sgml.txt: + $(RM) $@ + $(DOC2TXT) $*.sgml + +EXTRA_DIST = $(TXT) $(HTML) $(SGML) + +all-local: $(TXT) $(HTML) + +clean-local: + rm -f $(TXT) $(HTML) + +install-data-local: + $(mkinstalldirs) $(DESTDIR)$(TARGET_DIR) + for i in $(TXT) $(HTML); do \ + echo '-- Installing'$$i ; \ + $(INSTALL_DATA) $$i $(DESTDIR)$(TARGET_DIR)/$$i; \ + done diff --git a/src/fontconfig.3 b/src/fontconfig.3 deleted file mode 100644 index bc79742..0000000 --- a/src/fontconfig.3 +++ /dev/null @@ -1,1466 +0,0 @@ -.\" -.\" $RCSId: xc/lib/fontconfig/src/fontconfig.man,v 1.5 2002/08/26 19:57:40 keithp Exp $ -.\" -.\" Copyright © 2002 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. -.\" -.de TQ -.br -.ns -.TP -\\$1 -.. -.TH FONTCONFIG 3 "Version 1.0" "Fontconfig.org" - -.SH NAME -fontconfig \- Font configuration and customization library - -.SH SYNOPSIS -.nf -.B #include -.B #include -.fi -.SH DESCRIPTION -.B Fontconfig -is a library designed to provide system-wide font configuration, -customization and application access. - -.SH 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. - -.SS 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. -.P -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. -.P -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 make -simplify and regularize font installation and customization. - -.SS 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. -.sp -.nf -.ta 1i 2.75i 3.5i 5.5i -.lc \(em -Property CPP symbol Type Description - -family FC_FAMILY String Font family name -style FC_STYLE String Font style. Overrides weight and slant -slant FC_SLANT Int Italic, oblique or roman -weight FC_WEIGHT Int Light, medium, demibold, bold or black -size FC_SIZE Double Point size -aspect FC_ASPECT Double Stretches glyphs horizontally before hinting -pixelsize FC_PIXEL_SIZE Double Pixel size -spacing FC_SPACING Int Proportional, monospace or charcell -foundry FC_FOUNDRY String Font foundry name -antialias FC_ANTIALIAS Bool Whether glyphs can be antialiased -hinting FC_HINTING Bool Whether the rasterizer should use hinting -verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout -autohint FC_AUTOHINT Bool Use autohinter instead of normal hinter -globaladvance FC_GLOBAL_ADVANCE Bool Use font global advance data -file FC_FILE String The filename holding the font -index FC_INDEX Int The index of the font within the file -ftface FC_FT_FACE FT_Face Use the specified FreeType face object -rasterizer FC_RASTERIZER String Which rasterizer is in use -outline FC_OUTLINE Bool Whether the glyphs are outlines -scalable FC_SCALABLE Bool Whether glyphs can be scaled -scale FC_SCALE Double Scale factor for point->pixel conversions -dpi FC_DPI Double Target dots per inch -rgba FC_RGBA Int unknown, rgb, bgr, vrgb, vbgr, none - subpixel geometry -minspace FC_MINSPACE Bool Eliminate leading from line spacing -charset FC_CHARSET CharSet Unicode chars encoded by the font -lang FC_LANG String List of RFC-3066-style languages this font supports -.DT -.fi - -.SS 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. -.P -Font matching starts with an application constructed pattern. The desired -attributes of the resulting font are collected together in an FcPattern -object. 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. -.P -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. -.P -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. -.P -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. -.P -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. -.P -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. -.P -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. -.P -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. -.SS FONT LIST MATCHING -.P -While many applications want to locate a single font best matching their -search criteria, other applications need to build a set of fonts which can -be used to present any Unicode data. Fontconfig provides an API to generate -a list sorted by the nearness of each font to the pattern. Every font in -the system is considered, the best matching fonts are placed first. The -application then can select whether the remaining fonts are unconditionally -included in the list, or whether they are included only if they cover -portions of Unicode not covered by any of the preceeding fonts. -.P -The list resulting from this match is represented by references to the -original font patterns and so consumes very little memory. Using a list -entry involves creating a pattern which combines the information from the -font with the information from the original pattern and executing the font -substitutions. -.SS 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: -.nf - -:=:=... -.fi -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: -.sp -.nf -.ta 1i 3i - Times-12 12 point Times Roman - Times-12:bold 12 point Times Bold - Courier:italic Courier Italic in the default size - Monospace:matrix=1 .1 0 1 The users preferred monospace font - with artificial obliquing -.fi -.DT - -.SH LANG TAGS -.P -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. - -.P -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. - -.SH DATATYPES - -.TP -.B FcChar8 -.TQ -.B FcChar16 -.TQ -.B FcChar32 -.TQ -.B 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. - -.TP -.B FcMatrix -An FcMatrix holds an affine transformation, usually used to reshape glyphs. -A small set of matrix operations are provided to manipulate these. -.sp -.nf - typedef struct _FcMatrix { - double xx, xy, yx, yy; - } FcMatrix; -.fi - -.TP -.B 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. - -.TP -.B FcType -Tags the kind of data stored in an FcValue. - -.TP -.B FcValue -An FcValue object holds a single value with one of a number of different -types. The 'type' tag indicates which member is valid. -.sp -.nf - typedef struct _FcValue { - FcType type; - union { - const FcChar8 *s; - int i; - FcBool b; - double d; - const FcMatrix *m; - const FcCharSet *c; - } u; - } FcValue; -.fi -.P -.ta 1i 2i 3i 4i -.nf -.lc \(em - type Union member Datatype -  - FcTypeVoid (none) (none) - FcTypeInteger i int - FcTypeDouble d double - FcTypeString s char * - FcTypeBool b b - FcTypeMatrix m FcMatrix * - FcTypeCharSet c FcCharSet * -.fi -.DT -.TP -.B 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. - -.TP -.B FcFontSet -.sp -.nf - typedef struct _FcFontSet { - int nfont; - int sfont; - FcPattern **fonts; - } FcFontSet; -.fi -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. - -.TP -.B FcStrSet -.B 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. - -.TP -.B FcObjectSet -.sp -.nf - typedef struct _FcObjectSet { - int nobject; - int sobject; - const char **objects; - } FcObjectSet; -.fi -.sp -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. - -.TP -.B FcObjectType -.sp - typedef struct _FcObjectType { - const char *object; - FcType type; - } FcObjectType; -.fi -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. - -.TP -.B FcConstant -.sp - typedef struct _FcConstant { - const FcChar8 *name; - const char *object; - int value; - } FcConstant; -.fi -Provides for symbolic constants for new pattern elements. When 'name' is -seen in a font name, an 'object' element is created with value 'value'. - -.TP -.B 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. - -.TP -.B 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. - -.TP -.B 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. - -.TP -.B 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. - -.TP -.B FcResult -Used as a return type for functions manipulating FcPattern objects. -.P -.ta 1i 3i 4i -.lc \(em - Result code Meaning -.br -  -.br - FcResultMatch Object exists with the specified ID -.br - FcResultNoMatch Object doesn't exist at all -.br - FcResultTypeMismatch Object exists, but the type doesn't match -.br - FcResultNoId Object exists, but has fewer values than specified -.br -.DT - -.TP -.B FcAtomic -Used for locking access to config files. Provides a safe way to update -configuration files. - -.SH FUNCTIONS - -.SS FcMatrix -FcMatrix structures hold an affine transformation in matrix form. -.TP -#define FcMatrixInit(m) ((m)->xx = (m)->yy = 1, (m)->xy = (m)->yx = 0) -Initializes a matrix to the identify transformation. - -.TP -FcMatrix *FcMatrixCopy (const FcMatrix *mat) -Allocates a new FcMatrix and copies 'mat' into it. - -.TP -FcBool FcMatrixEqual (const FcMatrix *mat1, const FcMatrix *mat2) -Returns FcTrue if 'mat1' and 'mat2' are equal, else FcFalse. - -.TP -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'. - -.TP -void FcMatrixRotate (FcMatrix *m, double c, double s) -If 'c' is cos(angle) and 's' is sin(angle), FcMatrixRotate rotates the -matrix by 'angle'. - -.TP -void FcMatrixScale (FcMatrix *m, double sx, double sy) -Scales 'm' by 'sx' in the horizontal dimension and 'sy' in the -vertical dimension. - -.TP -void FcMatrixShear (FcMatrix *m, double sh, double sv) -Shears 'm' by 'sh' in the horizontal direction and 'sv' in the -vertical direction. - -.SS 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. - -.TP -FcCharSet *FcCharSetCreate (void) -Creates an empty FcCharSet object. - -.TP -void FcCharSetDestroy (FcCharSet *fcs) -Frees an FcCharSet object. - -.TP -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. - -.TP -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'. - -.TP -FcBool FcCharSetEqual (const FcCharSet *a, const FcCharSet *b) -Returns whether 'a' and 'b' contain the same set of unicode chars. - -.TP -FcCharSet *FcCharSetIntersect (const FcCharSet *a, const FcCharSet *b) -Returns a set including only those chars found in both 'a' and 'b'. - -.TP -FcCharSet *FcCharSetUnion (const FcCharSet *a, const FcCharSet *b); -Returns a set including only those chars found in either 'a' or 'b'. - -.TP -FcCharSet *FcCharSetSubtract (const FcCharSet *a, const FcCharSet *b) -Returns a set including only those chars found in 'a' but not 'b'. - -.TP -FcBool FcCharSetHasChar (const FcCharSet *fcs, FcChar32 ucs4) -Returns whether 'fcs' contains the char 'ucs4'. - -.TP -FcChar32 FcCharSetCount (const FcCharSet *a) -Returns the total number of unicode chars in 'a'. - -.TP -FcChar32 FcCharSetIntersectCount (const FcCharSet *a, const FcCharSet *b) -Returns the number of chars that are in both 'a' and 'b'. - -.TP -FcChar32 FcCharSetSubtractCount (const FcCharSet *a, const FcCharSet *b) -Returns the number of chars that are in 'a' but not in 'b'. - -.TP -FcBool FcCharSetIsSubset (const FcCharSet *a, const FcCharSet *b) -Returns whether 'a' is a subset of 'b'. - -.TP -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. - -.TP -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. - -.SS FcValue -FcValue is a structure containing a type tag and a union of all possible -datatypes. The tag is an enum of type -.B FcType -and is intended to provide a measure of run-time -typechecking, although that depends on careful programming. - -.TP -void FcValueDestroy (FcValue v) -Frees any memory referenced by `v'. Values of type FcTypeString, -FcTypeMatrix and FcTypeCharSet reference memory, the other types do not. - -.TP -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. - -.SS 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. - -.TP -FcPattern *FcPatternCreate (void) -Creates a pattern with no properties; used to build patterns from scratch. - -.TP -void FcPatternDestroy (FcPattern *p) -Destroys a pattern, in the process destroying all related values. - -.TP -FcBool FcPatternEqual (const FcPattern *pa, const FcPattern *pb); -Returns whether 'pa' and 'pb' are exactly alike. - -.TP -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'. - -.TP -FcChar32 FcPatternHash (const FcPattern *p) -Returns a 32-bit number which is the same for any two patterns which are -exactly alike. - -.TP -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. - -.TP -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'. - -.TP -FcBool FcPatternAddInteger (FcPattern *p, const char *object, int i) -.TQ -FcBool FcPatternAddDouble (FcPattern *p, const char *object, double d) -.TQ -FcBool FcPatternAddString (FcPattern *p, const char *object, const char *s) -.TQ -FcBool FcPatternAddMatrix (FcPattern *p, const char *object, const FcMatrix *s) -.TQ -FcBool FcPatternAddCharSet (FcPattern *p, const char *object, const FcCharSet *c) -.TQ -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. - -.TP -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. - -.TP -FcResult FcPatternGetInteger (FcPattern *p, const char *object, int n, int *i); -.TQ -FcResult FcPatternGetDouble (FcPattern *p, const char *object, int n, double *d); -.TQ -FcResult FcPatternGetString (FcPattern *p, const char *object, int n, char **const s); -.TQ -FcResult FcPatternGetMatrix (FcPattern *p, const char *object, int n, FcMatrix **s); -.TQ -FcResult FcPatternGetCharSet (FcPattern *p, const char *object, int n, FcCharSet **c); -.TQ -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. - -.TP -FcPattern *FcPatternBuild (FcPattern *orig, ...); -.TQ -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: -.IP -1. Object name, a string describing the property to be added. -.IP -2. Object type, one of the FcType enumerated values -.IP -3. Value, not an FcValue, but the raw type as passed to any of the -FcPatternAdd functions. Must match the type of the second argument. -.IP -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: -.RS -.IP -pattern = FcPatternBuild (0, FC_FAMILY, FtTypeString, "Times", (char *) 0); -.RE -.IP -FcPatternVaBuild is used when the arguments are already in the form of a -varargs value. - -.TP -FcBool FcPatternDel (FcPattern *p, const char *object) -Deletes all values associated with the property `object', returning -whether the property existed or not. - -.TP -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. - -.TP -void FcDefaultSubstitute (FcPattern *pattern) -Supplies default values for underspecified font patterns: -.RS -.IP \(bu -Patterns without a specified style or weight are set to Medium -.IP \(bu -Patterns without a specified style or slant are set to Roman -.IP \(bu -Patterns without a specified pixel size are given one computed from -any specified point size (default 12), dpi (default 75) and scale (default -1). -.RE - -.TP -FcPattern *FcNameParse (const char *name) -Converts 'name' from the standard text format described above into a pattern. - -.TP -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. - -.SS FcFontSet -An FcFontSet simply holds a list of patterns; these are used to return the -results of listing available fonts. -.TP -FcFontSet *FcFontSetCreate (void) -Creates an empty font set. - -.TP -void FcFontSetDestroy (FcFontSet *s); -Destroys a font set. Note that this destroys any referenced patterns as -well. - -.TP -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. - -.SS 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. - -.TP -FcObjectSet *FcObjectSetCreate (void) -Creates an empty set. - -.TP -FcBool FcObjectSetAdd (FcObjectSet *os, const char *object) -Adds a proprety name to the set. - -.TP -void FcObjectSetDestroy (FcObjectSet *os) -Destroys an object set. - - -.TP -FcObjectSet *FcObjectSetBuild (const char *first, ...) -.TQ -FcObjectSet *FcObjectSetVaBuild (const char *first, va_list va) -These build an object set from a null-terminated list of property names. - -.SS FcObjectType -Provides for applcation-specified font name object types so that new -pattern elements can be generated from font names. - -.TP -FcBool FcNameRegisterObjectTypes (const FcObjectType *types, int ntype) -Register 'ntype' new object types. - -.TP -FcBool FcNameUnregisterObjectTypes (const FcObjectType *types, int ntype) -Unregister 'ntype' object types. - -.TP -const FcObjectType *FcNameGetObjectType (const char *object) -Return the object type for the pattern element named 'object'. - -.SS FcConstant -Provides for application-specified symbolic constants for font names. - -.TP -FcBool FcNameRegisterConstants (const FcConstant *consts, int nconsts) -Register 'nconsts' new symbolic constants. - -.TP -FcBool FcNameUnregisterConstants (const FcConstant *consts, int nconsts) -Unregister 'nconsts' symbolic constants. - -.TP -const FcConstant *FcNameGetConstant (FcChar8 *string) -Return the FcConstant structure related to symbolic constant 'string'. - -.TP -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. - -.SS 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. - -.TP -FcBlanks *FcBlanksCreate (void) -Creates an empty FcBlanks object. - -.TP -void FcBlanksDestroy (FcBlanks *b) -Destroys an FcBlanks object, freeing any associated memory. - -.TP -FcBool FcBlanksAdd (FcBlanks *b, FcChar32 ucs4) -Adds a single character to an FcBlanks object, returning FcFalse -if this process ran out of memory. - -.TP -FcBool FcBlanksIsMember (FcBlanks *b, FcChar32 ucs4) -Returns whether the specified FcBlanks object contains the indicated Unicode -value. - -.SS 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. - -.TP -FcConfig *FcConfigCreate (void) -Creates an empty configuration. - -.TP -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. - -.TP -FcBool FcConfigSetCurrent (FcConfig *config) -Sets the current default configuration to 'config'. Implicitly calls -FcConfigBuildFonts if necessary, returning FcFalse if that call fails. - -.TP -FcConfig *FcConfigGetCurrent (void) -Returns the current default configuration. - -.TP -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. - -.TP -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. - -.TP -FcStrList *FcConfigGetConfigDirs (FcConfig *config) -Returns the list of font directories specified in the configuration files -for 'config'. Does not include any subdirectories. - -.TP -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. - -.TP -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. - -.TP -char *FcConfigGetCache (FcConfig *config) -Returns the name of the file used to store per-user font information. - -.TP -FcFontSet *FcConfigGetFonts (FcConfig *config, FcSetName set) -Returns one of the two sets of fonts from the configuration as specified -by 'set'. - -.TP -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. - -.TP -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. - -.TP -FcBool FcConfigSetRescanInverval (FcConfig *config, int rescanInterval) -Sets the rescan interval; returns FcFalse if an error occurred. - -.TP -FcBool FcConfigAppFontAddFile (FcConfig *config, const char *file) -Adds an application-specific font to the configuration. - -.TP -FcBool FcConfigAppFontAddDir (FcConfig *config, const char *dir) -Scans the specified directory for fonts, adding each one found to the -application-specific set of fonts. - -.TP -void FcConfigAppFontClear (FcConfig *config) -Clears the set of application-specific fonts. - -.TP -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 elements with target=pattern. - -.TP -FcBool FcConfigSubstitute (FcConfig *config, FcPattern *p, FcMatchKind kind) -Calls FcConfigSubstituteWithPat setting p_pat to NULL. - -.TP -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. - -.TP -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. -.P -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. -.P -The FcFontSet returned by FcFontSort is destroyed by caling FcFontSetDestroy. - -.TP -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. - -.TP -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. - -.TP -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. -.P -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. - -.SS Initialization -These functions provide some control over how the library is initialized. - -.TP -FcConfig *FcInitLoadConfig (void) -Loads the default configuration file and returns the resulting configuration. -Does not load any font information. - -.TP -FcConfig *FcInitLoadConfigAndFonts (void) -Loads the default configuration file and builds information about the -available fonts. Returns the resulting configuration. - -.TP -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. - -.TP -int FcGetVersion (void) -Returns the version number of the library. - -.TP -FcBool FcInitReinitialize (void) -Forces the default configuration file to be reloaded and resets the default -configuration. - -.TP -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. - -.SS 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. - -.TP -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. - -.TP -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. - -.TP -FcChar8 *FcAtomicNewFile (FcAtomic *atomic) -Returns the filename for writing a new version of the file referenced -by 'atomic'. - -.TP -FcChar8 *FcAtomicOrigFile (FcAtomic *atomic) -Returns the file refernced by 'atomic'. - -.TP -FcBool FcAtomicReplaceOrig (FcAtomic *atomic) -Replaces the original file referenced by 'atomic' with the new file. - -.TP -void FcAtomicDeleteNew (FcAtomic *atomic) -Deletes the new file. - -.TP -void FcAtomicUnlock (FcAtomic *atomic) -Unlocks the file. - -.TP -void FcAtomicDestroy (FcAtomic *atomic) -Destroys 'atomic'. - -.SS FreeType specific functions -.nf -.B #include -.fi -While the fontconfig library doesn't insist that FreeType be used as the -rasterization mechanism for fonts, it does provide some convenience -functions. - -.TP -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. - -.TP -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. - -.TP -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'. - -.SS XML specific functions -.TP -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. - -.SS File and Directory routines - -.TP -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'. - -.TP -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'. - -.TP -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'. - -.TP -FcBool FcDirCacheValid (const FcChar8 *cache_file) -Returns FcTrue if 'cache_file' is no older than the directory containing it, -else FcFalse. - -.SS FcStrSet and FcStrList -A data structure for enumerating strings, used to list directories while -scanning the configuration as directories are added while scanning. - -.TP -FcStrSet *FcStrSetCreate (void) -Create an empty set. - -.TP -FcBool FcStrSetMember (FcStrSet *set, const FcChar8 *s) -Returns whether 's' is a member of 'set'. - -.TP -FcBool FcStrSetAdd (FcStrSet *set, const FcChar8 *s) -Adds a copy of 's' to 'set'. - -.TP -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. - -.TP -FcBool FcStrSetDel (FcStrSet *set, const FcChar8 *s) -Removes 's' from 'set', returning FcTrue if 's' was a member else FcFalse. - -.TP -void FcStrSetDestroy (FcStrSet *set) -Destroys 'set'. - -.TP -FcStrList *FcStrListCreate (FcStrSet *set) -Creates an enumerator to list the strings in 'set'. - -.TP -FcChar8 *FcStrListNext (FcStrList *list) -Returns the next string in 'set'. - -.TP -void FcStrListDone (FcStrList *list) -Destroys the enumerator 'list'. - -.SS String utilities - -.TP -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. - -.TP -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. - -.TP -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. - -.TP -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'. - -.TP -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. - -.TP -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. - -.TP -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. - -.TP -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. - -.TP -FcChar8 *FcStrDirname (const FcChar8 *file) -Returns the directory containing 'file'. - -.TP -FcChar8 *FcStrBasename (const FcChar8 *file) -Returns the filename of 'file' stripped of any leading directory names. - -.SH 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. -.P -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: -.sp -.nf - - - - ... - -.fi -.P -.SS -This is the top level element for a font configuration and can contain -, , , and elements in any order. - -.SS -This element contains a directory name which will be scanned for font files -to include in the set of available fonts. - -.SS -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-'', where is the font configuration -file version number (currently 1). - -.SS -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. - -.SS -This element provides a place to consolodate additional configuration -information. can contain and elements in any -order. - -.SS -Fonts often include "broken" glyphs which appear in the encoding but are -drawn as blanks on the screen. Within the element, place each -Unicode characters which is supposed to be blank in an element. -Characters outside of this set which are drawn as blank will be elided from -the set of characters supported by the font. -The element holds an 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. - -.SS -This element holds first a (possibly empty) list of elements and then -a (possibly empty) list of 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. - -.SS -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. - -.SS -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 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: -.nf -.RS -.ta 1i 3i 5i -Mode Operation with match Operation without match - -"assign" Replace matching value Replace all values -"assign_replace" Replace all values Replace all values -"prepend" Insert before matching value Insert at head of list -"prepend_first" Insert at head of list Insert at head of list -"append" Append after matching value Append at end of list -"append_last" Append at end of list Append at end of list -.RE -.DT -.fi -.SS -.SS -.SS -.SS -These elements hold a single value of the indicated type. elements -hold either true or false. -.SS -This element holds the four elements of an affine transformation. -.SS -Holds a property name. Evaluates to the first value from the property of -the font, not the pattern. -.SS -Holds the name of a constant; these are always integers and serve as -symbolic names for common font values: -.RS -.sp -.nf -.ta 1i 2i 3i -.lc \(em -Constant Property CPP symbol - -light weight FC_WEIGHT_LIGHT -medium weight FC_WEIGHT_MEDIUM -demibold weight FC_WEIGHT_DEMIBOLD -bold weight FC_WEIGHT_BOLD -black weight FC_WEIGHT_BLACK -roman slant FC_SLANT_ROMAN -italic slant FC_SLANT_ITALIC -oblique slant FC_SLANT_OBLIQUE -proportional spacing FC_PROPORTIONAL -mono spacing FC_MONO -charcell spacing FC_CHARCELL -unknown rgba FC_RGBA_UNKNOWN -rgb rgba FC_RGBA_RGB -bgr rgba FC_RGBA_BGR -vrgb rgba FC_RGBA_VRGB -vbgr rgba FC_RGBA_VBGR -none rgba FC_RGBA_NONE -.DT -.fi -.RE -.SS -.SS -.SS -.SS -.SS -.SS -These elements perform the specified operation on a list of expression -elements. and are boolean, not bitwise. -.SS -.SS -.SS -.SS -.SS -.SS -These elements compare two values, producing a boolean result. -.SS -Inverts the boolean sense of its one expression element -.SS -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. -.SS -Alias elements provide a shorthand notation for the set of common match -operations needed to substitute one font family for another. They contain a - element followed by optional , and -elements. Fonts matching the element are edited to prepend the -list of ed families before the matching , append the -able familys after the matching and append the -families to the end of the family list. -.SS -Holds a single font family name -.SS -.SS -.SS -These hold a list of elements to be used by the element. -.SH EXAMPLE CONFIGURATION FILE -.SS System configuration file -This is an example of a system-wide configuration file -.sp -.nf - - - - - -/usr/X11R6/lib/X11/fonts/truetype -/usr/X11R6/lib/X11/fonts/Type1 - - - - mono - monospace - - - - - sans - serif - monospace - sans - - - -~/.fonts.conf - - - - Times - Times New Roman - serif - - - Helvetica - Verdana - sans - - - Courier - Courier New - monospace - - - - - serif - Times New Roman - - - sans - Verdana - - - monospace - Andale Mono - - -.fi -.SS User configuration file -This is an example of a per-user configuration file that lives in -~/.fonts.conf -.sp -.nf - - - - - - -~/misc/fonts - - - - rgb - - -.fi -.SH FILES -.B 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. - -.B fonts.dtd -is a DTD that describes the format of the configuration files. - -.B ~/.fonts.conf -is the conventional location for per-user font configuration, although the -actual location is specified in the global fonts.conf file. - -.B ~/.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. - -.SH AUTHOR -Keith Packard -- 2.39.5