* 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.

14 files changed, 327 insertions, 244 deletions

diff --git a/ChangeLog b/ChangeLog
index f1321a62c..f3d4c91a5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2005-08-29  Werner Lemberg  <wl@gnu.org>
+
+	* 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.
+
 2005-08-28  George Williams  <gww@silcom.com>
 
 	* src/truetype/ttgload.c [TT_MAX_COMPOSITE_RECURSE]: Removed.
diff --git a/docs/CUSTOMIZE b/docs/CUSTOMIZE
index e2beb6891..e1b3c065e 100644
--- a/docs/CUSTOMIZE
+++ b/docs/CUSTOMIZE
@@ -1,5 +1,5 @@
-How to customize the compilation of the library:
-================================================
+How to customize the compilation of the library
+===============================================
 
   FreeType  is  highly  customizable  to  fit various  needs,  and  this
   document describes how it is possible to select options and components
@@ -8,7 +8,7 @@ How to customize the compilation of the library:
 
 I. Configuration macros
 
-  The file found in "include/freetype/config/ftoption.h" contains a list
+  The file found in `include/freetype/config/ftoption.h' contains a list
   of commented configuration macros that can be toggled by developers to
   indicate which features should be active while building the library.
   
@@ -22,23 +22,28 @@ I. Configuration macros
   
 II. Modules list
 
-  The file found in "include/freetype/config/ftmodule.h" contains a list
+  The file found in `include/freetype/config/ftmodule.h' contains a list
   of  names  corresponding  to  the  modules  and  font  drivers  to  be
   statically compiled in the FreeType library during the build.
 
   You can change it to suit your own preferences.  Be aware that certain
-  modules depend  on others, as  described by the file  "modules.txt" in
+  modules depend  on others, as  described by the file  `modules.txt' in
   this directory.
 
   You can modify  the file's content to suit your  needs, or override it
   at compile time with one of the methods described below.
 
+  Note that  you also  have to  rename the various  `*.mk' files  in the
+  module directories  which you  want to exclude  so that  the extension
+  isn't `.mk'  -- GNU make uses  a simple globbing  mechanism to include
+  all those files.
+
 
 III. System interface
 
   FreeType's default interface to the  system (i.e., the parts that deal
   with   memory   management   and    i/o   streams)   is   located   in
-  "src/base/ftsystem.c".
+  `src/base/ftsystem.c'.
   
   The  current implementation uses  standard C  library calls  to manage
   memory and to read font files.  It is however possible to write custom
@@ -74,32 +79,32 @@ IV. Overriding default configuration and module headers
     Use the C include path to ensure that your own versions of the files
     are used at compile time when the lines
     
-       #include FT_CONFIG_OPTIONS_H
-       #include FT_CONFIG_MODULES_H
+      #include FT_CONFIG_OPTIONS_H
+      #include FT_CONFIG_MODULES_H
 
     are       compiled.       Their      default       values      being
     <freetype/config/ftoption.h>  and  <freetype/config/ftmodule.h>, you
     can do something like:
 
-       custom/
-         freetype/
-           config/
-             ftoption.h    => custom options header
-             ftmodule.h    => custom modules list
+      custom/
+        freetype/
+          config/
+            ftoption.h    => custom options header
+            ftmodule.h    => custom modules list
              
-       include/            => normal FreeType 2 include
-         freetype/
-           ...
+      include/            => normal FreeType 2 include
+        freetype/
+          ...
 
-    then change the  C include path to always give  the path to "custom"
-    before the FreeType 2 "include".
+    then change the  C include path to always give  the path to `custom'
+    before the FreeType 2 `include'.
 
 
-  2. Re-defining FT_CONFIG_OPTIONS_H and FT_CONFIG_MODULES_H
+  2. Redefining FT_CONFIG_OPTIONS_H and FT_CONFIG_MODULES_H
   
     Another way to  do the same thing is to redefine  the macros used to
     name  the  configuration headers.   To  do  so,  you need  a  custom
-    "ft2build.h" whose content can be as simple as:
+    `ft2build.h' whose content can be as simple as:
    
       #ifndef __FT2_BUILD_MY_PLATFORM_H__
       #define __FT2_BUILD_MY_PLATFORM_H__
@@ -111,25 +116,25 @@ IV. Overriding default configuration and module headers
 
       #endif /* __FT2_BUILD_MY_PLATFORM_H__ */
    
-    Place those files in a separate directory, e.g.:
+    Place those files in a separate directory, e.g.,
    
       custom/
         ft2build.h           => custom version described above
         my-ftoption.h        => custom options header
         my-ftmodule.h        => custom modules list header
 
