[general-docs] Updates to fontconfig.texi

general-docs I've finally got around to doing some long-postponed work in general-docs. These are some accumulated changes to fontconfig.texi. Aidan, I would appreciate it if you would take a look at the Initialization node, where you've done some work recently. I will check again before committing, but (knowing me) I think the odds are pretty good that if I've done violence to your changes, I'll overlook them, while (if you're anything like me ;-) you can probably detect such offenses blindfolded. There are definitely lags between this version and the current documents in upstream. I'm not sure whether it's worth syncing or not, since those are in man format, not texi. Index: xemacs-packages/general-docs/ChangeLog =================================================================== RCS file: /Users/steve/Software/Repositories/cvs.xemacs.org/XEmacs/packages/xemacs-packages/general-docs/ChangeLog,v retrieving revision 1.16 diff -u -U 0 -r1.16 ChangeLog --- xemacs-packages/general-docs/ChangeLog 7 May 2005 12:23:53 -0000 1.16 +++ xemacs-packages/general-docs/ChangeLog 12 Aug 2006 13:26:18 -0000 ＠＠ -0,0 +1,24 ＠＠ +2006-08-12 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * texi/xemacs/fontconfig.texi (Top, Overview): Note need for sync. + +2006-07-13 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * texi/xemacs/fontconfig.texi (Querying Fonts and Their Properties): + Fix typos. + +2005-08-01 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * texi/xemacs/fontconfig.texi (Initialization): Reorganize. Make + clear that FcInit() doesn't need to be called, and that any + function that forces reexamination of the fonts is expensive. + +2005-04-09 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * texi/xemacs/fontconfig.texi (FcPattern): Fix typo. + +2005-01-23 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * texi/xemacs/fontconfig.texi (Querying Fonts and Their + Properties): Improve organization. + Index: xemacs-packages/general-docs/texi/xemacs/fontconfig.texi =================================================================== RCS file: /Users/steve/Software/Repositories/cvs.xemacs.org/XEmacs/packages/xemacs-packages/general-docs/texi/xemacs/fontconfig.texi,v retrieving revision 1.3 diff -u -r1.3 fontconfig.texi --- xemacs-packages/general-docs/texi/xemacs/fontconfig.texi 5 May 2005 18:06:43 -0000 1.3 +++ xemacs-packages/general-docs/texi/xemacs/fontconfig.texi 12 Aug 2006 12:07:10 -0000 ＠＠ -38,7 +38,8 ＠＠ This file documents fontconfig, a rendering-engine-independent library for managing font metainformation (＠emph{i.e.}, everything but the glyph -data themselves). It is ＠emph{not} part of XEmacs. +data themselves). It is ＠emph{not} part of XEmacs. It is also +＠emph{not} very current with upstream documentation. Copyright © 2002 Keith Packard, member of The XFree86 Project, Inc. Copyright © 2003 Stephen J. Turnbull, member of the XEmacs Project ＠＠ -164,7 +165,8 ＠＠ Fontconfig is a library designed to provide system-wide font configuration, customization and application access. -This manual describes fontconfig version 1.0.2. +This manual describes fontconfig version 1.0.2. ＠strong{It is still +useful, but should be sync'ed to upstream.} ＠c FUNCTIONAL OVERVIEW Fontconfig contains two essential modules, the configuration module which ＠＠ -315,12 +317,12 ＠＠ Here are some examples: ＠example -Times-12 12 point Times Roman -Times-12:bold 12 point Times Bold +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 +Monospace:matrix=1 .1 0 1 The user's preferred monospace font with artificial obliquing -Mikachan\-PB-16 12 point Mikachan-PB +Mikachan\-PB-16 16-point Mikachan-PB ＠end example ＠node LANG Tags, , Font Names, Overview ＠＠ -526,7 +528,8 ＠＠ ＠item 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 +property of a font. The names are interned in an internal hash table. +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. ＠＠ -576,8 +579,9 ＠＠ ＠} FcObjectType; ＠end example 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. +Applications can add new object types so that font names which contain +the new elements can be parsed correctly. (Note: this is not the +representation of an object in an FcPattern.) ＠item FcConstant ＠＠ -847,15 +851,20 ＠＠ Destroys a pattern, in the process destroying all related values. ＠end deftypefun +＠deftypefun FcPattern *FcPatternDuplicate (FcPattern *p) + +Returns a copy of pattern ＠var{p}. +＠end deftypefun + ＠deftypefun FcBool FcPatternEqual (const FcPattern *pa, const FcPattern *pb); -Returns whether 'pa' and 'pb' are exactly alike. +Returns whether ＠var{pa} and ＠var{pb} are exactly alike. ＠end deftypefun ＠deftypefun 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'. +Returns whether ＠var{pa} and ＠var{pb} have exactly the same values for +all of the objects in ＠var{os}. ＠end deftypefun ＠deftypefun FcChar32 FcPatternHash (const FcPattern *p) ＠＠ -867,15 +876,17 ＠＠ ＠deftypefun 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 +`object'. (The name of the object added to the FcPattern is a pointer to a +copy stored in an internal hash table, not the pointer ＠var{object} itself.) +If `append' is FcTrue, the value is added at the end of any +existing list, otherwise it is inserted at the beginning. `value' is saved (with FcValueSave) when inserted into the pattern so that the library retains no reference to any application-supplied data structure. ＠end deftypefun ＠deftypefun FcBool FcPatternAddWeak (FcPattern *p, const char *object, FcValue value, FcBool append) -FcPatternAddWeak is essentially the same as FcPatternAdd except that any +FcPatternAddWeak is the same as FcPatternAdd except that any values added to the list have binding 'weak' instead of 'strong'. ＠end deftypefun ＠＠ -1027,7 +1038,9 ＠＠ ＠deftypefun FcBool FcObjectSetAdd (FcObjectSet *os, const char *object) -Adds a property name to the set. +Adds a property name to the set. (The name of the object added to the +FcPattern is a pointer to a copy stored in an internal hash table, not +the pointer ＠var{object} itself.) ＠end deftypefun ＠deftypefun void FcObjectSetDestroy (FcObjectSet *os) ＠＠ -1157,55 +1170,15 ＠＠ ＠node Querying Fonts and Their Properties, Initialization, FcLangSet, Functions ＠subsection Querying Fonts and Their Properties -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. - -＠deftypefun FcBlanks *FcBlanksCreate (void) - -Creates an empty FcBlanks object. -＠end deftypefun - -＠deftypefun void FcBlanksDestroy (FcBlanks *b) - -Destroys an FcBlanks object, freeing any associated memory. -＠end deftypefun - -＠deftypefun FcBool FcBlanksAdd (FcBlanks *b, FcChar32 ucs4) - -Adds a single character to an FcBlanks object, returning FcFalse -if this process ran out of memory. -＠end deftypefun - -＠deftypefun FcBool FcBlanksIsMember (FcBlanks *b, FcChar32 ucs4) - -Returns whether the specified FcBlanks object contains the indicated Unicode -value. -＠end deftypefun - -The site or user may specify substitutions for certain font patterns, -for convenience or to get more accurate results for the local -installation or preferences. These functions execute the substitution -based on a specified configuration. - -＠deftypefun 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. -＠end deftypefun - -＠deftypefun FcBool FcConfigSubstitute (FcConfig *config, FcPattern *p, FcMatchKind kind) - -Calls FcConfigSubstituteWithPat setting p_pat to NULL. -＠end deftypefun +The mission of the ＠file{fontconfig} library is providing a standard +interface to query the fonts available to a program. This section +describes the query functions, followed by descriptions of auxiliary +facilities for default pattern substitutions and handling of blank +characters. The following functions return fonts that match a certain pattern. ＠code{FcFontRenderPrepare} and ＠code{FcFontMatch} always return a single -best match. ＠code{FcFontList} returns the list of fonts that match a a +best match. ＠code{FcFontList} returns the list of fonts that match a given pattern on a certain set of properties. ＠code{FcFontSort} returns the entire list of fonts, sorted in order of match quality, possibly filtering out fonts that do not provide additional characters beyond ＠＠ -1221,7 +1194,7 ＠＠ ＠deftypefun {FcPattern *} FcFontMatch (FcConfig *config, FcPattern *p, FcResult *result) -Returns the font in 'config' most close matching 'p'. This function +Returns the font in 'config' most closely matching 'p'. This function should be called only after FcConfigSubstitute and FcDefaultSubstitute have been called for 'p'; otherwise the results will not be correct. ＠end deftypefun ＠＠ -1229,7 +1202,10 ＠＠ ＠deftypefun FcFontSet *FcFontList (FcConfig *config, FcPattern *p, FcObjectSet *os) Selects fonts matching 'p', creates patterns containing only the objects in -'os' from those fonts, and returns the set of unique such patterns. +'os' from those fonts, and returns the set of such patterns (with duplicates +deleted). Any object unspecified in ＠var{pattern} is a wildcard, and the +returned fonts must match on all specified objects. The patterns are +truncated after matching. The FcFontSet returned by FcFontList is destroyed by calling FcFontSetDestroy. ＠end deftypefun ＠＠ -1252,10 +1228,135 ＠＠ The FcFontSet returned by FcFontSort is destroyed by calling FcFontSetDestroy. ＠end deftypefun +The site or user may specify substitutions for certain font patterns, +for convenience or to get more accurate results for the local +installation or preferences. These functions execute the substitution +based on a specified configuration. + +＠deftypefun 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. +＠end deftypefun + +＠deftypefun FcBool FcConfigSubstitute (FcConfig *config, FcPattern *p, FcMatchKind kind) + +Calls FcConfigSubstituteWithPat setting p_pat to NULL. +＠end deftypefun + +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. + +＠deftypefun FcBlanks *FcBlanksCreate (void) + +Creates an empty FcBlanks object. +＠end deftypefun + +＠deftypefun void FcBlanksDestroy (FcBlanks *b) + +Destroys an FcBlanks object, freeing any associated memory. +＠end deftypefun + +＠deftypefun FcBool FcBlanksAdd (FcBlanks *b, FcChar32 ucs4) + +Adds a single character to an FcBlanks object, returning FcFalse +if this process ran out of memory. +＠end deftypefun + +＠deftypefun FcBool FcBlanksIsMember (FcBlanks *b, FcChar32 ucs4) + +Returns whether the specified FcBlanks object contains the indicated Unicode +value. +＠end deftypefun + ＠node Initialization, FcAtomic, Querying Fonts and Their Properties, Functions ＠subsection Initialization + +For most purposes, the default configuration (parsed and initialized +from both system and user configuration files) is sufficient. + +＠deftypefun 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. + +The default configuration is normally implicitly initialized; you +probably do not have to call this function, but it shouldn't hurt to do +so. +＠end deftypefun + +＠deftypefun FcBool FcInitBringUptoDate (void) + +Checks the rescan interval in the default configuration, checking the +configuration if the interval has passed and reloading the configuration +when any changes are detected. +＠end deftypefun + +＠deftypefun FcBool FcInitReinitialize (void) + +Forces the default configuration file to be reloaded and resets the default +configuration. +＠c #### CHECK THIS!! +This is an expensive operation. +＠end deftypefun + + +These functions provide some control over how the default configuration of +the library is initialized. (This configuration is normally implicitly +initialized.) + +＠deftypefun 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. +＠end deftypefun + +＠deftypefun FcConfig *FcInitLoadConfig (void) + +Loads the default configuration file and returns the resulting configuration. +Does not load any font information. Unless you need to use multiple +configs, it is probably not very useful to call this function from user +code (use ＠code{FcInit()} or ＠code{FcInitReinitialize()} instead). +＠end deftypefun + +＠deftypefun FcConfig *FcInitLoadConfigAndFonts (void) + +Loads the default configuration file and builds information about the +available fonts. Returns the resulting configuration. Unless you need to +use multiple configs, it is probably not very useful to call this function +from user code (use ＠code{FcInit()} or ＠code{FcInitReinitialize()} instead). +This is an expensive operation since it searches for and reads the font +files. +＠end deftypefun + + +If you need to work with different versions of the API, use +＠code{FcGetVersion} to get the library's version information. + +＠deftypefun int FcGetVersion (void) + +Returns the version number of the library. +＠end deftypefun + + 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. ＠＠ -1360,64 +1461,6 ＠＠ Clears the set of application-specific fonts. ＠end deftypefun -These functions provide some control over how the default configuration of -the library is initialized. (This configuration is normally implicitly -initialized.) - -＠deftypefun 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. -＠end deftypefun - -＠deftypefun FcConfig *FcInitLoadConfig (void) - -Loads the default configuration file and returns the resulting configuration. -Does not load any font information. -＠end deftypefun - -＠deftypefun FcConfig *FcInitLoadConfigAndFonts (void) - -Loads the default configuration file and builds information about the -available fonts. Returns the resulting configuration. -＠end deftypefun - -＠deftypefun 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. -＠end deftypefun - -＠deftypefun int FcGetVersion (void) - -Returns the version number of the library. -＠end deftypefun - -＠deftypefun FcBool FcInitReinitialize (void) - -Forces the default configuration file to be reloaded and resets the default -configuration. -＠end deftypefun - -＠deftypefun FcBool FcInitBringUptoDate (void) - -Checks the rescan interval in the default configuration, checking the -configuration if the interval has passed and reloading the configuration -when any changes are detected. -＠end deftypefun - - ＠node FcAtomic, FreeType-Specific Functions, Initialization, Functions ＠subsection FcAtomic -- Graduate School of Systems and Information Engineering University of Tsukuba http://turnbull.sk.tsukuba.ac.jp/ Tennodai 1-1-1 Tsukuba 305-8573 JAPAN Economics of Information Communication and Computation Systems Experimental Economics, Microeconomic Theory, Game Theory