[freetype2] logging ab0ea06 04/16: Update logging related documentation.

[Werner LEMBERG]

branch: logging
commit ab0ea068ee5acf6a6e1a77d5c315fb8934ce4190
Author: Priyesh Kumar <priyeshkkumar@gmail.com>
Commit: Werner Lemberg <wl@gnu.org>

    Update logging related documentation.
    
    * docs/DEBUG: Updates related to `FT_LOGGING`.
    
    * README.git: Updates related to logging.
---
 ChangeLog  |  8 ++++++
 README.git |  8 ++++++
 docs/DEBUG | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 110 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index 5d6ac07..fb6da40 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,13 @@
 2020-11-30  Priyesh Kumar  <priyeshkkumar@gmail.com>
 
+       Update logging related documentation.
+
+       * docs/DEBUG: Updates related to `FT_LOGGING`.
+
+       * README.git: Updates related to logging.
+
+2020-11-30  Priyesh Kumar  <priyeshkkumar@gmail.com>
+
        * src/*: Fix `-Wformat` warnings.
 
 2020-11-30  Priyesh Kumar  <priyeshkkumar@gmail.com>
diff --git a/README.git b/README.git
index c4f0033..1da3fa8 100644
--- a/README.git
+++ b/README.git
@@ -35,6 +35,14 @@ Similarly, a  build with  `cmake' can  be done  directly 
from  the git
 repository.
 
 
+For using the `FT_LOGGING' macro while debugging (see `docs/DEBUG' for
+more information)  use the  following git  commands to  checkout `dlg'
+library as a git submodule.
+
+  git submodule init
+  git submodule update
+
+
 ----------------------------------------------------------------------
 
 Copyright (C) 2005-2020 by
diff --git a/docs/DEBUG b/docs/DEBUG
index a96b5e2..48bea34 100644
--- a/docs/DEBUG
+++ b/docs/DEBUG
@@ -44,6 +44,21 @@ located in the file `ftoption.h'.  The macros are:
     When `FT2_DEBUG_MEMORY'  isn't defined  at runtime,  the debugging
     memory manager is ignored, and performance is unaffected.
 
+  FT_LOGGING
+
+    #define this macro for enhanced logging support; it automatically
+    sets `FT_DEBUG_LEVEL_TRACE' and `FT_DEBUG_LEVEL_ERROR'.
+
+    If  defined,  `FT_TRACE'  and  `FT_ERROR'  can  send  tracing  and
+    debugging messages to a file.  The location of the log file has to
+    be set  with the  `FT_LOGGING_FILE' environment variable  (more on
+    this later).
+
+    The main enhancements are the  possibility of logging the time and
+    the name  of the `FT_COMPONENT'  macro together with  the affected
+    `FT_TRACE' or `FT_ERROR' calls.  See below how to activate this in
+    the `FT2_DEBUG' environment variable.
+
 
 II. Debugging macros
 --------------------
@@ -150,6 +165,43 @@ behaviour of FreeType at runtime.
     the memory and io components, which  are set to the trace levels 5
     and 4, respectively.
 
+    If `FT_LOGGING' is defined, two more options are available.
+
+    * -v: Print also  the name of FreeType's component  from which the
+          current log is produced.
+
+    * -t: Print also the time.
+
+    Here are some examples how the output might look like.
+
+      FT2_DEBUG="any:7 memory:5 -vt"
+
+        => [20:32:02:44969 ttload]    table directory loaded
+
+      FT2_DEBUG="any:7 memory:5 -t"
+
+        => [20:32:02:44969]    table directory loaded
+
+      FT2_DEBUG="any:7 memory:5 -v"
+
+        => [ttload]    table directory loaded
+
+
+  FT_LOGGING_FILE
+
+    This  variable  is  only  used  if  FreeType  is  built  with  the
+    `FT_LOGGING'  macro defined.   It contains  the path  to the  file
+    where the  user wants  to put  his log  file.  If  it is  not set,
+    FreeType uses stderr.
+
+    Examples:
+
+      On UNIX-like systems with bash:
+      export FT_LOGGING_FILE="/tmp/freetype2.log"
+
+      On Windows:
+      set FT_LOGGING_FILE=C:\Users\AppData\Local\Temp\freetype2.log
+
 
   FT2_DEBUG_MEMORY
 
@@ -201,6 +253,48 @@ behaviour of FreeType at runtime.
     If it  is undefined,  or if  its value  is not  strictly positive,
     freed blocks are released at runtime.
 
+
+IV. Additional Capabilities with `FT_LOGGING'
+---------------------------------------------
+
+If  `FT_LOGGING'  is  defined,  four APIs  are  available  to  provide
+additional debugging support.  Use
+
+  #include<freetype/ftlogging.h>
+
+to access them.
+
+  FT_Trace_Set_Level( const char*  level )
+
+    By  default,  FreeType   uses  the  tracing  levels   set  in  the
+    `FT2_DEBUG' environment  variable.  Use this function  to override
+    the value with `level'.  Use value `NULL' to disable tracing.
+
+  FT_Trace_Set_Default_Level():
+
+    Reset the tracing levels to the default value, i.e., the value of
+    the `FT2_DEBUG' environment variable or no tracing if not set.
+
+  FT_Set_Log_Handler( ft_custom_log_handler  handler ):
+
+    Use `handler' as a custom handler for formatting tracing and error
+    messages.  The  `ft_custom_log_handler' typedef has  the following
+    prototype.
+
+      void
+      (*ft_custom_log_handler)( const char*  ft_component,
+                                const char*  fmt,
+                                va_list      args );
+
+   `ft_component' is the current component like `ttload', `fmt' is the
+   first argument  of `FT_TRACE' or  `FT_ERROR', and `args'  holds the
+   remaining arguments.
+
+  FT_Set_Default_Log_Handler():
+
+    Reset the log handler to the default version.
+
+
 ------------------------------------------------------------------------
 
 Copyright (C) 2002-2020 by