From 7785694244cdfc5939ca4754cab4e08bd6980f99 Mon Sep 17 00:00:00 2001
From: marha <marha@users.sourceforge.net>
Date: Sun, 22 Feb 2015 14:47:01 +0100
Subject: Upgraded to freetype 2.5.5

---
 freetype/src/tools/docmaker/content.py   | 216 ++++++++++-----
 freetype/src/tools/docmaker/docmaker.py  |  39 +--
 freetype/src/tools/docmaker/formatter.py |  73 +++--
 freetype/src/tools/docmaker/sources.py   | 200 +++++++-------
 freetype/src/tools/docmaker/tohtml.py    | 445 +++++++++++++++++++------------
 freetype/src/tools/docmaker/utils.py     |  81 +++---
 6 files changed, 643 insertions(+), 411 deletions(-)

(limited to 'freetype/src/tools/docmaker')

diff --git a/freetype/src/tools/docmaker/content.py b/freetype/src/tools/docmaker/content.py
index 98025e67e..adea6f1d7 100644
--- a/freetype/src/tools/docmaker/content.py
+++ b/freetype/src/tools/docmaker/content.py
@@ -1,57 +1,81 @@
-#  Content (c) 2002, 2004, 2006-2009, 2012, 2013
-#    David Turner <david@freetype.org>
 #
-#  This file contains routines used to parse the content of documentation
-#  comment blocks and build more structured objects out of them.
+#  content.py
+#
+#    Parse comment blocks to build content blocks (library file).
+#
+#  Copyright 2002, 2004, 2006-2009, 2012-2014 by
+#  David Turner.
+#
+#  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 contains routines to parse documentation comment blocks,
+# building more structured objects out of them.
 #
 
+
 from sources import *
-from utils import *
+from utils   import *
+
 import string, re
 
 
-# this regular expression is used to detect code sequences. these
-# are simply code fragments embedded in '{' and '}' like in:
 #
-#  {
-#    x = y + z;
-#    if ( zookoo == 2 )
-#    {
-#      foobar();
-#    }
-#  }
+# Regular expressions to detect code sequences.  `Code sequences' are simply
+# code fragments embedded in '{' and '}', as demonstrated in the following
+# example.
+#
+#   {
+#     x = y + z;
+#     if ( zookoo == 2 )
+#     {
+#       foobar();
+#     }
+#   }
 #
-# note that indentation of the starting and ending accolades must be
-# exactly the same. the code sequence can contain accolades at greater
-# indentation
+# Note that the indentation of the first opening brace and the last closing
+# brace must be exactly the same.  The code sequence itself should have a
+# larger indentation than the surrounding braces.
 #
 re_code_start = re.compile( r"(\s*){\s*$" )
 re_code_end   = re.compile( r"(\s*)}\s*$" )
 
 
-# this regular expression is used to isolate identifiers from
-# other text
 #
-re_identifier = re.compile( r'((?:\w|-)*)' )
-
-
-# we collect macros ending in `_H'; while outputting the object data, we use
-# this info together with the object's file location to emit the appropriate
-# header file macro and name before the object itself
+# A regular expression to isolate identifiers from other text.
 #
-re_header_macro = re.compile( r'^#define\s{1,}(\w{1,}_H)\s{1,}<(.*)>' )
+re_identifier = re.compile( r'((?:\w|-)*)' )
 
 
-#############################################################################
 #
-# The DocCode class is used to store source code lines.
+# We collect macro names ending in `_H' (group 1), as defined in
+# `config/ftheader.h'.  While outputting the object data, we use this info
+# together with the object's file location (group 2) to emit the appropriate
+# header file macro and its associated file name before the object itself.
 #
-#   'self.lines' contains a set of source code lines that will be dumped as
-#   HTML in a <PRE> tag.
+# Example:
 #
-#   The object is filled line by line by the parser; it strips the leading
-#   "margin" space from each input line before storing it in 'self.lines'.
+#   #define FT_FREETYPE_H <freetype.h>
 #
+re_header_macro = re.compile( r'^#define\s{1,}(\w{1,}_H)\s{1,}<(.*)>' )
+
+
+################################################################
+##
+##  DOC CODE CLASS
+##
+##  The `DocCode' class is used to store source code lines.
+##
+##  `self.lines' contains a set of source code lines that will be dumped as
+##  HTML in a <PRE> tag.
+##
+##  The object is filled line by line by the parser; it strips the leading
+##  `margin' space from each input line before storing it in `self.lines'.
+##
 class  DocCode:
 
     def  __init__( self, margin, lines ):
@@ -77,12 +101,14 @@ class  DocCode:
 
 
 
-#############################################################################
-#
-# The DocPara class is used to store "normal" text paragraph.
-#
-#   'self.words' contains the list of words that make up the paragraph
-#
+################################################################
+##
+##  DOC PARA CLASS
+##
+##  `Normal' text paragraphs are stored in the `DocPara' class.
+##
+##  `self.words' contains the list of words that make up the paragraph.
+##
 class  DocPara:
 
     def  __init__( self, lines ):
@@ -123,17 +149,18 @@ class  DocPara:
         return result
 
 
-
-#############################################################################
-#
-#  The DocField class is used to store a list containing either DocPara or
-#  DocCode objects. Each DocField also has an optional "name" which is used
-#  when the object corresponds to a field or value definition
-#
+################################################################
+##
+##  DOC FIELD CLASS
+##
+##  The `DocField' class stores a list containing either `DocPara' or
+##  `DocCode' objects.  Each DocField object also has an optional `name'
+##  that is used when the object corresponds to a field or value definition.
+##
 class  DocField:
 
     def  __init__( self, name, lines ):
-        self.name  = name  # can be None for normal paragraphs/sources
+        self.name  = name  # can be `None' for normal paragraphs/sources
         self.items = []    # list of items
 
         mode_none  = 0     # start parsing mode
@@ -143,14 +170,14 @@ class  DocField:
         margin     = -1    # current code sequence indentation
         cur_lines  = []
 
-        # now analyze the markup lines to see if they contain paragraphs,
-        # code sequences or fields definitions
+        # analyze the markup lines to check whether they contain paragraphs,
+        # code sequences, or fields definitions
         #
         start = 0
         mode  = mode_none
 
         for l in lines:
-            # are we parsing a code sequence ?
+            # are we parsing a code sequence?
             if mode == mode_code:
                 m = re_code_end.match( l )
                 if m and len( m.group( 1 ) ) <= margin:
@@ -161,10 +188,10 @@ class  DocField:
                     cur_lines = []
                     mode      = mode_none
                 else:
-                    # nope, continue the code sequence
+                    # otherwise continue the code sequence
                     cur_lines.append( l[margin:] )
             else:
-                # start of code sequence ?
+                # start of code sequence?
                 m = re_code_start.match( l )
                 if m:
                     # save current lines
@@ -222,13 +249,29 @@ class  DocField:
         return result
 
 
-
-# this regular expression is used to detect field definitions
 #
-re_field = re.compile( r"\s*(\w*|\w(\w|\.)*\w)\s*::" )
-
-
-
+# A regular expression to detect field definitions.
+#
+# Examples:
+#
+#   foo     ::
+#   foo.bar ::
+#
+re_field = re.compile( r"""
+                         \s*
+                           (
+                             \w*
+                           |
+                             \w (\w | \.)* \w
+                           )
+                         \s* ::
+                       """, re.VERBOSE )
+
+
+################################################################
+##
+##  DOC MARKUP CLASS
+##
 class  DocMarkup:
 
     def  __init__( self, tag, lines ):
@@ -242,7 +285,7 @@ class  DocMarkup:
         for l in lines:
             m = re_field.match( l )
             if m:
-                # we detected the start of a new field definition
+                # We detected the start of a new field definition.
 
                 # first, save the current one
                 if cur_lines:
