From 39381776a4c0cf4077a31f3a493cbd37420cec71 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Fri, 7 Mar 2003 19:01:41 +0000 Subject: [PATCH] Finish reformatting developer documentation --- doc/Makefile.am | 16 +- doc/edit-sgml.c | 17 +- doc/fcatomic.fncs | 93 ++++++++ doc/fcconfig.fncs | 153 ++++++------ doc/fcfile.fncs | 78 +++++++ doc/fcfreetype.fncs | 69 ++++++ doc/fcinit.fncs | 78 +++++++ doc/fcstring.fncs | 150 ++++++++++++ doc/fcstrset.fncs | 104 +++++++++ doc/fontconfig-devel.sgml | 475 +++++++++----------------------------- 10 files changed, 795 insertions(+), 438 deletions(-) create mode 100644 doc/fcatomic.fncs create mode 100644 doc/fcfile.fncs create mode 100644 doc/fcfreetype.fncs create mode 100644 doc/fcinit.fncs create mode 100644 doc/fcstring.fncs create mode 100644 doc/fcstrset.fncs diff --git a/doc/Makefile.am b/doc/Makefile.am index 6b18c1a..543f128 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -17,7 +17,13 @@ DOC_FUNCS_FNCS=\ fcobjecttype.fncs \ fcconstant.fncs \ fcblanks.fncs \ - fcconfig.fncs + fcconfig.fncs \ + fcinit.fncs \ + fcatomic.fncs \ + fcfreetype.fncs \ + fcfile.fncs \ + fcstrset.fncs \ + fcstring.fncs DOC_FUNCS_SGML=\ fcmatrix.sgml \ @@ -29,7 +35,13 @@ DOC_FUNCS_SGML=\ fcobjecttype.sgml \ fcconstant.sgml \ fcblanks.sgml \ - fcconfig.sgml + fcconfig.sgml \ + fcinit.sgml \ + fcatomic.sgml \ + fcfreetype.sgml \ + fcfile.sgml \ + fcstrset.sgml \ + fcstring.sgml man3_MANS= \ FcCharSetAddChar.3 \ diff --git a/doc/edit-sgml.c b/doc/edit-sgml.c index 6e04e1c..d40c9b3 100644 --- a/doc/edit-sgml.c +++ b/doc/edit-sgml.c @@ -145,6 +145,15 @@ ReplaceDispose (Replace *r) Dispose (r); } +void +Bail (char *format, char *arg) +{ + fprintf (stderr, "fatal: "); + fprintf (stderr, format, arg); + fprintf (stderr, "\n"); + exit (1); +} + Replace * ReplaceRead (FILE *f) { @@ -164,6 +173,8 @@ ReplaceRead (FILE *f) ReplaceDispose (r); return 0; } + if (isspace (c)) + Bail ("invalid character after tag %s", r->tag->buf); StringAdd (r->tag, c); } if (r->tag->buf[0] == '\0') @@ -408,10 +419,12 @@ main (int argc, char **argv) FILE *f; ReplaceSet *s; + if (!argv[1]) + Bail ("usage: %s ", argv[0]); f = fopen (argv[1], "r"); if (!f) { - perror (argv[1]); + Bail ("can't open file %s", argv[1]); exit (1); } while ((s = ReplaceSetRead (stdin))) @@ -421,6 +434,6 @@ main (int argc, char **argv) rewind (f); } if (ferror (stdout)) - exit (1); + Bail ("%s", "error writing output"); exit (0); } diff --git a/doc/fcatomic.fncs b/doc/fcatomic.fncs new file mode 100644 index 0000000..d99a110 --- /dev/null +++ b/doc/fcatomic.fncs @@ -0,0 +1,93 @@ +/* + * $Id$ + * + * Copyright © 2003 Keith Packard + * + * Permission to use, copy, modify, distribute, and sell this software and its + * documentation for any purpose is hereby granted without fee, provided that + * the above copyright notice appear in all copies and that both that + * copyright notice and this permission notice appear in supporting + * documentation, and that the name of Keith Packard not be used in + * advertising or publicity pertaining to distribution of the software without + * specific, written prior permission. Keith Packard makes no + * representations about the suitability of this software for any purpose. It + * is provided "as is" without express or implied warranty. + * + * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + * EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR + * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + * PERFORMANCE OF THIS SOFTWARE. + */ + +@RET@ FcAtomic * +@FUNC@ FcAtomicCreate +@TYPE1@ const FcChar8 * @ARG1@ file +@PURPOSE@ create an FcAtomic object +@DESC@ +Creates a data structure containing data needed to control access to 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. +@@ + +@RET@ FcBool +@FUNC@ FcAtomicLock +@TYPE1@ FcAtomic * @ARG1@ atomic +@PURPOSE@ lock a file +@DESC@ +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. +@@ + +@RET@ FcChar8 * +@FUNC@ FcAtomicNewFile +@TYPE1@ FcAtomic * @ARG1@ atomic +@PURPOSE@ return new temporary file name +@DESC@ +Returns the filename for writing a new version of the file referenced +by atomic. +@@ + +@RET@ FcChar8 * +@FUNC@ FcAtomicOrigFile +@TYPE1@ FcAtomic * @ARG1@ atomic +@PURPOSE@ return original file name +@DESC@ +Returns the file refernced by atomic. +@@ + +@RET@ FcBool +@FUNC@ FcAtomicReplaceOrig +@TYPE1@ FcAtomic * @ARG1@ atomic +@PURPOSE@ replace original with new +@DESC@ +Replaces the original file referenced by atomic with the new file. +@@ + +@RET@ void +@FUNC@ FcAtomicDeleteNew +@TYPE1@ FcAtomic * @ARG1@ atomic +@PURPOSE@ delete new file +@DESC@ +Deletes the new file. Used in error recovery to back out changes. +@@ + +@RET@ void +@FUNC@ FcAtomicUnlock +@TYPE1@ FcAtomic * @ARG1@ atomic +@PURPOSE@ unlock a file +@DESC@ +Unlocks the file. +@@ + +@RET@ void +@FUNC@ FcAtomicDestroy +@TYPE1@ FcAtomic * @ARG1@ atomic +@PURPOSE@ destroy an FcAtomic object +@DESC@ +Destroys atomic. +@@ diff --git a/doc/fcconfig.fncs b/doc/fcconfig.fncs index d6119f2..b52f4e6 100644 --- a/doc/fcconfig.fncs +++ b/doc/fcconfig.fncs @@ -21,7 +21,7 @@ * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR * PERFORMANCE OF THIS SOFTWARE. */ -@RET@ FcConfig * +@RET@ FcConfig * @FUNC@ FcConfigCreate @TYPE1@ void @PURPOSE@ Create a configuration @@ -29,9 +29,9 @@ Creates an empty configuration. @@ -@RET@ void -@FUNC@ FcConfigDestroy -@TYPE1@ FcConfig * @ARG1@ config +@RET@ void +@FUNC@ FcConfigDestroy +@TYPE1@ FcConfig * @ARG1@ config @PURPOSE@ Destroy a configuration @DESC@ Destroys a configuration and any data associated with it. Note that calling @@ -39,16 +39,16 @@ this function with the return from FcConfigGetCurrent will place the library in an indeterminate state. @@ -@RET@ FcBool -@FUNC@ FcConfigSetCurrent -@TYPE1@ FcConfig * @ARG1@ config +@RET@ FcBool +@FUNC@ FcConfigSetCurrent +@TYPE1@ FcConfig * @ARG1@ config @PURPOSE@ Set configuration as default @DESC@ Sets the current default configuration to config. Implicitly calls FcConfigBuildFonts if necessary, returning FcFalse if that call fails. @@ -@RET@ FcConfig * +@RET@ FcConfig * @FUNC@ FcConfigGetCurrent @TYPE1@ void @PURPOSE@ Return current configuration @@ -56,18 +56,18 @@ FcConfigBuildFonts if necessary, returning FcFalse if that call fails. Returns the current default configuration. @@ -@RET@ FcBool -@FUNC@ FcConfigUptoDate -@TYPE1@ FcConfig * @ARG1@ config +@RET@ FcBool +@FUNC@ FcConfigUptoDate +@TYPE1@ FcConfig * @ARG1@ config @PURPOSE@ Check timestamps on config files @DESC@ Checks all of the files related to config and returns whether the in-memory version is in sync with the disk version. @@ -@RET@ FcBool -@FUNC@ FcConfigBuildFonts -@TYPE1@ FcConfig * @ARG1@ config +@RET@ FcBool +@FUNC@ FcConfigBuildFonts +@TYPE1@ FcConfig * @ARG1@ config @PURPOSE@ Build font database @DESC@ Builds the set of available fonts for the given configuration. Note that @@ -75,18 +75,18 @@ any changes to the configuration after this call have indeterminate effects. Returns FcFalse if this operation runs out of memory. @@ -@RET@ FcStrList * -@FUNC@ FcConfigGetConfigDirs -@TYPE1@ FcConfig * @ARG1@ config +@RET@ FcStrList * +@FUNC@ FcConfigGetConfigDirs +@TYPE1@ FcConfig * @ARG1@ config @PURPOSE@ Get config directories @DESC@ Returns the list of font directories specified in the configuration files for config. Does not include any subdirectories. @@ -@RET@ FcStrList * -@FUNC@ FcConfigGetFontDirs -@TYPE1@ FcConfig * @ARG1@ config +@RET@ FcStrList * +@FUNC@ FcConfigGetFontDirs +@TYPE1@ FcConfig * @ARG1@ config @PURPOSE@ Get font directories @DESC@ Returns the list of font directories in config. This includes the @@ -94,45 +94,45 @@ configured font directories along with any directories below those in the filesystem. @@ -@RET@ FcStrList * -@FUNC@ FcConfigGetConfigFiles -@TYPE1@ FcConfig * @ARG1@ config +@RET@ FcStrList * +@FUNC@ FcConfigGetConfigFiles +@TYPE1@ FcConfig * @ARG1@ config @PURPOSE@ Get config files @DESC@ Returns the list of known configuration files used to generate config. Note that this will not include any configuration done with FcConfigParse. @@ -@RET@ char * -@FUNC@ FcConfigGetCache -@TYPE1@ FcConfig * @ARG1@ config +@RET@ char * +@FUNC@ FcConfigGetCache +@TYPE1@ FcConfig * @ARG1@ config @PURPOSE@ Get cache filename @DESC@ Returns the name of the file used to store per-user font information. @@ -@RET@ FcFontSet * -@FUNC@ FcConfigGetFonts +@RET@ FcFontSet * +@FUNC@ FcConfigGetFonts @TYPE1@ FcConfig * @ARG1@ config -@TYPE2@ FcSetName @ARG2@ set +@TYPE2@ FcSetName @ARG2@ set @PURPOSE@ Get config font set @DESC@ -Returns one of the two sets of fonts from the configuration as specified +Returns one of the two sets of fonts from the configuration as specified by set. @@ -@RET@ FcBlanks * -@FUNC@ FcConfigGetBlanks -@TYPE1@ FcConfig * @ARG1@ config +@RET@ FcBlanks * +@FUNC@ FcConfigGetBlanks +@TYPE1@ FcConfig * @ARG1@ config @PURPOSE@ Get config blanks @DESC@ Returns the FcBlanks object associated with the given configuration, if no blanks were present in the configuration, this function will return 0. @@ -@RET@ int -@FUNC@ FcConfigGetRescanInverval -@TYPE1@ FcConfig * @ARG1@ config +@RET@ int +@FUNC@ FcConfigGetRescanInverval +@TYPE1@ FcConfig * @ARG1@ config @PURPOSE@ Get config rescan interval @DESC@ Returns the interval between automatic checks of the configuration (in @@ -140,8 +140,8 @@ seconds) specified in config. The configuration is check a call to FcFontList when this interval has passed since the last check. @@ -@RET@ FcBool -@FUNC@ FcConfigSetRescanInverval +@RET@ FcBool +@FUNC@ FcConfigSetRescanInverval @TYPE1@ FcConfig * @ARG1@ config @TYPE2@ int @ARG2@ rescanInterval @PURPOSE@ Set config rescan interval @@ -149,62 +149,62 @@ a call to FcFontList when this interval has passed since the last check. Sets the rescan interval; returns FcFalse if an error occurred. @@ -@RET@ FcBool -@FUNC@ FcConfigAppFontAddFile +@RET@ FcBool +@FUNC@ FcConfigAppFontAddFile @TYPE1@ FcConfig * @ARG1@ config -@TYPE2@ const char * @ARG2@ file +@TYPE2@ const char * @ARG2@ file @PURPOSE@ Add font file to font database @DESC@ Adds an application-specific font to the configuration. @@ -@RET@ FcBool -@FUNC@ FcConfigAppFontAddDir +@RET@ FcBool +@FUNC@ FcConfigAppFontAddDir @TYPE1@ FcConfig * @ARG1@ config -@TYPE2@ const char * @ARG1@ dir +@TYPE2@ const char * @ARG1@ dir @PURPOSE@ Add fonts from directory to font database @DESC@ Scans the specified directory for fonts, adding each one found to the application-specific set of fonts. @@ -@RET@ void -@FUNC@ FcConfigAppFontClear -@TYPE1@ FcConfig * @ARG1@ config +@RET@ void +@FUNC@ FcConfigAppFontClear +@TYPE1@ FcConfig * @ARG1@ config @PURPOSE@ Remove all app fonts from font database @DESC@ Clears the set of application-specific fonts. @@ -@RET@ FcBool -@FUNC@ FcConfigSubstituteWithPat +@RET@ FcBool +@FUNC@ FcConfigSubstituteWithPat @TYPE1@ FcConfig * @ARG1@ config @TYPE2@ FcPattern * @ARG2@ p @TYPE3@ FcPattern * @ARG3@ p_pat -@TYPE4@ FcMatchKind @ARG4@ kind +@TYPE4@ FcMatchKind @ARG4@ kind @PURPOSE@ Execute substitutions @DESC@ Performs the sequence of pattern modification operations, if kind is -FcMatchPattern, then those tagged as pattern operations are applied, else +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. @@ -@RET@ FcBool -@FUNC@ FcConfigSubstitute +@RET@ FcBool +@FUNC@ FcConfigSubstitute @TYPE1@ FcConfig * @ARG1@ config @TYPE2@ FcPattern * @ARG2@ p -@TYPE3@ FcMatchKind @ARG3@ kind +@TYPE3@ FcMatchKind @ARG3@ kind @PURPOSE@ Execute substitutions @DESC@ Calls FcConfigSubstituteWithPat setting p_pat to NULL. @@ -@RET@ FcPattern * -@FUNC@ FcFontMatch +@RET@ FcPattern * +@FUNC@ FcFontMatch @TYPE1@ FcConfig * @ARG1@ config @TYPE2@ FcPattern * @ARG2@ p -@TYPE3@ FcResult * @ARG3@ result +@TYPE3@ FcResult * @ARG3@ result @PURPOSE@ Return best font @DESC@ Returns the font in config most close matching p. This function @@ -212,13 +212,13 @@ should be called only after FcConfigSubstitute and FcDefaultSubstitute have been called for p; otherwise the results will not be correct. @@ -@RET@ FcFontSet * -@FUNC@ FcFontSort +@RET@ FcFontSet * +@FUNC@ FcFontSort @TYPE1@ FcConfig * @ARG1@ config @TYPE2@ FcPattern * @ARG2@ p @TYPE3@ FcBool @ARG3@ trim @TYPE4@ FcCharSet ** @ARG4@ csp -@TYPE5@ FcResult * @ARG5@ result +@TYPE5@ FcResult * @ARG5@ result @PURPOSE@ Return list of matching fonts @DESC@ Returns the list of fonts sorted by closeness to p. If trim is FcTrue, @@ -236,11 +236,11 @@ FcFontRenderPrepare which combines them into a complete pattern. The FcFontSet returned by FcFontSort is destroyed by caling FcFontSetDestroy. @@ -@RET@ FcPattern * -@FUNC@ FcFontRenderPrepare +@RET@ FcPattern * +@FUNC@ FcFontRenderPrepare @TYPE1@ FcConfig * @ARG1@ config @TYPE2@ FcPattern * @ARG2@ pat -@TYPE3@ FcPattern * @ARG3@ font +@TYPE3@ FcPattern * @ARG3@ font @PURPOSE@ Prepare pattern for loading font file @DESC@ Creates a new pattern consisting of elements of font not appearing @@ -249,25 +249,25 @@ value from pat for elements appearing in both. The resul FcConfigSubstitute with kind FcMatchFont and then returned. @@ -@RET@ FcFontSet * -@FUNC@ FcFontList +@RET@ FcFontSet * +@FUNC@ FcFontList @TYPE1@ FcConfig * @ARG1@ config @TYPE2@ FcPattern * @ARG2@ p -@TYPE3@ FcObjectSet * @ARG3@ os +@TYPE3@ FcObjectSet * @ARG3@ os @PURPOSE@ List fonts @DESC@ Selects fonts matching p, creates patterns from those fonts containing only the objects in os and returns the set of unique such patterns. @@ -@RET@ char * -@FUNC@ FcConfigFilename -@TYPE1@ const char * @ARG1@ name +@RET@ char * +@FUNC@ FcConfigFilename +@TYPE1@ const char * @ARG1@ name @PURPOSE@ Find a config file @DESC@ Given the specified external entity name, return the associated filename. This provides applications a way to convert various configuration file -references into filename form. +references into filename form. A null or empty name indicates that the default configuration file should be used; which file this references can be overridden with the @@ -277,3 +277,16 @@ doesn't start with '/', it refers to a file in the default configuration directory; the built-in default directory can be overridden with the FC_CONFIG_DIR environment variable. @@ + +@RET@ FcBool +@FUNC@ FcConfigParseAndLoad +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ const FcChar8 * @ARG2@ file +@TYPE2@ FcBool @ARG3@ complain +@PURPOSE@ load a configuration file +@DESC@ +Walks the configuration in 'file' and constructs the internal representation +in 'config'. Any include files referenced from within 'file' will be loaded +with FcConfigLoad and also parsed. If 'complain' is FcFalse, no warning +will be displayed if 'file' does not exist. +@@ diff --git a/doc/fcfile.fncs b/doc/fcfile.fncs new file mode 100644 index 0000000..b20b099 --- /dev/null +++ b/doc/fcfile.fncs @@ -0,0 +1,78 @@ +/* + * $Id$ + * + * Copyright © 2003 Keith Packard + * + * Permission to use, copy, modify, distribute, and sell this software and its + * documentation for any purpose is hereby granted without fee, provided that + * the above copyright notice appear in all copies and that both that + * copyright notice and this permission notice appear in supporting + * documentation, and that the name of Keith Packard not be used in + * advertising or publicity pertaining to distribution of the software without + * specific, written prior permission. Keith Packard makes no + * representations about the suitability of this software for any purpose. It + * is provided "as is" without express or implied warranty. + * + * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + * EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR + * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + * PERFORMANCE OF THIS SOFTWARE. + */ + +@RET@ FcBool +@FUNC@ FcFileScan +@TYPE1@ FcFontSet * @ARG1@ set +@TYPE2@ FcStrSet * @ARG2@ dirs +@TYPE3@ FcFileCache * @ARG3@ cache +@TYPE4@ FcBlanks * @ARG4@ blanks +@TYPE5@ const char * @ARG5@ file +@TYPE6@ FcBool @ARG6@ force +@PURPOSE@ scan a font file +@DESC@ +Scans a single file and adds all fonts found to 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. +@@ + +@RET@ FcBool +@FUNC@ FcDirScan +@TYPE1@ FcFontSet * @ARG1@ set +@TYPE2@ FcStrSet * @ARG2@ dirs +@TYPE3@ FcFileCache * @ARG3@ cache +@TYPE4@ FcBlanks * @ARG4@ blanks +@TYPE5@ const char * @ARG5@ dir +@TYPE6@ FcBool @ARG6@ force +@PURPOSE@ scan a font directory +@DESC@ +Scans an entire directory and adds all fonts found to +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. +@@ + +@RET@ FcBool +@FUNC@ FcDirSave +@TYPE1@ FcFontSet * @ARG1@ set +@TYPE2@ FcStrSet * @ARG2@ dirs +@TYPE3@ const char * @ARG3@ dir +@PURPOSE@ save a directory cache +@DESC@ +Creates the per-directory cache file for dir and +populates it with the fonts in set and subdirectories +in dirs. +@@ + +@RET@ FcBool +@FUNC@ FcDirCacheValid +@TYPE1@ const FcChar8 * @ARG1@ cache_file +@PURPOSE@ check directory cache timestamp +@DESC@ +Returns FcTrue if cache_file is no older than the +directory containing it, else FcFalse. +@@ diff --git a/doc/fcfreetype.fncs b/doc/fcfreetype.fncs new file mode 100644 index 0000000..7e22582 --- /dev/null +++ b/doc/fcfreetype.fncs @@ -0,0 +1,69 @@ +/* + * $Id$ + * + * Copyright © 2003 Keith Packard + * + * Permission to use, copy, modify, distribute, and sell this software and its + * documentation for any purpose is hereby granted without fee, provided that + * the above copyright notice appear in all copies and that both that + * copyright notice and this permission notice appear in supporting + * documentation, and that the name of Keith Packard not be used in + * advertising or publicity pertaining to distribution of the software without + * specific, written prior permission. Keith Packard makes no + * representations about the suitability of this software for any purpose. It + * is provided "as is" without express or implied warranty. + * + * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + * EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR + * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + * PERFORMANCE OF THIS SOFTWARE. + */ + +@SYNOPSIS@ +#include <fontconfig.h> +#include <fcfreetype.h> +@RET@ FT_UInt +@FUNC@ FcFreeTypeCharIndex +@TYPE1@ FT_Face @ARG1@ face +@TYPE2@ FcChar32 @ARG2@ ucs4 +@PURPOSE@ map Unicode to glyph id +@DESC@ +Maps a Unicode char to a glyph index. This function uses information from +several possible underlying encoding tables to work around broken fonts. +As a result, this function isn't designed to be used in performance +sensitive areas; results from this function are intended to be cached by +higher level functions. +@@ + +@SYNOPSIS@ +#include <fontconfig.h> +#include <fcfreetype.h> +@RET@ FcCharSet * +@FUNC@ FcFreeTypeCharSet +@TYPE1@ FT_Face @ARG1@ face +@TYPE2@ FcBlanks * @ARG2@ blanks +@PURPOSE@ compute unicode coverage +@DESC@ +Scans a FreeType face and returns the set of encoded Unicode chars. This scans +several encoding tables to build as complete a list as possible. +If 'blanks' is not 0, the glyphs in the font are examined and any blank glyphs +not in 'blanks' are not placed in the returned FcCharSet. +@@ + +@SYNOPSIS@ +#include <fontconfig.h> +#include <fcfreetype.h> +@RET@ FcPattern * +@FUNC@ FcFreeTypeQuery +@TYPE1@ const char * @ARG1@ file +@TYPE2@ int @ARG2@ id +@TYPE3@ FcBlanks * @ARG3@ blanks +@TYPE4@ int * @ARG4@ count +@PURPOSE@ compute font file pattern +@DESC@ +Constructs a pattern representing the 'id'th font in 'file'. The number +of fonts in 'file' is returned in 'count'. +@@ diff --git a/doc/fcinit.fncs b/doc/fcinit.fncs new file mode 100644 index 0000000..bdf83fd --- /dev/null +++ b/doc/fcinit.fncs @@ -0,0 +1,78 @@ +/* + * $Id$ + * + * Copyright © 2003 Keith Packard + * + * Permission to use, copy, modify, distribute, and sell this software and its + * documentation for any purpose is hereby granted without fee, provided that + * the above copyright notice appear in all copies and that both that + * copyright notice and this permission notice appear in supporting + * documentation, and that the name of Keith Packard not be used in + * advertising or publicity pertaining to distribution of the software without + * specific, written prior permission. Keith Packard makes no + * representations about the suitability of this software for any purpose. It + * is provided "as is" without express or implied warranty. + * + * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + * EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR + * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + * PERFORMANCE OF THIS SOFTWARE. + */ +@RET@ FcConfig * +@FUNC@ FcInitLoadConfig +@TYPE1@ void +@PURPOSE@ load configuration +@DESC@ +Loads the default configuration file and returns the resulting configuration. +Does not load any font information. +@@ + +@RET@ FcConfig * +@FUNC@ FcInitLoadConfigAndFonts +@TYPE1@ void +@PURPOSE@ load configuration and font data +@DESC@ +Loads the default configuration file and builds information about the +available fonts. Returns the resulting configuration. +@@ + +@RET@ FcBool +@FUNC@ FcInit +@TYPE1@ void +@PURPOSE@ initialize fontconfig library +@DESC@ +Loads the default configuration file and the fonts referenced therein and +sets the default configuration to that result. Returns whether this +process succeeded or not. If the default configuration has already +been loaded, this routine does nothing and returns FcTrue. +@@ + +@RET@ int +@FUNC@ FcGetVersion +@TYPE1@ void +@PURPOSE@ library version number +@DESC@ +Returns the version number of the library. +@@ + +@RET@ FcBool +@FUNC@ FcInitReinitialize +@TYPE1@ void +@PURPOSE@ re-initialize library +@DESC@ +Forces the default configuration file to be reloaded and resets the default +configuration. +@@ + +@RET@ FcBool +@FUNC@ FcInitBringUptoDate +@TYPE1@ void +@PURPOSE@ reload configuration files if needed +@DESC@ +Checks the rescan interval in the default configuration, checking the +configuration if the interval has passed and reloading the configuration if +when any changes are detected. +@@ diff --git a/doc/fcstring.fncs b/doc/fcstring.fncs new file mode 100644 index 0000000..56254f9 --- /dev/null +++ b/doc/fcstring.fncs @@ -0,0 +1,150 @@ +/* + * $Id$ + * + * Copyright © 2003 Keith Packard + * + * Permission to use, copy, modify, distribute, and sell this software and its + * documentation for any purpose is hereby granted without fee, provided that + * the above copyright notice appear in all copies and that both that + * copyright notice and this permission notice appear in supporting + * documentation, and that the name of Keith Packard not be used in + * advertising or publicity pertaining to distribution of the software without + * specific, written prior permission. Keith Packard makes no + * representations about the suitability of this software for any purpose. It + * is provided "as is" without express or implied warranty. + * + * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + * EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR + * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + * PERFORMANCE OF THIS SOFTWARE. + */ + + +@RET@ int +@FUNC@ FcUtf8ToUcs4 +@TYPE1@ FcChar8 * @ARG1@ src +@TYPE2@ FcChar32 * @ARG2@ dst +@TYPE3@ int @ARG3@ len +@PURPOSE@ convert UTF-8 to UCS4 +@DESC@ +Converts the next Unicode char from src into +dst and returns the number of bytes containing the +char. src nust be at least +len bytes long. +@@ + +@RET@ int +@FUNC@ FcUcs4ToUtf8 +@TYPE1@ FcChar32 @ARG1@ src +@TYPE2@ FcChar8 @ARG2@ dst[FC_UTF8_MAX_LEN] +@PURPOSE@ convert UCS4 to UTF-8 +@DESC@ +Converts the Unicode char from src into +dst and returns the number of bytes needed to encode +the char. +@@ + +@RET@ FcBool +@FUNC@ FcUtf8Len +@TYPE1@ FcChar8 * @ARG1@ src +@TYPE2@ int @ARG2@ len +@TYPE3@ int * @ARG3@ nchar +@TYPE4@ int * @ARG4@ wchar +@PURPOSE@ count UTF-8 encoded chars +@DESC@ +Counts the number of Unicode chars in 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. +@@ + +@RET@ int +@FUNC@ FcUtf16ToUcs4 +@TYPE1@ FcChar8 * @ARG1@ src +@TYPE2@ FcEndian @ARG2@ endian +@TYPE3@ FcChar32 * @ARG3@ dst +@TYPE4@ int @ARG4@ len +@PURPOSE@ convert UTF-16 to UCS4 +@DESC@ +Converts the next Unicode char from 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. +@@ + +@RET@ FcBool +@FUNC@ FcUtf16Len +@TYPE1@ FcChar8 * @ARG1@ src +@TYPE2@ FcEndian @ARG2@ endian +@TYPE3@ int @ARG3@ len +@TYPE4@ int * @ARG4@ nchar +@TYPE5@ int * @ARG5@ wchar +@PURPOSE@ count UTF-16 encoded chars +@DESC@ +Counts the number of Unicode chars in 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. +@@ + +@RET@ FcChar8 * +@FUNC@ FcStrCopy +@TYPE1@ const FcChar8 * @ARG1@ s +@PURPOSE@ duplicate a string +@DESC@ +Allocates memory, copies s and returns the resulting +buffer. Yes, this is strdup, but that function isn't +available on every platform. +@@ + +@RET@ FcChar8 * +@FUNC@ FcStrCopyFilename +@TYPE1@ const FcChar8 * @ARG1@ s +@PURPOSE@ copy a string, expanding '~' +@DESC@ +Just like FcStrCopy except that it converts any leading '~' characters in +s to the value of the HOME environment variable. +Returns NULL if '~' is present in s and HOME is unset. +@@ + +@RET@ int +@FUNC@ FcStrCmpIgnoreCase +@TYPE1@ const char * @ARG1@ s1 +@TYPE2@ const char * @ARG2@ s2 +@PURPOSE@ compare UTF-8 strings ignoring ASCII case +@DESC@ +Returns the usual <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. +@@ + +@RET@ FcChar8 * +@FUNC@ FcStrDirname +@TYPE1@ const FcChar8 * @ARG1@ file +@PURPOSE@ directory part of filename +@DESC@ +Returns the directory containing file. This +is returned in newly allocated storage which should be freed when no longer +needed. +@@ + +@RET@ FcChar8 * +@FUNC@ FcStrBasename +@TYPE1@ const FcChar8 * @ARG1@ file +@PURPOSE@ last component of filename +@DESC@ +Returns the filename of file stripped of any leading +directory names. This is returned in newly allocated storage which should +be freed when no longer needed. +@@ diff --git a/doc/fcstrset.fncs b/doc/fcstrset.fncs new file mode 100644 index 0000000..9013bc9 --- /dev/null +++ b/doc/fcstrset.fncs @@ -0,0 +1,104 @@ +/* + * $Id$ + * + * Copyright © 2003 Keith Packard + * + * Permission to use, copy, modify, distribute, and sell this software and its + * documentation for any purpose is hereby granted without fee, provided that + * the above copyright notice appear in all copies and that both that + * copyright notice and this permission notice appear in supporting + * documentation, and that the name of Keith Packard not be used in + * advertising or publicity pertaining to distribution of the software without + * specific, written prior permission. Keith Packard makes no + * representations about the suitability of this software for any purpose. It + * is provided "as is" without express or implied warranty. + * + * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + * EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR + * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + * PERFORMANCE OF THIS SOFTWARE. + */ + + +@RET@ FcStrSet * +@FUNC@ FcStrSetCreate +@TYPE1@ void +@PURPOSE@ create a string set +@DESC@ +Create an empty set. +@@ + +@RET@ FcBool +@FUNC@ FcStrSetMember +@TYPE1@ FcStrSet * @ARG1@ set +@TYPE2@ const FcChar8 * @ARG2@ s +@PURPOSE@ check set for membership +@DESC@ +Returns whether s is a member of +set. +@@ + +@RET@ FcBool +@FUNC@ FcStrSetAdd +@TYPE1@ FcStrSet * @ARG1@ set +@TYPE2@ const FcChar8 * @ARG2@ s +@PURPOSE@ add to a string set +@DESC@ +Adds a copy of s to set. +@@ + +@RET@ FcBool +@FUNC@ FcStrSetAddFilename +@TYPE1@ FcStrSet * @ARG1@ set +@TYPE2@ const FcChar8 * @ARG2@ s +@PURPOSE@ add a filename to a string set +@DESC@ +Adds a copy s to set, The copy +is created with FcStrCopyFilename so that leading '~' values are replaced +with the value of the HOME environment variable. +@@ + +@RET@ FcBool +@FUNC@ FcStrSetDel +@TYPE1@ FcStrSet * @ARG1@ set +@TYPE2@ const FcChar8 * @ARG2@ s +@PURPOSE@ delete from a string set +@DESC@ +Removes s from set, returning +FcTrue if s was a member else FcFalse. +@@ + +@RET@ void +@FUNC@ FcStrSetDestroy +@TYPE1@ FcStrSet * @ARG1@ set +@PURPOSE@ destroy a string set +@DESC@ +Destroys set. +@@ + +@RET@ FcStrList * +@FUNC@ FcStrListCreate +@TYPE1@ FcStrSet * @ARG1@ set +@PURPOSE@ create a string iterator +@DESC@ +Creates an iterator to list the strings in set. +@@ + +@RET@ FcChar8 * +@FUNC@ FcStrListNext +@TYPE1@ FcStrList * @ARG1@ list +@PURPOSE@ get next string in iteration +@DESC@ +Returns the next string in set. +@@ + +@RET@ void +@FUNC@ FcStrListDone +@TYPE1@ FcStrList * @ARG1@ list +@PURPOSE@ destroy a string iterator +@DESC@ +Destroys the enumerator list. +@@ diff --git a/doc/fontconfig-devel.sgml b/doc/fontconfig-devel.sgml index b8be3f1..1528fbc 100644 --- a/doc/fontconfig-devel.sgml +++ b/doc/fontconfig-devel.sgml @@ -1,19 +1,25 @@ + + - - + + + + + + - - - + + + + ]>