-    and  change the C  include path  to ensure  that "custom"  is always
-    placed before the FT2 "include" during compilation.
+    and  change the C  include path  to ensure  that `custom'  is always
+    placed before the FT2 `include' during compilation.
 
 ------------------------------------------------------------------------
 
-Copyright 2003 by
+Copyright 2003, 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.
 
 
diff --git a/docs/DEBUG b/docs/DEBUG
index 4e1323391..4b0501aff 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.
 
 
diff --git a/docs/INSTALL b/docs/INSTALL
index b342d96de..d53cafafc 100644
--- a/docs/INSTALL
+++ b/docs/INSTALL
@@ -10,41 +10,46 @@ I. Normal installation and upgrades
   1. Native TrueType Hinting
 
     Native TrueType  hinting is disabled  by default[1].  If  you really
-    need it, read the file "TRUETYPE" for information.
+    need it, read the file `TRUETYPE' for information.
+
 
   2. Unix Systems (as well as Cygwin or MSys on Windows)
 
-    Please read *both* UPGRADE.UNX and INSTALL.UNX to install or upgrade
-    FreeType 2  on a Unix system.   Note that you *will*  need GNU Make,
+    Please  read *both*  `UPGRADE.UNX' and  `INSTALL.UNX' to  install or
+    upgrade FreeType 2 on a Unix system.  Note that you *need* GNU Make,
     since other make tools won't work (this includes BSD Make).
 
-  3. On VMS with the "mms" build tool
+
+  3. On VMS with the `mms' build tool
   
-    See INSTALL.VMS for installation instructions on this platform.
+    See `INSTALL.VMS' for installation instructions on this platform.
+
 
   4. Other systems using GNU Make
   
     On non-Unix platforms, it is possible to build the library using GNU
-    Make utility.   Note that  *NO OTHER MAKE  TOOL WILL  WORK*[2]! This
+    Make utility.   Note that *NO  OTHER MAKE TOOL WILL  WORK*[2]!  This
     methods  supports  several compilers  on  Windows,  OS/2, and  BeOS,
-    including Mingw, Visual C++, Borland C++, and more.
+    including MinGW, Visual C++, Borland C++, and more.
+
+    Instructions are provided in the file `INSTALL.GNU'.
 
-    Instructions are provided in the file "INSTALL.GNU".
 
-  5. With an IDE Project File (e.g. for Visual Studio or CodeWarrior)
+  5. With an IDE Project File (e.g., for Visual Studio or CodeWarrior)
   
-    We provide  a small  number of "project  files" for various  IDEs to
+    We provide  a small  number of `project  files' for various  IDEs to
     automatically build the library as  well.  Note that these files are
-    not supported and sporadically maintained by FreeType developers, so
-    don't expect them to work in each release.
+    not   supported  and  only   sporadically  maintained   by  FreeType
+    developers, so don't expect them to work in each release.
     
-    To find  them, have a look  at the content  of the "builds/<system>"
+    To find  them, have a look  at the content  of the `builds/<system>'
     directory, where <system> stands for your OS or environment.
 
+
   6. From you own IDE, or own Makefiles
   
     If you want to create your own project file, follow the instructions
-    given in the "INSTALL.ANY" document of this directory.
+    given in the `INSTALL.ANY' document of this directory.
 
 
 II. Custom builds of the library
@@ -52,7 +57,7 @@ II. Custom builds of the library
 
   Customizing the  compilation of  FreeType is easy,  and allows  you to
   select only  the components of the  font engine that  you really need.
