Add FcPatternFilter() (#13016)

[fontconfig.git] / doc / fcfile.fncs

diff --git a/doc/fcfile.fncs b/doc/fcfile.fncs
index df7400bdaf84162641361664d849d94eb1afb636..80d7e7f7270876488f36b766c301e50f9e7f5bf9 100644 (file)
--- a/doc/fcfile.fncs
+++ b/doc/fcfile.fncs
@@ -28,7 +28,7 @@
 @TYPE2@                FcStrSet *                      @ARG2@          dirs    
 @TYPE3@                FcFileCache *                   @ARG3@          cache   
 @TYPE4@                FcBlanks *                      @ARG4@          blanks  
-@TYPE5@                const char *                    @ARG5@          file    
+@TYPE5@                const FcChar8 *                 @ARG5@          file    
 @TYPE6@                FcBool%                                 @ARG6@          force   
 @PURPOSE@      scan a font file
 @DESC@
@@ -37,7 +37,21 @@ If <parameter>force</parameter> is FcTrue, then the file is scanned even if
 associated information is found in <parameter>cache</parameter>.  If
 <parameter>file</parameter> is a directory, it is added to
 <parameter>dirs</parameter>. Whether fonts are found depends on fontconfig
-poliy as well as the current configuration.
+policy as well as the current configuration. Internally, fontconfig will
+ignore BDF and PCF fonts which are not in Unicode (or the effectively
+equivalent ISO Latin-1) encoding as those are not usable by Unicode-based
+applications. The configuration can ignore fonts based on filename or
+contents of the font file itself. Returns FcFalse if any of the fonts cannot be
+added (due to allocation failure). Otherwise returns FcTrue.
+@@
+
+@RET@          FcBool
+@FUNC@         FcFileIsDir
+@TYPE1@                const FcChar8 *                 @ARG1@          file
+@PURPOSE@      check whether a file is a directory
+@DESC@
+Returns FcTrue if <parameter>file</parameter> is a directory, otherwise
+returns FcFalse.
 @@
 
 @RET@          FcBool  
@@ -46,36 +60,29 @@ poliy as well as the current configuration.
 @TYPE2@                FcStrSet *                      @ARG2@          dirs    
 @TYPE3@                FcFileCache *                   @ARG3@          cache   
 @TYPE4@                FcBlanks *                      @ARG4@          blanks  
-@TYPE5@                const char *                    @ARG5@          dir     
+@TYPE5@                const FcChar8 *                 @ARG5@          dir     
 @TYPE6@                FcBool%                                 @ARG6@          force   
-@PURPOSE@      scan a font directory
+@PURPOSE@      DEPRECATED: formerly used to scan a font directory
 @DESC@
-Scans an entire directory and adds all fonts found to
-<parameter>set</parameter>.  If <parameter>force</parameter> is FcTrue, then
-the directory and all files within it are scanned even if information is
-present in the per-directory cache file or <parameter>cache</parameter>.  Any
-subdirectories found are added to <parameter>dirs</parameter>. Whether fonts
-or directories are found depends on fontconfig
-policy as well as the current configuration.
+This function does nothing aside from returning FcFalse. It used to scan an
+entire directory and add all fonts found to
+<parameter>set</parameter>.  If <parameter>force</parameter> was FcTrue, then
+the directory and all files within it were scanned even if information was
+present in the per-directory cache file or <parameter>cache</parameter>. Any
+subdirectories found were added to <parameter>dirs</parameter>.
 @@
 
 @RET@          FcBool  
 @FUNC@         FcDirSave 
 @TYPE1@                FcFontSet *                     @ARG1@          set     
 @TYPE2@                FcStrSet *                      @ARG2@          dirs    
-@TYPE3@                const char *                    @ARG3@          dir     
-@PURPOSE@      save a directory cache
+@TYPE3@                const FcChar8 *                 @ARG3@          dir     
+@PURPOSE@      DEPRECATED: formerly used to save a directory cache
 @DESC@
-Creates the per-directory cache file for <parameter>dir</parameter> and
-populates it with the fonts in <parameter>set</parameter> and subdirectories
-in <parameter>dirs</parameter>.
+This function now does nothing aside from returning FcFalse. It used to creates the
+per-directory cache file for <parameter>dir</parameter> and populates it
+with the fonts in <parameter>set</parameter> and subdirectories in
+<parameter>dirs</parameter>. All of this functionality is now automatically
+managed by FcDirCacheLoad and FcDirCacheRead.
 @@
 
-@RET@          FcBool  
-@FUNC@         FcDirCacheValid 
-@TYPE1@                const FcChar8 *                 @ARG1@          cache_file      
-@PURPOSE@      check directory cache timestamp
-@DESC@
-Returns FcTrue if <parameter>cache_file</parameter> is no older than the
-directory containing it, else FcFalse.
-@@