* include/freetype/freetype.h, include/freetype/ftchapters.h: Add

a preliminary section with some explanations about user allocation.

* src/tools/docmaker/tohtml.py (HtmlFormatter.section_enter):
Don't abort if there are no data types, functions, etc., in a
section.
Print synopsis only if we have a data type, function, etc.

* docs/INSTALL.ANY, docs/INSTALL, docs/INSTALL.UNX, docs/CUSTOMIZE,
docs/INSTALL.GNU, docs/TRUETYPE, docs/DEBUG, docs/UPGRADE.UNX,
docs/VERSION.DLL, docs/formats.txt: Revised, formatted.

1 files changed, 32 insertions, 27 deletions

diff --git a/docs/DEBUG b/docs/DEBUG
index 4e132339..4b0501af 100644
--- a/docs/DEBUG
+++ b/docs/DEBUG
@@ -6,7 +6,7 @@ I. Configuration macros
 
 There  are several ways  to enable  debugging features  in a  FreeType 2
 builds.   This is controlled  through the  definition of  special macros
-located in the file "ftoptions.h".  The macros are:
+located in the file `ftoptions.h'.  The macros are:
 
 
   FT_DEBUG_LEVEL_ERROR
@@ -23,7 +23,7 @@ located in the file "ftoptions.h".  The macros are:
     FT_TRACE2, ..., FT_TRACE7.
 
     The  trace  macros are  used  to  send  debugging messages  when  an
-    appropriate  "debug  level" is  configured  at  runtime through  the
+    appropriate  `debug  level' is  configured  at  runtime through  the
     FT2_DEBUG environment variable (more on this later).
 
   FT_DEBUG_MEMORY
@@ -51,16 +51,17 @@ 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".
+    `ftoption.h'.
 
     Note that you  have to use a printf-like  signature, but with double
-    parentheses, like in:
+    parentheses, like in
 
       FT_ERROR(( "your %s is not %s\n", "foo", "bar" ));
 
@@ -70,31 +71,31 @@ its code:
     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_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:
+    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>.
+    internal file `freetype/internal/fttrace.h'.
 
-    Each  such component  is assigned  a "debug  level", ranging  from 0
-    to 7,  through  the  use   of  the  FT2_DEBUG  environment  variable
+    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.
 
     When FT_TRACE  is called, its  level is compared  to the one  of the
@@ -106,11 +107,11 @@ its code:
     least* 2.
 
     The  second  parameter  to  FT_TRACE must  contain  parentheses  and
-    correspond to a printf-like call, as in:
+    correspond 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
+    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
 
@@ -121,7 +122,8 @@ III. Environment variables
 --------------------------
 
 The  following  environment   variables  control  debugging  output  and
-behaviour of FreeType at runtime:
+behaviour of FreeType at runtime.
+
 
   FT2_DEBUG
 
@@ -131,19 +133,20 @@ behaviour of FreeType at runtime:
 
        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.   "levelX" is  the
+    where `componentX' is the name of a tracing component, as defined in
+    `fttrace.h',  but  without the  `trace_'  prefix.   `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  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 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
-    and 4, respectively.
+    the memory and io components which will be set to trace levels 5 and
+    4, respectively.
+
 
   FT2_DEBUG_MEMORY
 
@@ -154,9 +157,10 @@ behaviour of FreeType at runtime:
     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  will be
     ignored in other builds.
 
+
   FT2_ALLOC_TOTAL_MAX
 
     This  variable is ignored  if FT2_DEBUG_MEMORY  is not  defined.  It
@@ -168,6 +172,7 @@ behaviour of FreeType at runtime:
     If it is  undefined, or if its value is  not strictly positive, then
     no allocation bounds are checked at runtime.
 
+
   FT2_ALLOC_COUNT_MAX
   
     This  variable is ignored  if FT2_DEBUG_MEMORY  is not  defined.  It
@@ -177,17 +182,17 @@ behaviour of FreeType at runtime:
     engine's robustness.
     
     If it is  undefined, or if its value is  not strictly positive, then
-    no allocation bounsd are checked at runtime.
+    no allocation bounds are checked at runtime.
 
 ------------------------------------------------------------------------
 
-Copyright 2002, 2003, 2004 by
+Copyright 2002, 2003, 2004, 2005 by
 David Turner, Robert Wilhelm, and Werner Lemberg.
 
-This  file  is  part  of the  FreeType  project, and may  only be  used,
-modified,  and  distributed  under  the  terms of  the FreeType  project
-license, LICENSE.TXT.   By continuing to use, modify, or distribute this
-file you  indicate that  you have  read the  license and understand  and
+This  file is  part  of the  FreeType  project, and  may  only be  used,
+modified,  and  distributed under  the  terms  of  the FreeType  project
+license, LICENSE.TXT.  By continuing  to use, modify, or distribute this
+file  you indicate that  you have  read the  license and  understand and
 accept it fully.