-  For more details read the file "CUSTOMIZE".
+  For more details read the file `CUSTOMIZE'.
 
 
 ------------------------------------------------------------------------
@@ -60,19 +65,22 @@ II. Custom builds of the library
 [1] More details on:  http://www.freetype.org/patents.html
 
 [2] make++, a  make tool written in Perl, has  sufficient support of GNU
-    make       extensions       to       build      FreeType.        See
-    http://makepp.sourceforge.net for more information; you need version
-    1.19 or newer, and you must pass option `--norc-substitution'.
+    make extensions to build FreeType.  See
+
+      http://makepp.sourceforge.net
+
+    for more information;  you need version 1.19 or  newer, and you must
+    pass option `--norc-substitution'.
 
 ------------------------------------------------------------------------
 
 Copyright 2000, 2001, 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.
 
 
diff --git a/docs/INSTALL.ANY b/docs/INSTALL.ANY
index 4045b2fa9..75e701a0c 100644
--- a/docs/INSTALL.ANY
+++ b/docs/INSTALL.ANY
@@ -1,26 +1,26 @@
 Instructions on how to build FreeType with your own build tool
 ==============================================================
 
-See  the  file `CUSTOMIZE'  to  learn  how  to customize  FreeType  to
-specific environments.
+See the file `CUSTOMIZE' to  learn how to customize FreeType to specific
+environments.
 
 
 I. Standard procedure
 ---------------------
 
-  * DISABLE PRE-COMPILED  HEADERS!  This is very  important for Visual
+  * DISABLE  PRE-COMPILED HEADERS!   This is  very important  for Visual
     C++, because FreeType uses lines like:
     
       #include FT_FREETYPE_H
     
-    which are not correctly supported by this compiler while being ISO
-    C compliant!
+    which are not correctly supported by this compiler while being ISO C
+    compliant!
 
-  * You  need  to  add  the directories  `freetype2/include'  to  your
-    include path when compiling the library.
+  * You need to add  the directories `freetype2/include' to your include
+    path when compiling the library.
 
-  * FreeType 2 is made of  several components; each of them is located
-    in    a   subdirectory    of   `freetype2/src'.     For   example,
+  * FreeType 2 is made of several components; each of them is located in
+    a     subdirectory     of     `freetype2/src'.      For     example,
     `freetype2/src/truetype/' contains the TrueType font driver.
 
   * DO NOT COMPILE ALL C FILES!  Rather, compile the following ones:
@@ -85,14 +85,17 @@ I. Standard procedure
       `type42.c'   needs `truetype.c'
 
 
-  You are done.  In case of problems, see the archives of the FreeType
+  Read the file `CUSTOMIZE' in case you want to compile only a subset of
+  the drivers, renderers, and optional modules.
+
+  You are done.   In case of problems, see the  archives of the FreeType
   development mailing list.
 
 
 II. Support for flat-directory compilation
 ------------------------------------------
 
-  It is  possible to  put all  FreeType 2 source  files into  a single
+  It  is possible  to put  all  FreeType 2  source files  into a  single
   directory, with the *exception* of the `include' hierarchy.
 
   1. Copy all files in current directory
@@ -110,19 +113,19 @@ II. Support for flat-directory compilation
       cc -c -Ifreetype2/include ftbase.c
       etc.
 
-    You don't  need to define  the FT_FLAT_COMPILATION macro  (as this
-    was required in previous releases of FreeType 2).
+    You don't need to define  the FT_FLAT_COMPILATION macro (as this was
+    required in previous releases of FreeType 2).
 
-----------------------------------------------------------------------
+------------------------------------------------------------------------
 
 Copyright 2003, 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 accept it fully.
+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.
 
 
 --- end of INSTALL.ANY ---
diff --git a/docs/INSTALL.GNU b/docs/INSTALL.GNU
index cd2208ec5..096b4b5f6 100644
--- a/docs/INSTALL.GNU
+++ b/docs/INSTALL.GNU
@@ -11,20 +11,22 @@ the file INSTALL.UNX instead.
   1. Install GNU Make
   -------------------
 
-    Because  GNU  Make  is  the  only Make  tool  supported  to  compile
-    FreeType 2, you should install it on your machine.
+    Because GNU Make is the only Make tool supported to compile FreeType
+    2, you should install it on your machine.
 
     The FreeType 2  build system relies on many  features special to GNU
-    Make --  trying to build the  library with any other  Make tool will
-    *fail*.
+    Make.
 
-    NEARLY  ALL OTHER  MAKE TOOLS  WILL FAIL,  INCLUDING "BSD  MAKE", SO
-    REALLY INSTALL A RECENT VERSION OF GNU MAKE ON YOUR SYSTEM!
+    NEARLY ALL  OTHER MAKE TOOLS  FAIL, INCLUDING `BSD MAKE',  SO REALLY
+    INSTALL A RECENT VERSION OF GNU MAKE ON YOUR SYSTEM!
 
     Note  that make++,  a make  tool  written in  Perl, supports  enough
-    features    of    GNU     make    to    compile    FreeType.     See
-    http://makepp.sourceforge.net for more information; you need version
-    1.19 or newer, and you must pass option `--norc-substitution'.
+    features of GNU make to compile FreeType.  See
+    
+      http://makepp.sourceforge.net
+
+    for more information;  you need version 1.19 or  newer, and you must
+    pass option `--norc-substitution'.
 
     Make sure that  you are invoking GNU Make from  the command line, by
     typing something like:
@@ -36,7 +38,7 @@ the file INSTALL.UNX instead.
     VERSION 3.78.1 OR NEWER IS NEEDED!
 
 
-  2. Invoke 'make'
+  2. Invoke `make'
   ----------------
 
     Go to the root directory of  FreeType 2, then simply invoke GNU Make