@@ -275,7 +318,10 @@ class  DocMarkup:
         print " " * margin + "</" + self.tag + ">"
 
 
-
+################################################################
+##
+##  DOC CHAPTER CLASS
+##
 class  DocChapter:
 
     def  __init__( self, block ):
@@ -291,7 +337,10 @@ class  DocChapter:
             self.order = []
 
 
-
+################################################################
+##
+##  DOC SECTION CLASS
+##
 class  DocSection:
 
     def  __init__( self, name = "Other" ):
@@ -320,18 +369,21 @@ class  DocSection:
                 self.title       = title
                 self.abstract    = block.get_markup_words( "abstract" )
                 self.description = block.get_markup_items( "description" )
-                self.order       = block.get_markup_words( "order" )
+                self.order       = block.get_markup_words_all( "order" )
                 return
 
     def  reorder( self ):
         self.block_names = sort_order_list( self.block_names, self.order )
 
 
-
+################################################################
+##
+##  CONTENT PROCESSOR CLASS
+##
 class  ContentProcessor:
 
     def  __init__( self ):
-        """initialize a block content processor"""
+        """Initialize a block content processor."""
         self.reset()
 
         self.sections = {}    # dictionary of documentation sections
@@ -342,8 +394,8 @@ class  ContentProcessor:
         self.headers  = {}    # dictionary of header macros
 
     def  set_section( self, section_name ):
-        """set current section during parsing"""
-        if not self.sections.has_key( section_name ):
+        """Set current section during parsing."""
+        if not section_name in self.sections:
             section = DocSection( section_name )
             self.sections[section_name] = section
             self.section                = section
@@ -354,15 +406,14 @@ class  ContentProcessor:
         chapter = DocChapter( block )
         self.chapters.append( chapter )
 
-
     def  reset( self ):
-        """reset the content processor for a new block"""
+        """Reset the content processor for a new block."""
         self.markups      = []
         self.markup       = None
         self.markup_lines = []
 
     def  add_markup( self ):
-        """add a new markup section"""
+        """Add a new markup section."""
         if self.markup and self.markup_lines:
 
             # get rid of last line of markup if it's empty
@@ -378,8 +429,8 @@ class  ContentProcessor:
             self.markup_lines = []
 
     def  process_content( self, content ):
-        """process a block content and return a list of DocMarkup objects
-           corresponding to it"""
+        """Process a block content and return a list of DocMarkup objects
+           corresponding to it."""
         markup       = None
         markup_lines = []
         first        = 1
@@ -437,7 +488,7 @@ class  ContentProcessor:
         # listed there
         for chap in self.chapters:
             for sec in chap.order:
-                if self.sections.has_key( sec ):
+                if sec in self.sections:
                     section = self.sections[sec]
                     section.chapter = chap
                     section.reorder()
@@ -452,6 +503,7 @@ class  ContentProcessor:
         others = []
         for sec in self.sections.values():
             if not sec.chapter:
+                sec.reorder()
                 others.append( sec )
 
         # create a new special chapter for all remaining sections
@@ -463,7 +515,10 @@ class  ContentProcessor:
             self.chapters.append( chap )
 
 
-
+################################################################
+##
+##  DOC BLOCK CLASS
+##
 class  DocBlock:
 
     def  __init__( self, source, follow, processor ):
@@ -540,7 +595,7 @@ class  DocBlock:
         return self.source.location()
 
     def  get_markup( self, tag_name ):
-        """return the DocMarkup corresponding to a given tag in a block"""
+        """Return the DocMarkup corresponding to a given tag in a block."""
         for m in self.markups:
             if m.tag == string.lower( tag_name ):
                 return m
@@ -553,6 +608,21 @@ class  DocBlock:
         except:
             return []
 
+    def  get_markup_words_all( self, tag_name ):
+        try:
+            m = self.get_markup( tag_name )
+            words = []
+            for item in m.fields[0].items:
+                # We honour empty lines in an `<Order>' section element by
+                # adding the sentinel `/empty/'.  The formatter should then
+                # convert it to an appropriate representation in the
+                # `section_enter' function.
+                words += item.words
+                words.append( "/empty/" )
+            return words
+        except:
+            return []
+
     def  get_markup_text( self, tag_name ):
         result = self.get_markup_words( tag_name )
         return string.join( result )
diff --git a/freetype/src/tools/docmaker/docmaker.py b/freetype/src/tools/docmaker/docmaker.py
index bf75c5d5f..4fb1abf23 100644
--- a/freetype/src/tools/docmaker/docmaker.py
+++ b/freetype/src/tools/docmaker/docmaker.py
@@ -1,16 +1,26 @@
 #!/usr/bin/env python
 #
-#  DocMaker (c) 2002, 2004, 2008, 2013 David Turner <david@freetype.org>
+#  docmaker.py
 #
-# This program is a re-write of the original DocMaker tool used
-# to generate the API Reference of the FreeType font engine
-# by converting in-source comments into structured HTML.
+#    Convert source code markup to HTML documentation.
 #
-# This new version is capable of outputting XML data, as well
-# as accepts more liberal formatting options.
+#  Copyright 2002, 2004, 2008, 2013, 2014 by
+#  David Turner.
 #
-# It also uses regular expression matching and substitution
-# to speed things significantly.
+#  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 program is a re-write of the original DocMaker tool used to generate
+# the API Reference of the FreeType font rendering engine by converting
+# in-source comments into structured HTML.
+#
+# This new version is capable of outputting XML data as well as accepting
+# more liberal formatting options.  It also uses regular expression matching
+# and substitution to speed up operation significantly.
 #
 
 from sources   import *
@@ -39,13 +49,13 @@ def  usage():
 
 
 def  main( argv ):
-    """main program loop"""
+    """Main program loop."""
 
     global output_dir
 
     try:
