kc3-lang/freetype

diff --git a/ChangeLog b/ChangeLog
index 0be5f22..514adbe 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2002-07-07  David Turner  <david@freetype.org>
+
+    * docs/DEBUG.TXT: adding debugging support documentation
+
+    * src/base/ftdebug.c (ft_debug_init), builds/win32/ftdebug.c
+    (ft_debug_init), builds/amiga/src/ftdebug.c (ft_debug_init): changed the
+    syntax of the FT2_DEBUG environment variable  used to control debugging
+    output (i.e. logging and error messages). It must now look like:
+
+       any:6 memory:4 io:3   or
+       any:6,memory:4,io:3   or
+       any:6;memory:4;io:3
+
 2002-07-07  Owen Taylor  <owen@redhat.com>
 
     * include/freetype/freetype.h, src/base/ftobjs.h,
diff --git a/builds/amiga/src/base/ftdebug.c b/builds/amiga/src/base/ftdebug.c
index 7a04c1f..a618687 100644
--- a/builds/amiga/src/base/ftdebug.c
+++ b/builds/amiga/src/base/ftdebug.c
@@ -100,49 +100,49 @@ extern void __stdargs KVPrintF( const char *formatString, const void *values );
   ft_debug_init( void )
   {
     const char*  ft2_debug = getenv( "FT2_DEBUG" );
-    
+
 
     if ( ft2_debug )
     {
       const char*  p = ft2_debug;
       const char*  q;
-      
+
 
       for ( ; *p; p++ )
       {
         /* skip leading whitespace and separators */
-        if ( *p == ' ' || *p == '\t' || *p == ':' || *p == ';' || *p == '=' )
+        if ( *p == ' ' || *p == '\t' || *p == ',' || *p == ';' || *p == '=' )
           continue;
-          
+
         /* read toggle name, followed by '=' */
         q = p;
-        while ( *p && *p != '=' )
+        while ( *p && *p != ':' )
           p++;
-          
-        if ( *p == '=' && p > q )
+
+        if ( *p == ':' && p > q )
         {
           int  n, i, len = p - q;
           int  level = -1, found = -1;
-          
+
 
           for ( n = 0; n < trace_count; n++ )
           {
             const char*  toggle = ft_trace_toggles[n];
-            
+
 
             for ( i = 0; i < len; i++ )
             {
               if ( toggle[i] != q[i] )
                 break;
             }
-            
+
             if ( i == len && toggle[i] == 0 )
             {
               found = n;
               break;
             }
           }
-          
+
           /* read level */
           p++;
           if ( *p )
@@ -151,7 +151,7 @@ extern void __stdargs KVPrintF( const char *formatString, const void *values );
             if ( level < 0 || level > 6 )
               level = -1;
           }
-          
+
           if ( found >= 0 && level >= 0 )
           {
             if ( found == trace_any )
diff --git a/builds/win32/ftdebug.c b/builds/win32/ftdebug.c
index 7615172..5816a4f 100644
--- a/builds/win32/ftdebug.c
+++ b/builds/win32/ftdebug.c
@@ -107,9 +107,9 @@
   /*                                                                       */
   /* Initialize the tracing sub-system.  This is done by retrieving the    */
   /* value of the "FT2_DEBUG" environment variable.  It must be a list of  */
-  /* toggles, separated by spaces, `;' or `:'.  Example:                   */
+  /* toggles, separated by spaces, `;' or `,'.  Example:                   */
   /*                                                                       */
-  /*    "any=3 memory=6 stream=5"                                          */
+  /*    "any:3 memory:6 stream:5"                                          */
   /*                                                                       */
   /* This will request that all levels be set to 3, except the trace level */
   /* for the memory and stream components which are set to 6 and 5,        */
@@ -136,15 +136,15 @@
       for ( ; *p; p++ )
       {
         /* skip leading whitespace and separators */
-        if ( *p == ' ' || *p == '\t' || *p == ':' || *p == ';' || *p == '=' )
+        if ( *p == ' ' || *p == '\t' || *p == ',' || *p == ';' || *p == '=' )
           continue;
 
-        /* read toggle name, followed by '=' */
+        /* read toggle name, followed by ':' */
         q = p;
-        while ( *p && *p != '=' )
+        while ( *p && *p != ':' )
           p++;
 
-        if ( *p == '=' && p > q )
+        if ( *p == ':' && p > q )
         {
           int  n, i, len = p - q;
           int  level = -1, found = -1;
diff --git a/docs/DEBUG.TXT b/docs/DEBUG.TXT
new file mode 100644
index 0000000..86ffbcf
--- /dev/null
+++ b/docs/DEBUG.TXT
@@ -0,0 +1,164 @@
+Debugging within the FreeType sources:
+======================================
+
+I. Configuration macros:
+========================
+
+There are several ways to enable debugging features in a FreeType 2 builds.
+This is controled through the definition of special macros located in the
+file "ftoptions.h". The macros are:
+
+
+  FT_DEBUG_LEVEL_ERROR ::
+
+    #define this macro if you want to compile the FT_ERROR macro calls
+    used to print error messages during program execution. This will not
+    stop the program, but is very useful to spot invalid fonts during
+    development and code wordarounds for them.
+
+
+  FT_DEBUG_LEVEL_TRACE ::
+
+    #define this macro if you want to compile both the FT_ERROR macro and
+    the FT_TRACE one. This also includes the variants FT_TRACE0, FT_TRACE1,
+    FT_TRACE2, ..., FT_TRACE6.
+
+    The trace macros are used to send debugging messages when an appropriate
+    "debug level" is configured at runtime through the FT2_DEBUG environment
+    variable (more on this later)
+
+
+  FT_DEBUG_MEMORY ::
+
+    when this macro is #defined, the FreeType engines is linked with a small
+    but effective debugging memory manager that tracks all allocations and
+    frees that are performed within the font engine.
+
+    When the FT2_DEBUG_MEMORY environment variable is defined at runtime, a
+    call to FT_Done_FreeType will dump memory statistics, including the list of
+    leaked memory blocks with the source locations where these were allocated.
+    It's always a very good idea to define this in development builds. This
+    works with _any_ program linked to FreeType, but requires a big deal of
+    memory (the debugging memory manager never frees the blocks to the
+    heap in order to detect double frees).
+
+    When FT2_DEBUG_MEMORY isn't defined at runtime, the debugging memory
+    manager is ignored, and performance is un-affected.
+
+
+II. Debugging macros:
+=====================
+
+  Several macros can be used within the FreeType sources to help debugging
+  its code:
+
+ 1. FT_ERROR(( .. ))
+
+   this macro is used to send debug messages that indicate relatively serious
+   errors (like broken font files), but will not stop the execution of the
+   running program. Its code is compiled only when either FT_DEBUG_LEVEL_ERROR
+   or FT_DEBUG_LEVEL_TRACE are defined in "ftoption.h"
+
+   Note that you must use with a printf-like signature, but with double
+   parentheses, like in:
+
+     FT_ERROR(( "your %s is not %s\n", "foo", "bar" ));
+
+
+ 2. FT_ASSERT( condition )
+
+   this macro is used to check strong assertions at runtime. If its condition
+   isn't TRUE, the program will abort with a panic message. Its code is
+   compiled when either FT_DEBUG_LEVEL_ERROR or FT_DEBUG_LEVEL_TRACE are
+   defined. You don't need double-parentheses here. For example:
+
+     FT_ASSERT( ptr != NULL );
+
+
+ 3. FT_TRACE( level, (message...) )
+
+   the FT_TRACE macro is used to send general-purpose debugging messages
+   during program execution. This macro uses an *implicit* macro named
+   FT_COMPONENT used to name the current FreeType component being run.
+
+   The developer should always define FT_COMPONENT as appropriate, for
+   example as in:
+
+     #undef  FT_COMPONENT
+     #define FT_COMPONENT  trace_io
+
+   the value of the FT_COMPONENT macro is an enumeration named trace_XXXX
+   where XXXX is one of the component names defined in the internal file
+   <freetype/internal/fttrace.h>
+
+   Each such component is assigned a "debug level", ranging from 0 to 6
+   when a program linked with FreeType starts, through the use of the FT2_DEBUG
+   environment variable, described later.
+
+   When FT_TRACE is called, its level is compared to the one of the
+   corresponding component. Messages with trace levels *higher* than the
+   corresponding component level are filtered and never printed.
+
+   this means that trace messages with level 0 are always printed, those
+   with level 2 are only printed when the component level is *at least* 2
+
+   The second parameter to FT_TRACE must contain parentheses and correspond
+   to a print-like call, as in:
+
+     FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) )
+
+   The shortcut macros FT_TRACE0, FT_TRACE1, FT_TRACE2_, ... FT_TRACE6 can
+   be used with constant level indices, and are much cleaner to use, as in
+
+     FT_TRACE2(( "your %s is not %s\n", "foo", "bar" ));
+
+
+III. Environment variables:
+===========================
+
+ The following environment variables control debugging output and behaviour
+ of FreeType at runtime:
+
+
+  FT2_DEBUG
+    this variable is only used when FreeType is built with FT_DEBUG_LEVEL_TRACE
+    defined. It contains a list of component level definitions, following this
+    format:
+
+        component1:level1 component2:level2 component3:level3 ...
+
+    where "componentX" is the name of a tracing component, as defined in
+    "fttrace.h", but without the "trace_" prefix, and "levelX" is the
+    corresponding level to use at runtime.
+
+    "any" is a special component name that will be interpreted as
+    "any/all components". For example, the following definitions
+
+       set FT2_DEBUG=any:2 memory:5 io:4        (on Windows)
+       export FT2_DEBUG="any:2 memory:5 io:4"   (on Linux)
+
+    both stipulate that all components should have level 2, except for the
+    memory and io components which will be set to trace levels 5 and 4
+    respectively.
+
+
+  FT2_DEBUG_MEMORY
+    this environment variable, when defined, tells FreeType to use a debugging
+    memory manager that will track leaked memory blocks as well as other common
+    errors like double frees. It is also capable of reporting _where_ the
+    leaked blocks were allocated, which considerably saves time when
+    debugging new additions to the library.
+
+    This code is only compiled when FreeType is built with the FT_DEBUG_MEMORY
+    macro #defined in "ftoption.h" though, it will be ignored in other builds.
+
+
+Voila,
+
+- David Turner
+
+
+
+    used like printf( format, ... ), but with double quotes. This will
+    send a message to the standard error descriptor (stderr on most systems)
+    in certain builds of the library
\ No newline at end of file
diff --git a/include/freetype/internal/ftdebug.h b/include/freetype/internal/ftdebug.h
index 039b17b..2820ebe 100644
--- a/include/freetype/internal/ftdebug.h
+++ b/include/freetype/internal/ftdebug.h
@@ -13,6 +13,11 @@
 /*  this file you indicate that you have read the license and              */
 /*  understand and accept it fully.                                        */
 /*                                                                         */
+/*                                                                         */
+/*  IMPORTANT: A description of FreeType's debugging support can be        */
+/*             found in "docs/DEBUG.TXT". Read it if you need to use       */
+/*             or understand this code.                                    */
+/*                                                                         */
 /***************************************************************************/
 
 
@@ -47,10 +52,10 @@ FT_BEGIN_HEADER
 
 #define FT_TRACE_DEF( x )  trace_ ## x ,
 
-  /* defining the enumeration */ 
+  /* defining the enumeration */
   typedef enum
   {
-#include FT_INTERNAL_TRACE_H  
+#include FT_INTERNAL_TRACE_H
     trace_count
 
   } FT_Trace;
diff --git a/src/base/ftdebug.c b/src/base/ftdebug.c
index 4c6bcc5..65c823d 100644
--- a/src/base/ftdebug.c
+++ b/src/base/ftdebug.c
@@ -86,7 +86,7 @@
 #define FT_TRACE_DEF(x)  #x ,
 
   static const char*  ft_trace_toggles[trace_count + 1] =
-  { 
+  {
 #include FT_INTERNAL_TRACE_H
     NULL
   };
@@ -98,9 +98,9 @@
   /*                                                                       */
   /* Initialize the tracing sub-system.  This is done by retrieving the    */
   /* value of the "FT2_DEBUG" environment variable.  It must be a list of  */
-  /* toggles, separated by spaces, `;' or `:'.  Example:                   */
+  /* toggles, separated by spaces, `;' or `,'.  Example:                   */
   /*                                                                       */
-  /*    "any=3 memory=6 stream=5"                                          */
+  /*    "any:3 memory:6 stream:5"                                          */
   /*                                                                       */
   /* This will request that all levels be set to 3, except the trace level */
   /* for the memory and stream components which are set to 6 and 5,        */
@@ -116,48 +116,48 @@
   ft_debug_init( void )
   {
     const char*  ft2_debug = getenv( "FT2_DEBUG" );
-    
+
     if ( ft2_debug )
     {
       const char*  p = ft2_debug;
       const char*  q;
-      
+
 
       for ( ; *p; p++ )
       {
         /* skip leading whitespace and separators */
-        if ( *p == ' ' || *p == '\t' || *p == ':' || *p == ';' || *p == '=' )
+        if ( *p == ' ' || *p == '\t' || *p == ',' || *p == ';' || *p == '=' )
           continue;
-          
-        /* read toggle name, followed by '=' */
+
+        /* read toggle name, followed by ':' */
         q = p;
-        while ( *p && *p != '=' )
+        while ( *p && *p != ':' )
           p++;
-          
-        if ( *p == '=' && p > q )
+
+        if ( *p == ':' && p > q )
         {
           int  n, i, len = p - q;
           int  level = -1, found = -1;
-          
+
 
           for ( n = 0; n < trace_count; n++ )
           {
             const char*  toggle = ft_trace_toggles[n];
-            
+
 
             for ( i = 0; i < len; i++ )
             {
               if ( toggle[i] != q[i] )
                 break;
             }
-            
+
             if ( i == len && toggle[i] == 0 )
             {
               found = n;
               break;
             }
           }
-          
+
           /* read level */
           p++;
           if ( *p )
@@ -166,7 +166,7 @@
             if ( level < 0 || level > 6 )
               level = -1;
           }
-          
+
           if ( found >= 0 && level >= 0 )
           {
             if ( found == trace_any )