@@ -59,13 +61,15 @@ the file INSTALL.UNX instead.
       remove the file 'config.mk' from this directory then read the
       INSTALL file for help.
 
-      Otherwise, simply type 'make' again to build the library.
+      Otherwise, simply type 'make' again to build the library
+      or 'make refdoc' to build the API reference (the latter needs
+      python).
       =============================================================
 
 
     If the  detected settings correspond to your  platform and compiler,
     skip to step  5.  Note that if your platform  is completely alien to
-    the build system, the detected platform will be 'ansi'.
+    the build system, the detected platform will be `ansi'.
 
 
   3. Configure the build system for a different compiler
@@ -90,9 +94,9 @@ the file INSTALL.UNX instead.
 
     The  <compiler> name  to  use is  platform-dependent.   The list  of
     available  compilers  for  your  system  is available  in  the  file
-    `builds/<system>/detect.mk'
+    `builds/<system>/detect.mk'.
 
-    If  you are  satisfied by  the  new configuration  summary, skip  to
+    If you  are satisfied  by the new  configuration summary,  skip to
     step 5.
 
 
@@ -131,20 +135,20 @@ the file INSTALL.UNX instead.
   Final note
   
     The  build system  builds a  statically linked  library of  the font
-    engine in the "objs" directory.   It does _not_ support the build of
+    engine in the `objs' directory.   It does _not_ support the build of
     DLLs on Windows and OS/2.  If you need these, you have to either use
-    a  IDE-specific   project  file,  or  follow   the  instructions  in
-    "INSTALL.ANY" to create your own Makefiles.
+    an  IDE-specific  project  file,   or  follow  the  instructions  in
+    `INSTALL.ANY' to create your own Makefiles.
 
 ------------------------------------------------------------------------
 
-Copyright 2003, 2004 by
+Copyright 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.
 
 
diff --git a/docs/INSTALL.UNX b/docs/INSTALL.UNX
index 52f282025..f6deea8c7 100644
--- a/docs/INSTALL.UNX
+++ b/docs/INSTALL.UNX
@@ -1,5 +1,5 @@
 This document contains instructions on how to build the FreeType library
-on Unix systems.  This also works for emulations like  Cygwin or MSys on
+on Unix systems.  This also works  for emulations like Cygwin or MSys on
 Win32:
 
 
@@ -12,8 +12,11 @@ Win32:
 
     [Well, this is not  really correct.  Recently, a perl implementation
     of make called `makepp' has appeared which can also build FreeType 2
-    successfully  on Unix platforms.   See http://makepp.sourceforge.net
-    for more details; you need version 1.19 or newer,  and you must pass
+    successfully on Unix platforms.  See
+
+      http://makepp.sourceforge.net
+
+    for more details; you need version  1.19 or newer, and you must pass
     option `--norc-substitution'.]
 
     Trying to compile the library  with a different Make tool will print
@@ -36,7 +39,7 @@ Win32:
       make
       make install           (as root)
 
-    The default  installation path is  "/usr/local".  It can  be changed
+    The default  installation path is  `/usr/local'.  It can  be changed
     with the `--prefix=<path>' option.  Example:
 
       ./configure --prefix=/usr
@@ -49,8 +52,8 @@ Win32:
        gmake
        gmake install            (as root)
 
-    If  this  still  doesn't   work,  something's rotten on your system
-    (e.g. you are using a very old version of GNU Make).
+    If this still doesn't work, there must be a problem with your system
+    (e.g., you are using a very old version of GNU Make).
 
     It  is  possible  to  compile  FreeType in  a  different  directory.
     Assuming the  FreeType source  files in directory  `/src/freetype' a
@@ -63,13 +66,13 @@ Win32:
 
 ------------------------------------------------------------------------
 
-Copyright 2003, 2004 by
+Copyright 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.
 
 
diff --git a/docs/TRUETYPE b/docs/TRUETYPE
index 30029f4d2..27bfd443c 100644
--- a/docs/TRUETYPE
+++ b/docs/TRUETYPE
@@ -1,20 +1,23 @@
 How to enable the TrueType native hinter if you need it
---------------------------------------------------------
+-------------------------------------------------------
 
   The TrueType  bytecode interpreter is disabled in  all public releases
