[freetype2] master d355a73: docs/DEBUG: Document environment variable `FT2_KEEP_ALIVE'.

[Werner LEMBERG]

branch: master
commit d355a73aa3821ae83e0e28e0888eb22dd83b2d96
Author: Werner Lemberg <address@hidden>
Commit: Werner Lemberg <address@hidden>

    docs/DEBUG: Document environment variable `FT2_KEEP_ALIVE'.
    
    Also do some formatting and minor edits.
---
 docs/DEBUG | 133 +++++++++++++++++++++++++++++++++----------------------------
 1 file changed, 73 insertions(+), 60 deletions(-)

diff --git a/docs/DEBUG b/docs/DEBUG
index 828f294..36cdf13 100644
--- a/docs/DEBUG
+++ b/docs/DEBUG
@@ -11,20 +11,20 @@ located in the file `ftoption.h'.  The macros are:
 
   FT_DEBUG_LEVEL_ERROR
 
-    #define this macro if you want to compile the FT_ERROR macro calls
-    to print error  messages during program execution.   This will not
-    stop  the  program.  Very  useful  to  spot invalid  fonts  during
+    #define this  macro if  you want to  compile the  `FT_ERROR' macro
+    calls to print error messages during program execution.  This does
+    not stop  the program.  Very  useful to spot invalid  fonts during
     development and to code workarounds for them.
 
   FT_DEBUG_LEVEL_TRACE
 
-    #define this macro if you want to compile both macros FT_ERROR and
-    FT_TRACE.  This  also includes the variants  FT_TRACE0, FT_TRACE1,
-    FT_TRACE2, ..., FT_TRACE7.
+    #define this macro  if you want to compile  both macros `FT_ERROR'
+    and  `FT_TRACE'.  This  also  includes  the variants  `FT_TRACE0',
+    `FT_TRACE1', `FT_TRACE2', ..., `FT_TRACE7'.
 
     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).
+    `FT2_DEBUG' environment variable (more on this later).
 
   FT_DEBUG_MEMORY
 
@@ -32,16 +32,16 @@ located in the file `ftoption.h'.  The macros are:
     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 is 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  the `FT2_DEBUG_MEMORY'  environment variable  is defined  at
+    runtime,  a call  to `FT_Done_FreeType'  dumps memory  statistics,
+    including the list of leaked memory blocks and optionally with the
+    source locations where these were  allocated.  It is 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
+    When `FT2_DEBUG_MEMORY'  isn't defined  at runtime,  the debugging
     memory manager is ignored, and performance is unaffected.
 
 
@@ -55,10 +55,10 @@ 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
+    serious  errors  (like broken  font  files)  without stopping  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'.
+    either   `FT_DEBUG_LEVEL_ERROR'   or  `FT_DEBUG_LEVEL_TRACE'   are
+    defined in `ftoption.h'.
 
     Note that you have to use a printf-like signature, but with double
     parentheses, like in
@@ -69,53 +69,53 @@ debugging its code:
   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
+    condition isn't  TRUE, the  program aborts  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.  Example:
 
       FT_ASSERT( ptr != NULL );
 
 
   3. FT_TRACE( level, (message...) )
 
-    The  FT_TRACE  macro is  used  to  send general-purpose  debugging
+    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
+    macro  named  `FT_COMPONENT',  which names  the  current  FreeType
     component being run.
 
-    The developer  should always  define FT_COMPONENT  as appropriate,
+    The developer should always  define `FT_COMPONENT' as appropriate,
     for example as in
 
       #undef  FT_COMPONENT
       #define FT_COMPONENT  io
 
-    The  value  of the  FT_COMPONENT  macro  is  one  of the component
-    names  defined in the internal  file `internal/fttrace.h'.  If you
-    modify FreeType source and insert new FT_COMPONENT macro, you must
-    register it  in `fttrace.h'.  If  you insert or  remove many trace
-    macros, you can check the undefined or the unused trace  macro  by
-    `src/tools/chktrcmp.py'.
+    The  value of  the `FT_COMPONENT'  macro is  one of  the component
+    names defined  in the internal file  `internal/fttrace.h'.  If you
+    modify the  FreeType source code  and insert a  new `FT_COMPONENT'
+    macro,  you must  register it  in `fttrace.h'.   If you  insert or
+    remove many  trace macros,  you can test  for undefined  or unused
+    trace macros with the script `src/tools/chktrcmp.py'.
 
-    Each such component is assigned a `debug level', ranging from 0 to
-    7,  through   the  use  of  the   FT2_DEBUG  environment  variable
-    (described below) when a program linked with FreeType starts.
+    Each  such component  is assigned  a `debug  level', ranging  from
+    value  0 to  7, through  the  use of  the `FT2_DEBUG'  environment
+    variable  (described below)  when a  program linked  with FreeType
+    starts.
 