-        opts, args = getopt.getopt( sys.argv[1:], \
-                                    "ht:o:p:",    \
+        opts, args = getopt.getopt( sys.argv[1:],
+                                    "ht:o:p:",
                                     ["help", "title=", "output=", "prefix="] )
     except getopt.GetoptError:
         usage()
@@ -56,7 +66,6 @@ def  main( argv ):
         sys.exit( 1 )
 
     # process options
-    #
     project_title  = "Project"
     project_prefix = None
     output_dir     = None
@@ -90,7 +99,9 @@ def  main( argv ):
     # process sections
     content_processor.finish()
 
-    formatter = HtmlFormatter( content_processor, project_title, project_prefix )
+    formatter = HtmlFormatter( content_processor,
+                               project_title,
+                               project_prefix )
 
     formatter.toc_dump()
     formatter.index_dump()
@@ -98,9 +109,7 @@ def  main( argv ):
 
 
 # if called from the command line
-#
 if __name__ == '__main__':
     main( sys.argv )
 
-
 # eof
diff --git a/freetype/src/tools/docmaker/formatter.py b/freetype/src/tools/docmaker/formatter.py
index f62ce676c..7152c019d 100644
--- a/freetype/src/tools/docmaker/formatter.py
+++ b/freetype/src/tools/docmaker/formatter.py
@@ -1,19 +1,37 @@
-#  Formatter (c) 2002, 2004, 2007, 2008 David Turner <david@freetype.org>
 #
+#  formatter.py
+#
+#    Convert parsed content blocks to a structured document (library file).
+#
+#  Copyright 2002, 2004, 2007, 2008, 2014 by
+#  David Turner.
+#
+#  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 is the base Formatter class.  Its purpose is to convert a content
+# processor's data into specific documents (i.e., table of contents, global
+# index, and individual API reference indices).
+#
+# You need to sub-class it to output anything sensible.  For example, the
+# file `tohtml.py' contains the definition of the `HtmlFormatter' sub-class
+# to output HTML.
+#
+
 
 from sources import *
 from content import *
 from utils   import *
 
-# This is the base Formatter class.  Its purpose is to convert
-# a content processor's data into specific documents (i.e., table of
-# contents, global index, and individual API reference indices).
-#
-# You need to sub-class it to output anything sensible.  For example,
-# the file tohtml.py contains the definition of the HtmlFormatter sub-class
-# used to output -- you guessed it -- HTML.
-#
 
+################################################################
+##
+##  FORMATTER CLASS
+##
 class  Formatter:
 
     def  __init__( self, processor ):
@@ -36,20 +54,22 @@ class  Formatter:
                             self.add_identifier( field.name, block )
 
         self.block_index = self.identifiers.keys()
-        self.block_index.sort( index_sort )
+        self.block_index.sort( key = index_key )
 
     def  add_identifier( self, name, block ):
-        if self.identifiers.has_key( name ):
+        if name in self.identifiers:
             # duplicate name!
-            sys.stderr.write(                                           \
-               "WARNING: duplicate definition for '" + name + "' in " + \
-               block.location() + ", previous definition in " +         \
-               self.identifiers[name].location() + "\n" )
+            sys.stderr.write( "WARNING: duplicate definition for"
+                              + " '" + name + "' "
+                              + "in " + block.location() + ", "
+                              + "previous definition in "
+                              + self.identifiers[name].location()
+                              + "\n" )
         else:
             self.identifiers[name] = block
 
     #
-    #  Formatting the table of contents
+    # formatting the table of contents
     #
     def  toc_enter( self ):
         pass
@@ -97,7 +117,7 @@ class  Formatter:
             close_output( output )
 
     #
-    #  Formatting the index
+    # formatting the index
     #
     def  index_enter( self ):
         pass
@@ -128,7 +148,7 @@ class  Formatter:
             close_output( output )
 
     #
-    #  Formatting a section
+    # formatting a section
     #
     def  section_enter( self, section ):
         pass
@@ -162,7 +182,22 @@ class  Formatter:
         self.section_enter( section )
 
         for name in section.block_names:
-            block = self.identifiers[name]
+            skip_entry = 0
+            try:
+                block = self.identifiers[name]
+                # `block_names' can contain field names also,
+                # which we filter out
+                for markup in block.markups:
+                    if markup.tag == 'values':
+                        for field in markup.fields:
+                            if field.name == name:
+                                skip_entry = 1
+            except:
+                skip_entry = 1   # this happens e.g. for `/empty/' entries
+
+            if skip_entry:
+              continue
+
             self.block_enter( block )
 
             for markup in block.markups[1:]:   # always ignore first markup!
diff --git a/freetype/src/tools/docmaker/sources.py b/freetype/src/tools/docmaker/sources.py
index dab834978..61ecc22c4 100644
--- a/freetype/src/tools/docmaker/sources.py
+++ b/freetype/src/tools/docmaker/sources.py
@@ -1,62 +1,70 @@
-#  Sources (c) 2002-2004, 2006-2009, 2012, 2013
-#    David Turner <david@freetype.org>
 #
+#  sources.py
 #
-# this file contains definitions of classes needed to decompose
-# C sources files into a series of multi-line "blocks". There are
-# two kinds of blocks:
+#    Convert source code comments to multi-line blocks (library file).
 #
-#   - normal blocks, which contain source code or ordinary comments
+#  Copyright 2002-2004, 2006-2009, 2012-2014 by
+#  David Turner.
 #
-#   - documentation blocks, which have restricted formatting, and
-#     whose text always start with a documentation markup tag like
-#     "<Function>", "<Type>", etc..
+#  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 library file contains definitions of classes needed to decompose C
+# source code files into a series of multi-line `blocks'.  There are two
+# kinds of blocks.
+#
+#   - Normal blocks, which contain source code or ordinary comments.
 #
-# the routines used to process the content of documentation blocks
-# are not contained here, but in "content.py"
+#   - Documentation blocks, which have restricted formatting, and whose text
+#     always start with a documentation markup tag like `<Function>',
+#     `<Type>', etc.
 #
-# the classes and methods found here only deal with text parsing
-# and basic documentation block extraction
+# The routines to process the content of documentation blocks are contained
+# in file `content.py'; the classes and methods found here only deal with
+# text parsing and basic documentation block extraction.
 #
 
-import fileinput, re, sys, os, string
 
+import fileinput, re, sys, os, string
 
 
 ################################################################
 ##
-##  BLOCK FORMAT PATTERN
+##  SOURCE BLOCK FORMAT CLASS
+##
+##  A simple class containing compiled regular expressions to detect
+##  potential documentation format block comments within C source code.
 ##
-##   A simple class containing compiled regular expressions used
-##   to detect potential documentation format block comments within
-##   C source code
+##  The `column' pattern must contain a group to `unbox' the content of
+##  documentation comment blocks.
 ##
-##   note that the 'column' pattern must contain a group that will
-##   be used to "unbox" the content of documentation comment blocks
+##  Later on, paragraphs are converted to long lines, which simplifies the
+##  regular expressions that act upon the text.
 ##
 class  SourceBlockFormat:
 
     def  __init__( self, id, start, column, end ):
-        """create a block pattern, used to recognize special documentation blocks"""
+        """Create a block pattern, used to recognize special documentation
+           blocks."""
         self.id     = id
         self.start  = re.compile( start, re.VERBOSE )
         self.column = re.compile( column, re.VERBOSE )
         self.end    = re.compile( end, re.VERBOSE )
 
 
-
 #
-# format 1 documentation comment blocks look like the following:
+# Format 1 documentation comment blocks.
 #
-#    /************************************/
+#    /************************************/ (at least 2 asterisks)
 #    /*                                  */
 #    /*                                  */
 #    /*                                  */
-#    /************************************/
-#
-# we define a few regular expressions here to detect them
+#    /************************************/ (at least 2 asterisks)
 #
-
 start = r'''
   \s*      # any number of whitespace
   /\*{2,}/ # followed by '/' and at least two asterisks then '/'
@@ -75,16 +83,13 @@ re_source_block_format1 = SourceBlockFormat( 1, start, column, start )
 
 
 #
-# format 2 documentation comment blocks look like the following:
+# Format 2 documentation comment blocks.
 #
 #    /************************************ (at least 2 asterisks)
 #     *
+#     *                                    (1 asterisk)
 #     *
-#     *
-#     *
-#     **/       (1 or more asterisks at the end)
-#
-# we define a few regular expressions here to detect them
+#     */                                   (1 or more asterisks)
 #
 start = r'''
   \s*     # any number of whitespace
@@ -93,9 +98,9 @@ start = r'''
 '''
 
 column = r'''
-  \s*        # any number of whitespace
-  \*{1}(?!/) # followed by precisely one asterisk not followed by `/'
-  (.*)       # then anything (group1)
+  \s*           # any number of whitespace
+  \*{1}(?![*/]) # followed by precisely one asterisk not followed by `/'
+  (.*)          # then anything (group1)
 '''
 
 end = r'''
@@ -107,47 +112,56 @@ re_source_block_format2 = SourceBlockFormat( 2, start, column, end )
 
 
 #
-# the list of supported documentation block formats, we could add new ones
-# relatively easily
+# The list of supported documentation block formats.  We could add new ones
+# quite easily.
 #
 re_source_block_formats = [re_source_block_format1, re_source_block_format2]
 
 
 #
-# the following regular expressions corresponds to markup tags
-# within the documentation comment blocks. they're equivalent
-# despite their different syntax
+# The following regular expressions correspond to markup tags within the
+# documentation comment blocks.  They are equivalent despite their different
+# syntax.
+#
+# A markup tag consists of letters or character `-', to be found in group 1.
 #
-# notice how each markup tag _must_ begin a new line
+# Notice that a markup tag _must_ begin a new paragraph.
 #
 re_markup_tag1 = re.compile( r'''\s*<((?:\w|-)*)>''' )  # <xxxx> format
 re_markup_tag2 = re.compile( r'''\s*@((?:\w|-)*):''' )  # @xxxx: format
 
 #
-# the list of supported markup tags, we could add new ones relatively
-# easily
+# The list of supported markup tags.  We could add new ones quite easily.
 #
 re_markup_tags = [re_markup_tag1, re_markup_tag2]
 
+
 #
-# used to detect a cross-reference, after markup tags have been stripped
+# A regular expression to detect a cross reference, after markup tags have
+# been stripped off.  Group 1 is the reference, group 2 the rest of the
+# line.
+#
+# A cross reference consists of letters, digits, or characters `-' and `_'.
 #
 re_crossref = re.compile( r'@((?:\w|-)*)(.*)' )    #  @foo
 
 #
-# used to detect italic and bold styles in paragraph text
+# Two regular expressions to detect italic and bold markup, respectively.
+# Group 1 is the markup, group 2 the rest of the line.
+#
+# Note that the markup is limited to words consisting of letters, digits,
+# the character `_', or an apostrophe (but not as the first character).
 #
-re_italic = re.compile( r"_(\w(\w|')*)_(.*)" )     #  _italic_
-re_bold   = re.compile( r"\*(\w(\w|')*)\*(.*)" )   #  *bold*
+re_italic = re.compile( r"_(\w(?:\w|')*)_(.*)" )     #  _italic_
+re_bold   = re.compile( r"\*(\w(?:\w|')*)\*(.*)" )   #  *bold*
 
 #
-# this regular expression code to identify an URL has been taken from
+# This regular expression code to identify an URL has been taken from
 #
 #   http://mail.python.org/pipermail/tutor/2002-September/017228.html
 #
-# (with slight modifications)
+# (with slight modifications).
 #
-
 urls = r'(?:https?|telnet|gopher|file|wais|ftp)'
 ltrs = r'\w'
 gunk = r'/#~:.?+=&%@!\-'
@@ -177,17 +191,22 @@ url  = r"""
 re_url = re.compile( url, re.VERBOSE | re.MULTILINE )
 
 #
-# used to detect the end of commented source lines
+# A regular expression that stops collection of comments for the current
+# block.
 #
-re_source_sep = re.compile( r'\s*/\*\s*\*/' )
+re_source_sep = re.compile( r'\s*/\*\s*\*/' )   #  /* */
 
 #
-# used to perform cross-reference within source output
+# A regular expression to find possible C identifiers while outputting
+# source code verbatim, covering things like `*foo' or `(bar'.  Group 1 is
+# the prefix, group 2 the identifier -- since we scan lines from left to
+# right, sequentially splitting the source code into prefix and identifier
+# is fully sufficient for our purposes.
 #
 re_source_crossref = re.compile( r'(\W*)(\w*)' )
 
 #
-# a list of reserved source keywords
+# A regular expression that matches a list of reserved C source keywords.
 #
 re_source_keywords = re.compile( '''\\b ( typedef   |
                                           struct    |
@@ -215,24 +234,16 @@ re_source_keywords = re.compile( '''\\b ( typedef   |
 ##
 ##  SOURCE BLOCK CLASS
 ##
-##   A SourceProcessor is in charge of reading a C source file
-##   and decomposing it into a series of different "SourceBlocks".
-##   each one of these blocks can be made of the following data:
-##
-##   - A documentation comment block that starts with "/**" and
-##     whose exact format will be discussed later
-##
-##   - normal sources lines, including comments
+##  There are two important fields in a `SourceBlock' object.
 ##
-##   the important fields in a text block are the following ones:
+##    self.lines
+##      A list of text lines for the corresponding block.
 ##
-##     self.lines   : a list of text lines for the corresponding block
-##
-##     self.content : for documentation comment blocks only, this is the
-##                    block content that has been "unboxed" from its
-##                    decoration. This is None for all other blocks
-##                    (i.e. sources or ordinary comments with no starting
-##                     markup tag)
+##    self.content
+##      For documentation comment blocks only, this is the block content
+##      that has been `unboxed' from its decoration.  This is `None' for all
+##      other blocks (i.e., sources or ordinary comments with no starting
+##      markup tag)
 ##
 class  SourceBlock:
 
@@ -269,7 +280,7 @@ class  SourceBlock:
     def  location( self ):
         return "(" + self.filename + ":" + repr( self.lineno ) + ")"
 
-    # debugging only - not used in normal operations
+    # debugging only -- not used in normal operations
     def  dump( self ):
         if self.content:
             print "{{{content start---"
@@ -286,39 +297,38 @@ class  SourceBlock:
             print line
 
 
-
 ################################################################
 ##
 ##  SOURCE PROCESSOR CLASS
 ##
-##   The SourceProcessor is in charge of reading a C source file
-##   and decomposing it into a series of different "SourceBlock"
-##   objects.
+##  The `SourceProcessor' is in charge of reading a C source file and
+##  decomposing it into a series of different `SourceBlock' objects.
 ##
-##   each one of these blocks can be made of the following data:
+##  A SourceBlock object consists of the following data.
 ##
-##   - A documentation comment block that starts with "/**" and
-##     whose exact format will be discussed later
+##    - A documentation comment block using one of the layouts above.  Its
+##      exact format will be discussed later.
 ##
-##   - normal sources lines, include comments
+##    - Normal sources lines, including comments.
 ##
 ##
 class  SourceProcessor:
 
     def  __init__( self ):
-        """initialize a source processor"""
+        """Initialize a source processor."""
         self.blocks   = []
         self.filename = None
         self.format   = None
         self.lines    = []
 
     def  reset( self ):
-        """reset a block processor, clean all its blocks"""
+        """Reset a block processor and clean up all its blocks."""
         self.blocks = []
         self.format = None
 
     def  parse_file( self, filename ):
-        """parse a C source file, and add its blocks to the processor's list"""
+        """Parse a C source file and add its blocks to the processor's
+           list."""
         self.reset()
 
         self.filename = filename
@@ -337,16 +347,16 @@ class  SourceProcessor:
                 self.process_normal_line( line )
             else:
                 if self.format.end.match( line ):
-                    # that's a normal block end, add it to 'lines' and
-                    # create a new block
+                    # A normal block end.  Add it to `lines' and create a
+                    # new block
                     self.lines.append( line )
                     self.add_block_lines()
                 elif self.format.column.match( line ):
-                    # that's a normal column line, add it to 'lines'
+                    # A normal column line.  Add it to `lines'.
                     self.lines.append( line )
                 else:
-                    # humm.. this is an unexpected block end,
-                    # create a new block, but don't process the line
+                    # An unexpected block end.  Create a new block, but
+                    # don't process the line.
                     self.add_block_lines()
 
                     # we need to process the line again
@@ -356,7 +366,8 @@ class  SourceProcessor:
         self.add_block_lines()
 
     def  process_normal_line( self, line ):
-        """process a normal line and check whether it is the start of a new block"""
+        """Process a normal line and check whether it is the start of a new
+           block."""
         for f in re_source_block_formats:
             if f.start.match( line ):
                 self.add_block_lines()
@@ -366,9 +377,12 @@ class  SourceProcessor:
         self.lines.append( line )
 
     def  add_block_lines( self ):
-        """add the current accumulated lines and create a new block"""
+        """Add the current accumulated lines and create a new block."""
         if self.lines != []:
-            block = SourceBlock( self, self.filename, self.lineno, self.lines )
+            block = SourceBlock( self,
+                                 self.filename,
+                                 self.lineno,
+                                 self.lines )
 
             self.blocks.append( block )
             self.format = None
@@ -376,7 +390,7 @@ class  SourceProcessor:
 
     # debugging only, not used in normal operations
     def  dump( self ):
-        """print all blocks in a processor"""
+        """Print all blocks in a processor."""
         for b in self.blocks:
             b.dump()
 
diff --git a/freetype/src/tools/docmaker/tohtml.py b/freetype/src/tools/docmaker/tohtml.py
index 7944f1c99..05fc08a92 100644
--- a/freetype/src/tools/docmaker/tohtml.py
+++ b/freetype/src/tools/docmaker/tohtml.py
@@ -1,5 +1,19 @@
-#  ToHTML (c) 2002, 2003, 2005-2008, 2013
-#    David Turner <david@freetype.org>
+#
+#  tohtml.py
+#
+#    A sub-class container of the `Formatter' class to produce HTML.
+#
+#  Copyright 2002, 2003, 2005-2008, 2013, 2014 by
+#  David Turner.
+#
+#  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.
+
+# The parent class is contained in file `formatter.py'.
+
 
 from sources import *
 from content import *
@@ -8,7 +22,7 @@ from formatter import *
 import time
 
 
-# The following defines the HTML header used by all generated pages.
+# The following strings define the HTML header used by all generated pages.
 html_header_1 = """\
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
 "http://www.w3.org/TR/html4/loose.dtd">
@@ -21,62 +35,125 @@ html_header_1 = """\
 html_header_2 = """\
  API Reference</title>
 <style type="text/css">
+  a:link { color: #0000EF; }
+  a:visited { color: #51188E; }
+  a:hover { color: #FF0000; }
+
   body { font-family: Verdana, Geneva, Arial, Helvetica, serif;
          color: #000000;
-         background: #FFFFFF; }
+         background: #FFFFFF;
+         width: 87%;
+         margin: auto; }
+
+  div.section { width: 75%;
+                margin: auto; }
+  div.section hr { margin: 4ex 0 1ex 0; }
+  div.section h4 { background-color: #EEEEFF;
+                   font-size: medium;
+                   font-style: oblique;
+                   font-weight: bold;
+                   margin: 3ex 0 1.5ex 9%;
+                   padding: 0.3ex 0 0.3ex 1%; }
+  div.section p { margin: 1.5ex 0 1.5ex 10%; }
+  div.section pre { margin: 3ex 0 3ex 9%;
+                    background-color: #D6E8FF;
+                    padding: 2ex 0 2ex 1%; }
+  div.section table.fields { width: 90%;
+                             margin: 1.5ex 0 1.5ex 10%; }
+  div.section table.toc { width: 95%;
+                          margin: 1.5ex 0 1.5ex 5%; }
+  div.timestamp { text-align: center;
+                  font-size: 69%;
+                  margin: 1.5ex 0 1.5ex 0; }
 
-  p { text-align: justify; }
   h1 { text-align: center; }
-  li { text-align: justify; }
-  td { padding: 0 0.5em 0 0.5em; }
-  td.left { padding: 0 0.5em 0 0.5em;
-            text-align: left; }
+  h3 { font-size: medium;
+       margin: 4ex 0 1.5ex 0; }
 
-  a:link { color: #0000EF; }
-  a:visited { color: #51188E; }
-  a:hover { color: #FF0000; }
+  p { text-align: justify; }
+
+  pre.colored { color: blue; }
 
   span.keyword { font-family: monospace;
                  text-align: left;
                  white-space: pre;
                  color: darkblue; }
 
-  pre.colored { color: blue; }
+  table.fields td.val { font-weight: bold;
+                        text-align: right;
+                        width: 30%;
+                        vertical-align: baseline;
+                        padding: 1ex 1em 1ex 0; }
+  table.fields td.desc { vertical-align: baseline;
+                         padding: 1ex 0 1ex 1em; }
+  table.fields td.desc p:first-child { margin: 0; }
+  table.fields td.desc p { margin: 1.5ex 0 0 0; }
+  table.index { margin: 6ex auto 6ex auto;
+                border: 0;
+                border-collapse: separate;
+                border-spacing: 1em 0.3ex; }
+  table.index tr { padding: 0; }
+  table.index td { padding: 0; }
+  table.index-toc-link { width: 100%;
+                         border: 0;
+                         border-spacing: 0;
+                         margin: 1ex 0 1ex 0; }
+  table.index-toc-link td.left { padding: 0 0.5em 0 0.5em;
+                                 font-size: 83%;
+                                 text-align: left; }
+  table.index-toc-link td.middle { padding: 0 0.5em 0 0.5em;
+                                   font-size: 83%;
+                                   text-align: center; }
+  table.index-toc-link td.right { padding: 0 0.5em 0 0.5em;
+                                  font-size: 83%;
+                                  text-align: right; }
+  table.synopsis { margin: 6ex auto 6ex auto;
+                   border: 0;
+                   border-collapse: separate;
+                   border-spacing: 2em 0.6ex; }
+  table.synopsis tr { padding: 0; }
+  table.synopsis td { padding: 0; }
+  table.toc td.link { width: 30%;
+                      text-align: right;
+                      vertical-align: baseline;
+                      padding: 1ex 1em 1ex 0; }
+  table.toc td.desc { vertical-align: baseline;
+                      padding: 1ex 0 1ex 1em;
+                      text-align: left; }
+  table.toc td.desc p:first-child { margin: 0;
+                                    text-align: left; }
+  table.toc td.desc p { margin: 1.5ex 0 0 0;
+                        text-align: left; }
 
-  ul.empty { list-style-type: none; }
 </style>
 </head>
 <body>
 """
 
-html_header_3 = """
-<table align=center><tr><td><font size=-1>[<a href="\
+html_header_3l = """
+<table class="index-toc-link"><tr><td class="left">[<a href="\
 """
 
-html_header_3i = """
-<table align=center><tr><td width="100%"></td>
-<td><font size=-1>[<a href="\
+html_header_3r = """
+<table class="index-toc-link"><tr><td class="right">[<a href="\
 """
 
 html_header_4 = """\
-">Index</a>]</font></td>
-<td width="100%"></td>
-<td><font size=-1>[<a href="\
+">Index</a>]</td><td class="right">[<a href="\
 """
 
-html_header_5 = """\
-">TOC</a>]</font></td></tr></table>
-<center><h1>\
+html_header_5t = """\
+">TOC</a>]</td></tr></table>
+<h1>\
 """
 
-html_header_5t = """\
-">Index</a>]</font></td>
-<td width="100%"></td></tr></table>
-<center><h1>\
+html_header_5i = """\
+">Index</a>]</td></tr></table>
+<h1>\
 """
 
 html_header_6 = """\
- API Reference</h1></center>
+ API Reference</h1>
 """
 
 
@@ -87,8 +164,8 @@ html_footer = """\
 """
 
 # The header and footer used for each section.
-section_title_header = "<center><h1>"
-section_title_footer = "</h1></center>"
+section_title_header = "<h1>"
+section_title_footer = "</h1>"
 
 # The header and footer used for code segments.
 code_header = '<pre class="colored">'
@@ -99,66 +176,65 @@ para_header = "<p>"
 para_footer = "</p>"
 
 # Block header and footer.
-block_header        = '<table align=center width="75%"><tr><td>'
+block_header        = '<div class="section">'
 block_footer_start  = """\
-</td></tr></table>
-<hr width="75%">
-<table align=center width="75%"><tr><td><font size=-2>[<a href="\
+<hr>
+<table class="index-toc-link"><tr><td class="left">[<a href="\
 """
 block_footer_middle = """\
-">Index</a>]</font></td>
-<td width="100%"></td>
-<td><font size=-2>[<a href="\
+">Index</a>]</td>\
+<td class="middle">[<a href="#">Top</a>]</td>\
+<td class="right">[<a href="\
 """
 block_footer_end    = """\
-">TOC</a>]</font></td></tr></table>
+">TOC</a>]</td></tr></table></div>
 """
 
 # Description header/footer.
-description_header = '<table align=center width="87%"><tr><td>'
-description_footer = "</td></tr></table><br>"
+description_header = ""
+description_footer = ""
 
 # Marker header/inter/footer combination.
-marker_header = '<table align=center width="87%" cellpadding=5><tr bgcolor="#EEEEFF"><td><em><b>'
-marker_inter  = "</b></em></td></tr><tr><td>"
-marker_footer = "</td></tr></table>"
+marker_header = "<h4>"
+marker_inter  = "</h4>"
+marker_footer = ""
 
 # Header location header/footer.
-header_location_header = '<table align=center width="87%"><tr><td>'
-header_location_footer = "</td></tr></table><br>"
+header_location_header = "<p>"
+header_location_footer = "</p>"
 
 # Source code extracts header/footer.
-source_header = '<table align=center width="87%"><tr bgcolor="#D6E8FF"><td><pre>\n'
-source_footer = "\n</pre></table><br>"
+source_header = "<pre>"
+source_footer = "</pre>"
 
 # Chapter header/inter/footer.
-chapter_header = '<br><table align=center width="75%"><tr><td><h2>'
-chapter_inter  = '</h2><ul class="empty"><li>'
-chapter_footer = '</li></ul></td></tr></table>'
+chapter_header = """\
+<div class="section">
+<h2>\
+"""
+chapter_inter  = '</h2>'
+chapter_footer = '</div>'
 
 # Index footer.
 index_footer_start = """\
 <hr>
-<table><tr><td width="100%"></td>
-<td><font size=-2>[<a href="\
+<table class="index-toc-link"><tr><td class="right">[<a href="\
 """
 index_footer_end = """\
-">TOC</a>]</font></td></tr></table>
+">TOC</a>]</td></tr></table>
 """
 
 # TOC footer.
 toc_footer_start = """\
 <hr>
-<table><tr><td><font size=-2>[<a href="\
+<table class="index-toc-link"><tr><td class="left">[<a href="\
 """
 toc_footer_end = """\
-">Index</a>]</font></td>
-<td width="100%"></td>
-</tr></table>
+">Index</a>]</td></tr></table>
 """
 
 
-# source language keyword coloration/styling
+# Source language keyword coloration and styling.
 keyword_prefix = '<span class="keyword">'
 keyword_suffix = '</span>'
 
@@ -166,66 +242,78 @@ section_synopsis_header = '<h2>Synopsis</h2>'
 section_synopsis_footer = ''
 
 
-# Translate a single line of source to HTML.  This will convert
-# a "<" into "&lt.", ">" into "&gt.", etc.
+# Translate a single line of source to HTML.  This converts `<', `>', and
+# `&' into `&lt;',`&gt;', and `&amp;'.
+#
 def  html_quote( line ):
-    result = string.replace( line, "&", "&amp;" )
-    result = string.replace( result, "<", "&lt;" )
-    result = string.replace( result, ">", "&gt;" )
+    result = string.replace( line,   "&", "&amp;" )
+    result = string.replace( result, "<", "&lt;"  )
+    result = string.replace( result, ">", "&gt;"  )
     return result
 
 
-
+################################################################
+##
+##  HTML FORMATTER CLASS
+##
 class  HtmlFormatter( Formatter ):
 
     def  __init__( self, processor, project_title, file_prefix ):
         Formatter.__init__( self, processor )
 
-        global html_header_1, html_header_2, html_header_3
-        global html_header_4, html_header_5, html_footer
+        global html_header_1
+        global html_header_2
+        global html_header_3l, html_header_3r
+        global html_header_4
+        global html_header_5t, html_header_5i
+        global html_header_6
+        global html_footer
 
         if file_prefix:
             file_prefix = file_prefix + "-"
         else:
             file_prefix = ""
 
-        self.headers           = processor.headers
-        self.project_title     = project_title
-        self.file_prefix       = file_prefix
-        self.html_header       = html_header_1 + project_title +              \
-                                 html_header_2 +                              \
-                                 html_header_3 + file_prefix + "index.html" + \
-                                 html_header_4 + file_prefix + "toc.html" +   \
-                                 html_header_5 + project_title +              \
-                                 html_header_6
-
-        self.html_index_header = html_header_1 + project_title +             \
-                                 html_header_2 +                             \
-                                 html_header_3i + file_prefix + "toc.html" + \
-                                 html_header_5 + project_title +             \
-                                 html_header_6
-
-        self.html_toc_header   = html_header_1 + project_title +              \
-                                 html_header_2 +                              \
-                                 html_header_3 + file_prefix + "index.html" + \
-                                 html_header_5t + project_title +             \
-                                 html_header_6
-
-        self.html_footer       = "<center><font size=""-2"">generated on " +     \
-                                 time.asctime( time.localtime( time.time() ) ) + \
-                                 "</font></center>" + html_footer
+        self.headers       = processor.headers
+        self.project_title = project_title
+        self.file_prefix   = file_prefix
+        self.html_header   = (
+          html_header_1 + project_title
+          + html_header_2
+          + html_header_3l + file_prefix + "index.html"
+          + html_header_4 + file_prefix + "toc.html"
+          + html_header_5t + project_title
+          + html_header_6 )
+        self.html_index_header = (
+          html_header_1 + project_title
+          + html_header_2
+          + html_header_3r + file_prefix + "toc.html"
+          + html_header_5t + project_title
+          + html_header_6 )
+        self.html_toc_header = (
+          html_header_1 + project_title
+          + html_header_2
+          + html_header_3l + file_prefix + "index.html"
+          + html_header_5i + project_title
+          + html_header_6 )
+        self.html_footer = (
+          '<div class="timestamp">generated on '
+          + time.asctime( time.localtime( time.time() ) )
+          + "</div>" + html_footer )
 
         self.columns = 3
 
     def  make_section_url( self, section ):
         return self.file_prefix + section.name + ".html"
 
-    def  make_block_url( self, block ):
-        return self.make_section_url( block.section ) + "#" + block.name
+    def  make_block_url( self, block, name = None ):
+        if name == None:
+            name = block.name
+        return self.make_section_url( block.section ) + "#" + name
 
     def  make_html_word( self, word ):
-        """analyze a simple word to detect cross-references and styling"""
-        # look for cross-references
+        """Analyze a simple word to detect cross-references and markup."""
+        # handle cross-references
         m = re_crossref.match( word )
         if m:
             try:
@@ -236,27 +324,28 @@ class  HtmlFormatter( Formatter ):
                 return '<a href="' + url + '">' + name + '</a>' + rest
             except:
                 # we detected a cross-reference to an unknown item
-                sys.stderr.write( \
-                   "WARNING: undefined cross reference '" + name + "'.\n" )
+                sys.stderr.write( "WARNING: undefined cross reference"
+                                  + " '" + name + "'.\n" )
                 return '?' + name + '?' + rest
 
-        # look for italics and bolds
+        # handle markup for italic and bold
         m = re_italic.match( word )
         if m:
             name = m.group( 1 )
-            rest = m.group( 3 )
+            rest = m.group( 2 )
             return '<i>' + name + '</i>' + rest
 
         m = re_bold.match( word )
         if m:
             name = m.group( 1 )
-            rest = m.group( 3 )
+            rest = m.group( 2 )
             return '<b>' + name + '</b>' + rest
 
         return html_quote( word )
 
     def  make_html_para( self, words ):
-        """ convert words of a paragraph into tagged HTML text, handle xrefs """
+        """Convert words of a paragraph into tagged HTML text.  Also handle
+           cross references."""
         line = ""
         if words:
             line = self.make_html_word( words[0] )
@@ -265,8 +354,8 @@ class  HtmlFormatter( Formatter ):
             # handle hyperlinks
             line = re_url.sub( r'<a href="\1">\1</a>', line )
             # convert `...' quotations into real left and right single quotes
-            line = re.sub( r"(^|\W)`(.*?)'(\W|$)",  \
-                           r'\1&lsquo;\2&rsquo;\3', \
+            line = re.sub( r"(^|\W)`(.*?)'(\W|$)",
+                           r'\1&lsquo;\2&rsquo;\3',
                            line )
             # convert tilde into non-breakable space
             line = string.replace( line, "~", "&nbsp;" )
@@ -274,7 +363,7 @@ class  HtmlFormatter( Formatter ):
         return para_header + line + para_footer
 
     def  make_html_code( self, lines ):
-        """ convert a code sequence to HTML """
+        """Convert a code sequence to HTML."""
         line = code_header + '\n'
         for l in lines:
             line = line + html_quote( l ) + '\n'
@@ -282,7 +371,7 @@ class  HtmlFormatter( Formatter ):
         return line + code_footer
 
     def  make_html_items( self, items ):
-        """ convert a field's content into some valid HTML """
+        """Convert a field's content into HTML."""
         lines = []
         for item in items:
             if item.lines:
@@ -297,7 +386,9 @@ class  HtmlFormatter( Formatter ):
 
     def  print_html_field( self, field ):
         if field.name:
-            print "<table><tr valign=top><td><b>" + field.name + "</b></td><td>"
+            print( '<table><tr valign="top"><td><b>'
+                   + field.name
+                   + "</b></td><td>" )
 
         print self.make_html_items( field.items )
 
@@ -318,12 +409,24 @@ class  HtmlFormatter( Formatter ):
                     result = result + prefix + '<b>' + name + '</b>'
                 elif re_source_keywords.match( name ):
                     # this is a C keyword
-                    result = result + prefix + keyword_prefix + name + keyword_suffix
-                elif self.identifiers.has_key( name ):
+                    result = ( result + prefix
+                               + keyword_prefix + name + keyword_suffix )
+                elif name in self.identifiers:
                     # this is a known identifier
                     block = self.identifiers[name]
-                    result = result + prefix + '<a href="' + \
-                             self.make_block_url( block ) + '">' + name + '</a>'
+                    id = block.name
+
+                    # link to a field ID if possible
+                    for markup in block.markups:
+                        if markup.tag == 'values':
+                            for field in markup.fields:
+                                if field.name:
+                                    id = name
+
+                    result = ( result + prefix
+                               + '<a href="'
+                               + self.make_block_url( block, id )
+                               + '">' + name + '</a>' )
                 else:
                     result = result + html_quote( line[:length] )
 
@@ -335,15 +438,11 @@ class  HtmlFormatter( Formatter ):
         return result
 
     def  print_html_field_list( self, fields ):
-        print "<p></p>"
-        print "<table cellpadding=3 border=0>"
+        print '<table class="fields">'
         for field in fields:
-            if len( field.name ) > 22:
-              print "<tr valign=top><td colspan=0><b>" + field.name + "</b></td></tr>"
-              print "<tr valign=top><td></td><td>"
-            else:
-              print "<tr valign=top><td><b>" + field.name + "</b></td><td>"
-
+            print ( '<tr><td class="val" id="' + field.name + '">'
+                    + field.name
+                    + '</td><td class="desc">' )
             self.print_html_items( field.items )
             print "</td></tr>"
         print "</table>"
@@ -352,10 +451,9 @@ class  HtmlFormatter( Formatter ):
         table_fields = []
         for field in markup.fields:
             if field.name:
-                # we begin a new series of field or value definitions, we
-                # will record them in the 'table_fields' list before outputting
-                # all of them as a single table
-                #
+                # We begin a new series of field or value definitions.  We
+                # record them in the `table_fields' list before outputting
+                # all of them as a single table.
                 table_fields.append( field )
             else:
                 if table_fields:
@@ -368,7 +466,7 @@ class  HtmlFormatter( Formatter ):
             self.print_html_field_list( table_fields )
 
     #
-    #  Formatting the index
+    # formatting the index
     #
     def  index_enter( self ):
         print self.html_index_header
@@ -380,11 +478,11 @@ class  HtmlFormatter( Formatter ):
         self.index_items[name] = url
 
     def  index_exit( self ):
-        # block_index already contains the sorted list of index names
+        # `block_index' already contains the sorted list of index names
         count = len( self.block_index )
-        rows  = ( count + self.columns - 1 ) / self.columns
+        rows  = ( count + self.columns - 1 ) // self.columns
 
-        print "<table align=center border=0 cellpadding=0 cellspacing=0>"
+        print '<table class="index">'
         for r in range( rows ):
             line = "<tr>"
             for c in range( self.columns ):
@@ -392,7 +490,8 @@ class  HtmlFormatter( Formatter ):
                 if i < count:
                     bname = self.block_index[r + c * rows]
                     url   = self.index_items[bname]
-                    line = line + '<td><a href="' + url + '">' + bname + '</a></td>'
+                    line  = ( line + '<td><a href="' + url + '">'
+                              + bname + '</a></td>' )
                 else:
                     line = line + '<td></td>'
             line = line + "</tr>"
@@ -400,9 +499,9 @@ class  HtmlFormatter( Formatter ):
 
         print "</table>"
 
-        print index_footer_start +            \
-              self.file_prefix + "toc.html" + \
-              index_footer_end
+        print( index_footer_start
+               + self.file_prefix + "toc.html"
+               + index_footer_end )
 
         print self.html_footer
 
@@ -415,21 +514,20 @@ class  HtmlFormatter( Formatter ):
         Formatter.index_dump( self, index_filename )
 
     #
-    #  Formatting the table of content
+    # formatting the table of contents
     #
     def  toc_enter( self ):
         print self.html_toc_header
-        print "<center><h1>Table of Contents</h1></center>"
+        print "<h1>Table of Contents</h1>"
 
     def  toc_chapter_enter( self, chapter ):
-        print  chapter_header + string.join( chapter.title ) + chapter_inter
-        print "<table cellpadding=5>"
+        print chapter_header + string.join( chapter.title ) + chapter_inter
+        print '<table class="toc">'
 
     def  toc_section_enter( self, section ):
-        print '<tr valign=top><td class="left">'
-        print '<a href="' + self.make_section_url( section ) + '">' + \
-               section.title + '</a></td><td>'
-
+        print ( '<tr><td class="link">'
+                + '<a href="' + self.make_section_url( section ) + '">'
+                + section.title + '</a></td><td class="desc">' )
         print self.make_html_para( section.abstract )
 
     def  toc_section_exit( self, section ):
@@ -440,14 +538,14 @@ class  HtmlFormatter( Formatter ):
         print chapter_footer
 
     def  toc_index( self, index_filename ):
-        print chapter_header +                                      \
-              '<a href="' + index_filename + '">Global Index</a>' + \
-              chapter_inter + chapter_footer
+        print( chapter_header
+               + '<a href="' + index_filename + '">Global Index</a>'
+               + chapter_inter + chapter_footer )
 
     def  toc_exit( self ):
-        print toc_footer_start +                \
-              self.file_prefix + "index.html" + \
-              toc_footer_end
+        print( toc_footer_start
+               + self.file_prefix + "index.html"
+               + toc_footer_end )
 
         print self.html_footer
 
@@ -461,14 +559,12 @@ class  HtmlFormatter( Formatter ):
         Formatter.toc_dump( self, toc_filename, index_filename )
 
     #
-    #  Formatting sections
+    # formatting sections
     #
     def  section_enter( self, section ):
         print self.html_header
 
-        print section_title_header
-        print section.title
-        print section_title_footer
+        print section_title_header + section.title + section_title_footer
 
         maxwidth = 0
         for b in section.blocks.values():
@@ -476,32 +572,43 @@ class  HtmlFormatter( Formatter ):
                 maxwidth = len( b.name )
 
         width = 70  # XXX magic number
-        if maxwidth <> 0:
+        if maxwidth > 0:
             # print section synopsis
             print section_synopsis_header
-            print "<table align=center cellspacing=5 cellpadding=0 border=0>"
+            print '<table class="synopsis">'
 
-            columns = width / maxwidth
+            columns = width // maxwidth
             if columns < 1:
                 columns = 1
 
             count = len( section.block_names )
-            rows  = ( count + columns - 1 ) / columns
+            # don't handle last entry if it is empty
+            if section.block_names[-1] == "/empty/":
+                count -= 1
+            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>'
+                    line = line + '<td>'
                     if i < count:
                         name = section.block_names[i]
-                        line = line + '<a href="#' + name + '">' + name + '</a>'
+                        if name == "/empty/":
+                            # it can happen that a complete row is empty, and
+                            # without a proper `filler' the browser might
+                            # collapse the row to a much smaller height (or
+                            # even omit it completely)
+                            line = line + "&nbsp;"
+                        else:
+                            line = ( line + '<a href="#' + name + '">'
+                                     + name + '</a>' )
 
                     line = line + '</td>'
                 line = line + "</tr>"
                 print line
 
-            print "</table><br><br>"
+            print "</table>"
             print section_synopsis_footer
 
         print description_header
@@ -513,7 +620,7 @@ class  HtmlFormatter( Formatter ):
 
         # place html anchor if needed
         if block.name:
-            print '<h4><a name="' + block.name + '">' + block.name + '</a></h4>'
+            print( '<h3 id="' + block.name + '">' + block.name + '</h3>' )
 
         # dump the block C source lines now
         if block.code:
@@ -521,16 +628,17 @@ class  HtmlFormatter( Formatter ):
             for f in self.headers.keys():
                 if block.source.filename.find( f ) >= 0:
                     header = self.headers[f] + ' (' + f + ')'
-                    break;
+                    break
 
 #           if not header:
-#               sys.stderr.write( \
-#                 'WARNING: No header macro for ' + block.source.filename + '.\n' )
+#               sys.stderr.write(
+#                 "WARNING: No header macro for"
+#                 + " '" + block.source.filename + "'.\n" )
 
             if header:
-                print header_location_header
-                print 'Defined in ' + header + '.'
-                print header_location_footer
+                print ( header_location_header
+                        + 'Defined in ' + header + '.'
+                        + header_location_footer )
 
             print source_header
             for l in block.code:
@@ -552,15 +660,16 @@ class  HtmlFormatter( Formatter ):
             print marker_footer
 
     def  block_exit( self, block ):
-        print block_footer_start + self.file_prefix + "index.html" + \
-              block_footer_middle + self.file_prefix + "toc.html" +  \
-              block_footer_end
+        print( block_footer_start + self.file_prefix + "index.html"
+               + block_footer_middle + self.file_prefix + "toc.html"
+               + block_footer_end )
 
     def  section_exit( self, section ):
         print html_footer
 
     def  section_dump_all( self ):
         for section in self.sections:
-            self.section_dump( section, self.file_prefix + section.name + '.html' )
+            self.section_dump( section,
+                               self.file_prefix + section.name + '.html' )
 
 # eof
diff --git a/freetype/src/tools/docmaker/utils.py b/freetype/src/tools/docmaker/utils.py
index 1d96658c7..b35823ab7 100644
--- a/freetype/src/tools/docmaker/utils.py
+++ b/freetype/src/tools/docmaker/utils.py
@@ -1,48 +1,42 @@
-#  Utils (c) 2002, 2004, 2007, 2008  David Turner <david@freetype.org>
 #
-
-import string, sys, os, glob
-
-# current output directory
+#  utils.py
 #
-output_dir = None
-
-
-# This function is used to sort the index.  It is a simple lexicographical
-# sort, except that it places capital letters before lowercase ones.
+#    Auxiliary functions for the `docmaker' tool (library file).
 #
-def  index_sort( s1, s2 ):
-    if not s1:
-        return -1
-
-    if not s2:
-        return 1
-
-    l1 = len( s1 )
-    l2 = len( s2 )
-    m1 = string.lower( s1 )
-    m2 = string.lower( s2 )
+#  Copyright 2002, 2004, 2007, 2008, 2014 by
+#  David Turner.
+#
+#  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.
 
-    for i in range( l1 ):
-        if i >= l2 or m1[i] > m2[i]:
-            return 1
 
-        if m1[i] < m2[i]:
-            return -1
+import string, sys, os, glob, itertools
 
-        if s1[i] < s2[i]:
-            return -1
 
-        if s1[i] > s2[i]:
-            return 1
+# current output directory
+#
+output_dir = None
 
-    if l2 > l1:
-        return -1
 
-    return 0
+# A function that generates a sorting key.  We want lexicographical order
+# (primary key) except that capital letters are sorted before lowercase
+# ones (secondary key).
+#
+# The primary key is implemented by lowercasing the input.  The secondary
+# key is simply the original data appended, character by character.  For
+# example, the sort key for `FT_x' is `fFtT__xx', while the sort key for
+# `ft_X' is `fftt__xX'.  Since ASCII codes of uppercase letters are
+# numerically smaller than the codes of lowercase letters, `fFtT__xx' gets
+# sorted before `fftt__xX'.
+#
+def  index_key( s ):
+    return string.join( itertools.chain( *zip( s.lower(), s ) ) )
 
 
-# Sort input_list, placing the elements of order_list in front.
+# Sort `input_list', placing the elements of `order_list' in front.
 #
 def  sort_order_list( input_list, order_list ):
     new_list = order_list[:]
@@ -52,9 +46,9 @@ def  sort_order_list( input_list, order_list ):
     return new_list
 
 
-# Open the standard output to a given project documentation file.  Use
-# "output_dir" to determine the filename location if necessary and save the
-# old stdout in a tuple that is returned by this function.
+# Divert standard output to a given project documentation file.  Use
+# `output_dir' to determine the filename location if necessary and save the
+# old stdout handle in a tuple that is returned by this function.
 #
 def  open_output( filename ):
     global output_dir
@@ -69,7 +63,7 @@ def  open_output( filename ):
     return ( new_file, old_stdout )
 
 
-# Close the output that was returned by "close_output".
+# Close the output that was returned by `open_output'.
 #
 def  close_output( output ):
     output[0].close()
@@ -83,15 +77,16 @@ def  check_output():
     if output_dir:
         if output_dir != "":
             if not os.path.isdir( output_dir ):
-                sys.stderr.write( "argument" + " '" + output_dir + "' " + \
-                                  "is not a valid directory" )
+                sys.stderr.write( "argument"
+                                  + " '" + output_dir + "' "
+                                  + "is not a valid directory" )
                 sys.exit( 2 )
         else:
             output_dir = None
 
 
 def  file_exists( pathname ):
-    """checks that a given file exists"""
+    """Check that a given file exists."""
     result = 1
     try:
         file = open( pathname, "r" )
@@ -104,12 +99,12 @@ def  file_exists( pathname ):
 
 
 def  make_file_list( args = None ):
-    """builds a list of input files from command-line arguments"""
+    """Build a list of input files from command-line arguments."""
     file_list = []
     # sys.stderr.write( repr( sys.argv[1 :] ) + '\n' )
 
     if not args:
-        args = sys.argv[1 :]
+        args = sys.argv[1:]
 
     for pathname in args:
         if string.find( pathname, '*' ) >= 0:
-- 
cgit v1.2.3