-  of    the    FreeType    packages    for    patents    reasons    (see
-  http://www.freetype.org/patents.html for more details).
+  of the FreeType packages for patents reasons; see
+
+    http://www.freetype.org/patents.html
+
+  for more details.
 
   However,  many Linux distributions  do enable  the interpreter  in the
   FreeType packages (DEB/RPM/etc.) they produce for their platforms.  If
   you are using TrueType fonts on your system, you most probably want to
   enable it manually by doing the following:
 
-    - open the file "include/freetype/config/ftoption.h"
+    - open the file `include/freetype/config/ftoption.h'
 
     - locate a line that says:
 
-          #undef TT_CONFIG_OPTION_BYTECODE_INTERPRETER
+        #undef TT_CONFIG_OPTION_BYTECODE_INTERPRETER
 
     - change it to:
 
@@ -24,13 +27,13 @@ How to enable the TrueType native hinter if you need it
 
 ------------------------------------------------------------------------
 
-Copyright 2003 by
+Copyright 2003, 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.
 
 
diff --git a/docs/UPGRADE.UNX b/docs/UPGRADE.UNX
index 6c273d4ef..de1b35b32 100644
--- a/docs/UPGRADE.UNX
+++ b/docs/UPGRADE.UNX
@@ -10,7 +10,7 @@ SPECIAL NOTE FOR UNIX USERS
   1. Enable the TrueType bytecode hinter if you need it
   -----------------------------------------------------
 
-    See the instructions in the file "TRUETYPE" of this directory.
+    See the instructions in the file `TRUETYPE' of this directory.
    
     Note  that FreeType  supports  TrueType fonts  without the  bytecode
     interpreter through its  auto-hinter, which now generates relatively
@@ -20,9 +20,9 @@ SPECIAL NOTE FOR UNIX USERS
   2. Determine the correct installation path
   ------------------------------------------
 
-    By  default,  the  configure  script  will install  the  library  in
-    "/usr/local".   However,  many Unix  distributions  now install  the
-    library  in "/usr",  since FreeType  is becoming  a  critical system
+    By   default,  the   configure  script   installs  the   library  in
+    `/usr/local'.   However,  many Unix  distributions  now install  the
+    library  in `/usr',  since FreeType  is becoming  a  critical system
     component.
 
     If FreeType is already installed on your system, type
@@ -30,11 +30,11 @@ SPECIAL NOTE FOR UNIX USERS
       freetype-config --prefix
 
     on  the command  line.   This should  return  the installation  path
-    (e.g.,  "/usr"  or "/usr/local").   To  avoid  problems of  parallel
+    (e.g.,  `/usr'  or `/usr/local').   To  avoid  problems of  parallel
     FreeType  versions, use  this path  for the  --prefix option  of the
     configure script.
 
-    Otherwise, simply use "/usr" (or  whatever you think is adequate for
+    Otherwise, simply use `/usr' (or  whatever you think is adequate for
     your installation).
 
 
@@ -47,14 +47,13 @@ SPECIAL NOTE FOR UNIX USERS
     the library with the  instructions below using any other alternative
     (including BSD Make).
 
-    Trying to compile the library  with a different Make tool will print
-    a message like:
+    Trying to  compile the library with  a different Make  tool prints a
+    message like:
 
       Sorry, GNU make is required to build FreeType2.
 
-    and the build process will be aborted.  If this happens, install GNU
-    Make on  your system,  and use the  GNUMAKE environment  variable to
-    name it.
+    and the build process is aborted.  If this happens, install GNU Make
+    on your system, and use the GNUMAKE environment variable to name it.
 
 
   4. Build and install the library
@@ -67,24 +66,24 @@ SPECIAL NOTE FOR UNIX USERS
       make
       make install           (as root)
 
-    where "<yourprefix>" must be replaced  by the prefix returned by the
-    "freetype-config" command.
+    where `<yourprefix>' must be replaced  by the prefix returned by the
+    `freetype-config' command.
 
     When using a  different command to invoke GNU  Make, use the GNUMAKE
     variable.  For  example, if  `gmake' is the  command to use  on your
     system, do something like:
 
-       GNUMAKE=gmake ./configure --prefix=<yourprefix>
-       gmake
-       gmake install            (as root)
+      GNUMAKE=gmake ./configure --prefix=<yourprefix>
+      gmake
+      gmake install            (as root)
 
 
   5. Take care of XFree86 version 4
   ---------------------------------
 
-    Certain recent  Linux distributions will  install _several_ versions
-    of FreeType  on your system.  For  example, on a  fresh Mandrake 8.1
-    system, you can find the following files:
+    Certain Linux  distributions install _several_  versions of FreeType
+    on your  system.  For example, on  a fresh Mandrake  8.1 system, you
+    can find the following files:
 
       /usr/lib/libfreetype.so             which links to
       /usr/lib/libfreetype.6.1.0.so
@@ -97,16 +96,16 @@ SPECIAL NOTE FOR UNIX USERS
     Note that  these files  correspond to two  distinct versions  of the
     library!  It seems that this  surprising issue is due to the install
     scripts of  recent XFree86 servers (from 4.1.0)  which install their
-    own (dated) version of the library in "/usr/X11R6/lib".
+    own (dated) version of the library in `/usr/X11R6/lib'.
 
     In certain  _rare_ cases  you may experience  minor problems  if you
-    install this  release of  the library in  "/usr" only,  namely, that
-    certain  applications  will  not  benefit  from the  bug  fixes  and
-    rendering improvements you would expect.
+    install this  release of  the library in  `/usr' only,  namely, that
+    certain applications do not benefit from the bug fixes and rendering
+    improvements you would expect.
 
     There are two good ways to deal with this situation:
 
-      - Install the library _twice_,  in "/usr" and in "/usr/X11R6" (you
+      - Install the library _twice_,  in `/usr' and in `/usr/X11R6' (you
         have to  do that  each time you  install a new  FreeType release
         though).
 
@@ -125,13 +124,13 @@ SPECIAL NOTE FOR UNIX USERS
 
 ------------------------------------------------------------------------
 
-Copyright 2003 by
+Copyright 2003, 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.
 
 
diff --git a/docs/VERSION.DLL b/docs/VERSION.DLL
index f7cf88c02..b880ffc6b 100644
--- a/docs/VERSION.DLL
+++ b/docs/VERSION.DLL
@@ -1,4 +1,4 @@
-Due  to our  use of  "libtool" to  generate and  install the  FreeType 2
+Due  to our  use of  `libtool' to  generate and  install the  FreeType 2
 libraries on  Unix systems,  as well as  other historical events,  it is
 generally very  difficult to  know precisely which  release of  the font
 engine is installed on a given system.
@@ -7,19 +7,19 @@ This file tries  to explain why and to document  ways to properly detect
 FreeType on Unix.
 
 
-1. Version & Release numbers
-----------------------------
+1. Version and Release numbers
+------------------------------
 
 For each new  public release of FreeType 2,  there are generally *three*
-distinct "version" numbers to consider:
+distinct `version' numbers to consider:
 
   * The official FT2 release number, like 2.0.9, or 2.1.3.
 
-  * The libtool (and Unix)  specific version number, like "9.2.3".  This
-    is what "freetype-config --version" will return.
+  * The libtool (and Unix) specific version number, like 9.2.3.  This is
+    what `freetype-config --version' returns.
 
   * The platform-specific  shared object  number, used for  example when
-    the library is installed as "/usr/lib/libfreetype.so.6.3.2".
+    the library is installed as `/usr/lib/libfreetype.so.6.3.2'.
 
 The platform-specific  number is, unsurprisingly,  platform-specific and
 varies  with the  operating system  you are  using (several  variants of
@@ -32,14 +32,14 @@ tied to it.
 The release number is available  at *compile* time through the following
 macros defined in FT_FREETYPE_H:
 
-  - FREETYPE_MAJOR : major release number
-  - FREETYPE_MINOR : minor release number
-  - FREETYPE_PATCH : patch release number
+  - FREETYPE_MAJOR: major release number
+  - FREETYPE_MINOR: minor release number
+  - FREETYPE_PATCH: patch release number
 
 See below for a small autoconf fragment.
 
 The  release   number  is  also  available  at   *runtime*  through  the
-"FT_Library_Version" API.   Unfortunately, this one  wasn't available or
+`FT_Library_Version' API.   Unfortunately, this one  wasn't available or
 working correctly before the 2.1.3 official release.
 
 
@@ -50,6 +50,7 @@ The following table gives,  for each official release, the corresponding
 libtool  number, as well  as the  shared object  number found  on _most_
 systems, but not all of them:
 
+
     release    libtool      so
   -------------------------------
      2.2.0      9.9.3     6.3.9
@@ -74,10 +75,10 @@ The libtool numbers are a bit inconsistent due to the library's history:
   - 2.1.0 was created as a development branch from 2.0.8 (hence the same
     libtool numbers).
 
-  - 2.0.9  was  a  bug-fix  release  of  the  "stable"  branch,  and  we
+  - 2.0.9  was  a  bug-fix  release  of  the  `stable'  branch,  and  we
     incorrectly increased its libtool number.
 
-  - 2.1.4 is  still in  the "development" branch,  however it  is stable
+  - 2.1.4 is  still in  the `development' branch,  however it  is stable
     enough to be the basis of an upcoming 2.2.0 release.
 
 
@@ -86,7 +87,7 @@ The libtool numbers are a bit inconsistent due to the library's history:
 
 Lars Clausen contributed the following autoconf fragment to detect which
 version of  FreeType is  installed on  a system.  This  one tests  for a
-version that  is at least 2.0.9;  you should change  it to check against
+version that  is at least 2.0.9;  you should change it  to check against
 other release numbers.
 
 
@@ -113,10 +114,10 @@ other release numbers.
 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.
 
 
diff --git a/docs/formats.txt b/docs/formats.txt
index 332af0a89..2f7c3d94e 100644
--- a/docs/formats.txt
+++ b/docs/formats.txt
@@ -1,46 +1,46 @@
-This file contains a list of various font formats.  It gives the
+This  file  contains a  list  of various  font  formats.   It gives  the
 reference document and whether it is supported in FreeType 2.
 
 
   file type:
-    The only special case is `MAC'; on older Mac OS versions, a `file'
-    is stored as a data and a resource fork, this is, within two
-    separate data chunks.  In all other cases, the font data is stored
+    The only special  case is `MAC'; on older Mac  OS versions, a `file'
+    is  stored as  a  data and  a  resource fork,  this  is, within  two
+    separate data chunks.   In all other cases, the  font data is stored
     in a single file.
 
   wrapper format:
-    The format used to represent the font data.  In the table below it
-    is used only if the font format differs.  Possible values are
-    `SFNT' (binary), `PS' (a text header, followed by binary or text
-    data), and `LZW' (compressed with either `gzip' or `compress').
+    The format used  to represent the font data.  In  the table below it
+    is used only if the font format differs.  Possible values are `SFNT'
+    (binary), `PS' (a text header, followed by binary or text data), and
+    `LZW' (compressed with either `gzip' or `compress').
 
   font format:
-    How the font is to be accessed, possibly after converting the file
-    type and wrapper format into a generic form.  Bitmap formats are
-    `BDF', `PCF', and one form of `WINFNT'; all others are vector
+    How the font  is to be accessed, possibly  after converting the file
+    type and  wrapper format  into a generic  form.  Bitmap  formats are
+    `BDF',  `PCF', and  one  form  of `WINFNT';  all  others are  vector
     formats.
 
   font type:
-    Sub-formats of the font format.  `SBIT' and `MACSBIT' are bitmap
+    Sub-formats  of the font  format.  `SBIT'  and `MACSBIT'  are bitmap
     formats, `MM' and `VAR' support optical axes.
 
   glyph access:
-    If not specified, the glyph access is `standard' to the font
-    format.  Values are `CID' for CID-keyed fonts, `SYNTHETIC' for
-    fonts which are modified versions of other fonts by means of a
-    transformation matrix, `COLLECTION' for collecting multiple fonts
-    (sharing most of the data) into a single file, and `TYPE_0' for PS
-    fonts which are to be accessed in a tree-like structure.
+    If not specified, the glyph access is `standard' to the font format.
+    Values are  `CID' for CID-keyed  fonts, `SYNTHETIC' for  fonts which
+    are modified  versions of other  fonts by means of  a transformation
+    matrix, `COLLECTION' for collecting  multiple fonts (sharing most of
+    the data) into a single file, and `TYPE_0' for PS fonts which are to
+    be accessed in a tree-like structure.
 
   FreeType driver:
-    The module in the FreeType library which handles the specific font
-    format.  A missing entry means that FreeType doesn't support the
+    The module in  the FreeType library which handles  the specific font
+    format.   A missing entry  means that  FreeType doesn't  support the
     font format (yet).
 
 
-Please send additions and/or corrections to wl@gnu.org or to the
-FreeType developer's list at freetype-devel@nongnu.org (for subscribers
-only).  If you can provide a font example for a format which isn't
+Please  send  additions  and/or  corrections  to wl@gnu.org  or  to  the
+FreeType developer's list  at freetype-devel@nongnu.org (for subscribers
+only).   If you  can provide  a font  example for  a format  which isn't
 supported yet please send a mail too.
 
 