-    When FT_TRACE is  called, its level is compared to  the one of the
+    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.
+    the  corresponding  component level  are  filtered  out 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, etc.
 
-    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 printf-like call, as in
+    The second  parameter to  `FT_TRACE' must contain  parentheses and
+    corresponds to a printf-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_TRACE7 can  be used with  constant level indices, and  are much
+    The  shortcut macros  `FT_TRACE0', `FT_TRACE1',  `FT_TRACE2', ...,
+    `FT_TRACE7' 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" ));
@@ -131,7 +131,7 @@ 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
+    `FT_DEBUG_LEVEL_TRACE' defined.   It contains a list  of component
     level definitions, following this format:
 
       component1:level1 component2:level2 component3:level3 ...
@@ -140,53 +140,66 @@ behaviour of FreeType at runtime.
     in `fttrace.h'.  `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
+    `any' is a special component  name that is 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 with bash)
 
     both stipulate that all components should have level 2, except for
-    the memory and  io components which will be set  to trace levels 5
+    the memory and io components, which  are set to the 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 leaking memory blocks as
-    well as other common errors like double frees.  It is also capable
-    of  reporting _where_  the  leaking blocks  were allocated,  which
+    debugging memory manager that tracks leaking memory blocks as well
+    as other common  errors like double frees.  It is  also capable of
+    reporting  _where_  the  leaking   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
+    `FT_DEBUG_MEMORY'  macro #defined  in `ftoption.h'  though, it  is
     ignored in other builds.
 
 
   FT2_ALLOC_TOTAL_MAX
 
-    This variable is  ignored if FT2_DEBUG_MEMORY is  not defined.  It
+    This variable is ignored if `FT2_DEBUG_MEMORY' is not defined.  It
     allows  you  to  specify  a  maximum  heap  size  for  all  memory
     allocations performed  by FreeType.  This  is very useful  to test
     the robustness  of the  font engine  and programs  that use  it in
     tight memory conditions.
 
-    If it is undefined, or if its value is not strictly positive, then
-    no allocation bounds are checked at runtime.
+    If it is  undefined, or if its value is  not strictly positive, no
+    allocation bounds are checked at runtime.
 
 
   FT2_ALLOC_COUNT_MAX
 
-    This variable is  ignored if FT2_DEBUG_MEMORY is  not defined.  It
+    This variable is ignored if `FT2_DEBUG_MEMORY' is not defined.  It
     allows  you to  specify  a maximum  number  of memory  allocations
     performed    by    FreeType    before    returning    the    error
-    FT_Err_Out_Of_Memory.  This  is useful  for debugging  and testing
+    `FT_Err_Out_Of_Memory'.  This is useful  for debugging and testing
     the engine's robustness.
 
-    If it is undefined, or if its value is not strictly positive, then
-    no allocation bounds are checked at runtime.
+    If it is  undefined, or if its value is  not strictly positive, no
+    allocation bounds are checked at runtime.
+
+
+  FT2_KEEP_ALIVE
+
+    This  variable is  ignored if  `FT2_DEBUG_MEMORY' is  not defined.
+    `Keep alive' means that freed  blocks aren't released to the heap.
+    This is  useful to detect  double-frees or weird  heap corruption,
+    reporting the source code location  of the original allocation and
+    deallocation  in case  of a  problem.   It uses  large amounts  of
+    memory, however.
+
+    If it  is undefined,  or if  its value  is not  strictly positive,
+    freed blocks are released at runtime.
 
 ------------------------------------------------------------------------