@@ -122,16 +122,17 @@ MAC  ---     PS     TYPE_1  ---        type1    T1_SPEC.pdf
 ---  ---     WINFNT VECTOR  ---        ---      MS Windows 3 Developer's Notes
 
 
-[1] Support should be rather simple since this is identical to `CFF'
-    but in a PS wrapper.
+[1] Support should be rather simple since this is identical to `CFF' but
+    in a PS wrapper.
 
 [2] Official PFR specification:
 
       http://www.bitstream.com/categories/developer/truedoc/pfrspec.html
       http://www.bitstream.com/categories/developer/truedoc/pfrspec1.2.pdf
 
-    The syntax of the auxiliary data is not defined there, but is partially
-    defined in MHP 1.0.3 (also called ETSI TS 101812 V1.3.1) section 7.4.
+    The  syntax of  the  auxiliary data  is  not defined  there, but  is
+    partially defined in  MHP 1.0.3 (also called ETSI  TS 101812 V1.3.1)
+    section 7.4.
 
       http://www.etsi.org/
       http://webapp.etsi.org/workprogram/Report_WorkItem.asp?WKI_ID=18799
@@ -143,10 +144,10 @@ MAC  ---     PS     TYPE_1  ---        type1    T1_SPEC.pdf
 Copyright 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.
 
 
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index 345d4fb81..7976b4fb2 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -57,6 +57,26 @@ FT_BEGIN_HEADER
 
 
   /*************************************************************************/
+  /*                                                                       */
+  /* <Section>                                                             */
+  /*    user_allocation                                                    */
+  /*                                                                       */
+  /* <Title>                                                               */
+  /*    User allocation                                                    */
+  /*                                                                       */
+  /* <Abstract>                                                            */
+  /*    How client applications should allocate FreeType data structures.  */
+  /*                                                                       */
+  /* <Description>                                                         */
+  /*    FreeType assumes that structures allocated by the user and passed  */
+  /*    as arguments are zeroed out except for the actual data.  With      */
+  /*    other words, it is recommended to use `calloc' (or variants of it) */
+  /*    instead of `malloc' for allocation.                                */
+  /*                                                                       */
+  /*************************************************************************/
+
+
+  /*************************************************************************/
   /*************************************************************************/
   /*                                                                       */
   /*                        B A S I C   T Y P E S                          */
diff --git a/include/freetype/ftchapters.h b/include/freetype/ftchapters.h
index 0d2f87bf3..9fd25a376 100644
--- a/include/freetype/ftchapters.h
+++ b/include/freetype/ftchapters.h
@@ -9,6 +9,20 @@
 /***************************************************************************/
 /*                                                                         */
 /* <Chapter>                                                               */
+/*    general_remarks                                                      */
+/*                                                                         */
+/* <Title>                                                                 */
+/*    General Remarks                                                      */
+/*                                                                         */
+/* <Sections>                                                              */
+/*    user_allocation                                                      */
+/*                                                                         */
+/***************************************************************************/
+
+
+/***************************************************************************/
+/*                                                                         */
+/* <Chapter>                                                               */
 /*    core_api                                                             */
 /*                                                                         */
 /* <Title>                                                                 */
@@ -24,6 +38,7 @@
 /*                                                                         */
 /***************************************************************************/
 
+
 /***************************************************************************/
 /*                                                                         */
 /* <Chapter>                                                               */
diff --git a/src/tools/docmaker/tohtml.py b/src/tools/docmaker/tohtml.py
index 2a3cf239b..2b9c547d9 100644
--- a/src/tools/docmaker/tohtml.py
+++ b/src/tools/docmaker/tohtml.py
@@ -410,37 +410,39 @@ class HtmlFormatter(Formatter):
         print section.title
         print section_title_footer
 
-        # print section synopsys
-        print section_synopsis_header
-        print "<table align=center cellspacing=5 cellpadding=0 border=0>"
-
         maxwidth = 0
         for b in section.blocks.values():
-            if len(b.name) > maxwidth:
-                maxwidth = len(b.name)
+            if len( b.name ) > maxwidth:
+                maxwidth = len( b.name )
 
         width  = 70  # XXX magic number
-        columns = width / maxwidth
-        if columns < 1:
-            columns = 1
-
-        count   = len(section.block_names)
-        rows    = (count + columns-1)/columns
-        for r in range(rows):
-            line = "<tr>"
-            for c in range(columns):
-                i = r + c*rows
-                line = line + '<td></td><td>'
-                if i < count:
-                    name = section.block_names[i]
-                    line = line + '<a href="#' + name + '">' + name + '</a>'
-
-                line = line + '</td>'
-            line = line + "</tr>"
-            print line
-
-        print "</table><br><br>"
-        print section_synopsis_footer
+        if maxwidth <> 0:
+            # print section synopsis
+            print section_synopsis_header
+            print "<table align=center cellspacing=5 cellpadding=0 border=0>"
+
+            columns = width / maxwidth
+            if columns < 1:
+                columns = 1
+
+            count = len( section.block_names )
+            rows  = ( count + columns - 1 ) / columns
+
+            for r in range( rows ):
+                line = "<tr>"
+                for c in range( columns ):
+                    i = r + c * rows
+                    line = line + '<td></td><td>'
+                    if i < count:
+                        name = section.block_names[i]
+                        line = line + '<a href="#' + name + '">' + name + '</a>'
+
+                    line = line + '</td>'
+                line = line + "</tr>"
+                print line
+
+            print "</table><br><br>"
+            print section_synopsis_footer
 
         print description_header
         print self.make_html_items( section.description )