From 195728d5ba38f34fb2c2c20807c01656f2f59b66 Mon Sep 17 00:00:00 2001 From: Nikhil Ramakrishnan Date: Sat, 25 Aug 2018 12:17:30 +0530 Subject: [PATCH] * src/tools/docmaker: Remove `docmaker'. `Docmaker' has now upgraded to `docwriter', a pip package available at https://pypi.org/project/docwriter/ --- src/tools/docmaker/.gitignore | 1 - src/tools/docmaker/content.py | 672 ----------------------------- src/tools/docmaker/docbeauty.py | 111 ----- src/tools/docmaker/docmaker.py | 115 ----- src/tools/docmaker/formatter.py | 228 ---------- src/tools/docmaker/sources.py | 410 ------------------ src/tools/docmaker/tohtml.py | 726 -------------------------------- src/tools/docmaker/utils.py | 127 ------ 8 files changed, 2390 deletions(-) delete mode 100644 src/tools/docmaker/.gitignore delete mode 100644 src/tools/docmaker/content.py delete mode 100644 src/tools/docmaker/docbeauty.py delete mode 100644 src/tools/docmaker/docmaker.py delete mode 100644 src/tools/docmaker/formatter.py delete mode 100644 src/tools/docmaker/sources.py delete mode 100644 src/tools/docmaker/tohtml.py delete mode 100644 src/tools/docmaker/utils.py diff --git a/src/tools/docmaker/.gitignore b/src/tools/docmaker/.gitignore deleted file mode 100644 index 0d20b6487..000000000 --- a/src/tools/docmaker/.gitignore +++ /dev/null @@ -1 +0,0 @@ -*.pyc diff --git a/src/tools/docmaker/content.py b/src/tools/docmaker/content.py deleted file mode 100644 index 198780aee..000000000 --- a/src/tools/docmaker/content.py +++ /dev/null @@ -1,672 +0,0 @@ -# -# content.py -# -# Parse comment blocks to build content blocks (library file). -# -# Copyright 2002-2018 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 * - -import string, re - - -# -# 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 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*$" ) - - -# -# A regular expression to isolate identifiers from other text. Two syntax -# forms are supported: -# -# -# [] -# -# where both `' and `' consist of alphanumeric characters, `_', -# and `-'. Use `' if there are multiple, valid `' entries; in the -# index, `' will be appended in parentheses. -# -# For example, -# -# stem_darkening[autofit] -# -# becomes `stem_darkening (autofit)' in the index. -# -re_identifier = re.compile( r""" - ((?:\w|-)+ - (?:\[(?:\w|-)+\])?) - """, re.VERBOSE ) - - -# -# We collect macro names ending in `_H' (group 1), as defined in -# `freetype/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. -# -# Example: -# -# #define FT_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 
 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 ):
-        self.lines = []
-        self.words = None
-
-        # remove margin spaces
-        for l in lines:
-            if string.strip( l[:margin] ) == "":
-                l = l[margin:]
-            self.lines.append( l )
-
-    def  dump( self, prefix = "", width = 60 ):
-        lines = self.dump_lines( 0, width )
-        for l in lines:
-            print( prefix + l )
-
-    def  dump_lines( self, margin = 0, width = 60 ):
-        result = []
-        for l in self.lines:
-            result.append( " " * margin + l )
-        return result
-
-
-
-################################################################
-##
-##  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 ):
-        self.lines = None
-        self.words = []
-        for l in lines:
-            l = string.strip( l )
-            self.words.extend( string.split( l ) )
-
-    def  dump( self, prefix = "", width = 60 ):
-        lines = self.dump_lines( 0, width )
-        for l in lines:
-            print( prefix + l )
-
-    def  dump_lines( self, margin = 0, width = 60 ):
-        cur    = ""  # current line
-        col    = 0   # current width
-        result = []
-
-        for word in self.words:
-            ln = len( word )
-            if col > 0:
-                ln = ln + 1
-
-            if col + ln > width:
-                result.append( " " * margin + cur )
-                cur = word
-                col = len( word )
-            else:
-                if col > 0:
-                    cur = cur + " "
-                cur = cur + word
-                col = col + ln
-
-        if col > 0:
-            result.append( " " * margin + cur )
-
-        return result
-
-
-################################################################
-##
-##  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.items = []    # list of items
-
-        mode_none  = 0     # start parsing mode
-        mode_code  = 1     # parsing code sequences
-        mode_para  = 3     # parsing normal paragraph
-
-        margin     = -1    # current code sequence indentation
-        cur_lines  = []
-
-        # 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?
-            if mode == mode_code:
-                m = re_code_end.match( l )
-                if m and len( m.group( 1 ) ) <= margin:
-                    # that's it, we finished the code sequence
-                    code = DocCode( 0, cur_lines )
-                    self.items.append( code )
-                    margin    = -1
-                    cur_lines = []
-                    mode      = mode_none
-                else:
-                    # otherwise continue the code sequence
-                    cur_lines.append( l[margin:] )
-            else:
-                # start of code sequence?
-                m = re_code_start.match( l )
-                if m:
-                    # save current lines
-                    if cur_lines:
-                        para = DocPara( cur_lines )
-                        self.items.append( para )
-                        cur_lines = []
-
-                    # switch to code extraction mode
-                    margin = len( m.group( 1 ) )
-                    mode   = mode_code
-                else:
-                    if not string.split( l ) and cur_lines:
-                        # if the line is empty, we end the current paragraph,
-                        # if any
-                        para = DocPara( cur_lines )
-                        self.items.append( para )
-                        cur_lines = []
-                    else:
-                        # otherwise, simply add the line to the current
-                        # paragraph
-                        cur_lines.append( l )
-
-        if mode == mode_code:
-            # unexpected end of code sequence
-            code = DocCode( margin, cur_lines )
-            self.items.append( code )
-        elif cur_lines:
-            para = DocPara( cur_lines )
-            self.items.append( para )
-
-    def  dump( self, prefix = "" ):
-        if self.field:
-            print( prefix + self.field + " ::" )
-            prefix = prefix + "----"
-
-        first = 1
-        for p in self.items:
-            if not first:
-                print( "" )
-            p.dump( prefix )
-            first = 0
-
-    def  dump_lines( self, margin = 0, width = 60 ):
-        result = []
-        nl     = None
-
-        for p in self.items:
-            if nl:
-                result.append( "" )
-
-            result.extend( p.dump_lines( margin, width ) )
-            nl = 1
-
-        return result
-
-
-#
-# 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 ):
-        self.tag    = string.lower( tag )
-        self.fields = []
-
-        cur_lines = []
-        field     = None
-        mode      = 0
-
-        for l in lines:
-            m = re_field.match( l )
-            if m:
-                # We detected the start of a new field definition.
-
-                # first, save the current one
-                if cur_lines:
-                    f = DocField( field, cur_lines )
-                    self.fields.append( f )
-                    cur_lines = []
-                    field     = None
-
-                field     = m.group( 1 )   # record field name
-                ln        = len( m.group( 0 ) )
-                l         = " " * ln + l[ln:]
-                cur_lines = [l]
-            else:
-                cur_lines.append( l )
-
-        if field or cur_lines:
-            f = DocField( field, cur_lines )
-            self.fields.append( f )
-
-    def  get_name( self ):
-        try:
-            return self.fields[0].items[0].words[0]
-        except:
-            return None
-
-    def  dump( self, margin ):
-        print( " " * margin + "<" + self.tag + ">" )
-        for f in self.fields:
-            f.dump( "  " )
-        print( " " * margin + "" )
-
-
-################################################################
-##
-##  DOC CHAPTER CLASS
-##
-class  DocChapter:
-
-    def  __init__( self, block ):
-        self.block    = block
-        self.sections = []
-        if block:
-            self.name  = block.name
-            self.title = block.get_markup_words( "title" )
-            self.order = block.get_markup_words( "sections" )
-        else:
-            self.name  = "Other"
-            self.title = string.split( "Miscellaneous" )
-            self.order = []
-
-
-################################################################
-##
-##  DOC SECTION CLASS
-##
-class  DocSection:
-
-    def  __init__( self, name = "Other" ):
-        self.name        = name
-        self.blocks      = {}
-        self.block_names = []  # ordered block names in section
-        self.defs        = []
-        self.abstract    = ""
-        self.description = ""
-        self.order       = []
-        self.title       = "ERROR"
-        self.chapter     = None
-
-    def  add_def( self, block ):
-        self.defs.append( block )
-
-    def  add_block( self, block ):
-        self.block_names.append( block.name )
-        self.blocks[block.name] = block
-
-    def  process( self ):
-        # look up one block that contains a valid section description
-        for block in self.defs:
-            title = block.get_markup_text( "title" )
-            if title:
-                self.title       = title
-                self.abstract    = block.get_markup_words( "abstract" )
-                self.description = block.get_markup_items( "description" )
-                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."""
-        self.reset()
-
-        self.sections = {}    # dictionary of documentation sections
-        self.section  = None  # current documentation section
-
-        self.chapters = []    # list of chapters
-
-        self.headers  = {}    # dictionary of header macros
-
-    def  set_section( self, 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
-        else:
-            self.section = self.sections[section_name]
-
-    def  add_chapter( self, block ):
-        chapter = DocChapter( block )
-        self.chapters.append( chapter )
-
-    def  reset( self ):
-        """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."""
-        if self.markup and self.markup_lines:
-
-            # get rid of last line of markup if it's empty
-            marks = self.markup_lines
-            if len( marks ) > 0 and not string.strip( marks[-1] ):
-                self.markup_lines = marks[:-1]
-
-            m = DocMarkup( self.markup, self.markup_lines )
-
-            self.markups.append( m )
-
-            self.markup       = None
-            self.markup_lines = []
-
-    def  process_content( self, content ):
-        """Process a block content and return a list of DocMarkup objects
-           corresponding to it."""
-        markup       = None
-        markup_lines = []
-        first        = 1
-
-        margin  = -1
-        in_code = 0
-
-        for line in content:
-            if in_code:
-                m = re_code_end.match( line )
-                if m and len( m.group( 1 ) ) <= margin:
-                    in_code = 0
-                    margin  = -1
-            else:
-                m = re_code_start.match( line )
-                if m:
-                    in_code = 1
-                    margin  = len( m.group( 1 ) )
-
-            found = None
-
-            if not in_code:
-                for t in re_markup_tags:
-                    m = t.match( line )
-                    if m:
-                        found  = string.lower( m.group( 1 ) )
-                        prefix = len( m.group( 0 ) )
-                        # remove markup from line
-                        line   = " " * prefix + line[prefix:]
-                        break
-
-            # is it the start of a new markup section ?
-            if found:
-                first = 0
-                self.add_markup()  # add current markup content
-                self.markup = found
-                if len( string.strip( line ) ) > 0:
-                    self.markup_lines.append( line )
-            elif first == 0:
-                self.markup_lines.append( line )
-
-        self.add_markup()
-
-        return self.markups
-
-    def  parse_sources( self, source_processor ):
-        blocks = source_processor.blocks
-        count  = len( blocks )
-
-        for n in range( count ):
-            source = blocks[n]
-            if source.content:
-                # this is a documentation comment, we need to catch
-                # all following normal blocks in the "follow" list
-                #
-                follow = []
-                m = n + 1
-                while m < count and not blocks[m].content:
-                    follow.append( blocks[m] )
-                    m = m + 1
-
-                doc_block = DocBlock( source, follow, self )
-
-    def  finish( self ):
-        # process all sections to extract their abstract, description
-        # and ordered list of items
-        #
-        for sec in self.sections.values():
-            sec.process()
-
-        # process chapters to check that all sections are correctly
-        # listed there
-        for chap in self.chapters:
-            for sec in chap.order:
-                if sec in self.sections:
-                    section = self.sections[sec]
-                    section.chapter = chap
-                    section.reorder()
-                    chap.sections.append( section )
-                else:
-                    sys.stderr.write( "WARNING: chapter '" +          \
-                        chap.name + "' in " + chap.block.location() + \
-                        " lists unknown section '" + sec + "'\n" )
-
-        # check that all sections are in a chapter
-        #
-        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
-        # when necessary
-        #
-        if others:
-            chap = DocChapter( None )
-            chap.sections = others
-            self.chapters.append( chap )
-
-
-################################################################
-##
-##  DOC BLOCK CLASS
-##
-class  DocBlock:
-
-    def  __init__( self, source, follow, processor ):
-        processor.reset()
-
-        self.source  = source
-        self.code    = []
-        self.type    = "ERRTYPE"
-        self.name    = "ERRNAME"
-        self.section = processor.section
-        self.markups = processor.process_content( source.content )
-
-        # compute block type from first markup tag
-        try:
-            self.type = self.markups[0].tag
-        except:
-            pass
-
-        # compute block name from first markup paragraph
-        try:
-            markup = self.markups[0]
-            para   = markup.fields[0].items[0]
-            name   = para.words[0]
-            m = re_identifier.match( name )
-            if m:
-                name = m.group( 1 )
-            self.name = name
-        except:
-            pass
-
-        if self.type == "section":
-            # detect new section starts
-            processor.set_section( self.name )
-            processor.section.add_def( self )
-        elif self.type == "chapter":
-            # detect new chapter
-            processor.add_chapter( self )
-        else:
-            processor.section.add_block( self )
-
-        # now, compute the source lines relevant to this documentation
-        # block. We keep normal comments in for obvious reasons (??)
-        source = []
-        for b in follow:
-            if b.format:
-                break
-            for l in b.lines:
-                # collect header macro definitions
-                m = re_header_macro.match( l )
-                if m:
-                    processor.headers[m.group( 2 )] = m.group( 1 );
-
-                # we use "/* */" as a separator
-                if re_source_sep.match( l ):
-                    break
-                source.append( l )
-
-        # now strip the leading and trailing empty lines from the sources
-        start = 0
-        end   = len( source ) - 1
-
-        while start < end and not string.strip( source[start] ):
-            start = start + 1
-
-        while start < end and not string.strip( source[end] ):
-            end = end - 1
-
-        if start == end and not string.strip( source[start] ):
-            self.code = []
-        else:
-            self.code = source[start:end + 1]
-
-    def  location( self ):
-        return self.source.location()
-
-    def  get_markup( self, tag_name ):
-        """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
-        return None
-
-    def  get_markup_words( self, tag_name ):
-        try:
-            m = self.get_markup( tag_name )
-            return m.fields[0].items[0].words
-        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 `' 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 )
-
-    def  get_markup_items( self, tag_name ):
-        try:
-            m = self.get_markup( tag_name )
-            return m.fields[0].items
-        except:
-            return None
-
-# eof
diff --git a/src/tools/docmaker/docbeauty.py b/src/tools/docmaker/docbeauty.py
deleted file mode 100644
index 0b021fa6c..000000000
--- a/src/tools/docmaker/docbeauty.py
+++ /dev/null
@@ -1,111 +0,0 @@
-#!/usr/bin/env python
-#
-#  DocBeauty (c) 2003, 2004, 2008 David Turner 
-#
-# This program is used to beautify the documentation comments used
-# in the FreeType 2 public headers.
-#
-
-from sources import *
-from content import *
-from utils   import *
-
-import sys, os, string, getopt
-
-
-content_processor = ContentProcessor()
-
-
-def  beautify_block( block ):
-    if block.content:
-        content_processor.reset()
-
-        markups = content_processor.process_content( block.content )
-        text    = []
-        first   = 1
-
-        for markup in markups:
-            text.extend( markup.beautify( first ) )
-            first = 0
-
-        # now beautify the documentation "borders" themselves
-        lines = [" /*************************************************************************"]
-        for l in text:
-            lines.append( "  *" + l )
-        lines.append( "  */" )
-
-        block.lines = lines
-
-
-def  usage():
-    print( "\nDocBeauty 0.1 Usage information\n" )
-    print( "  docbeauty [options] file1 [file2 ...]\n" )
-    print( "using the following options:\n" )
-    print( "  -h : print this page" )
-    print( "  -b : backup original files with the 'orig' extension" )
-    print( "" )
-    print( "  --backup : same as -b" )
-
-
-def  main( argv ):
-    """main program loop"""
-
-    global output_dir
-
-    try:
-        opts, args = getopt.getopt( sys.argv[1:], \
-                                    "hb",         \
-                                    ["help", "backup"] )
-    except getopt.GetoptError:
-        usage()
-        sys.exit( 2 )
-
-    if args == []:
-        usage()
-        sys.exit( 1 )
-
-    # process options
-    #
-    output_dir = None
-    do_backup  = None
-
-    for opt in opts:
-        if opt[0] in ( "-h", "--help" ):
-            usage()
-            sys.exit( 0 )
-
-        if opt[0] in ( "-b", "--backup" ):
-            do_backup = 1
-
-    # create context and processor
-    source_processor = SourceProcessor()
-
-    # retrieve the list of files to process
-    file_list = make_file_list( args )
-    for filename in file_list:
-        source_processor.parse_file( filename )
-
-        for block in source_processor.blocks:
-            beautify_block( block )
-
-        new_name = filename + ".new"
-        ok       = None
-
-        try:
-            file = open( new_name, "wt" )
-            for block in source_processor.blocks:
-                for line in block.lines:
-                    file.write( line )
-                    file.write( "\n" )
-            file.close()
-        except:
-            ok = 0
-
-
-# if called from the command line
-#
-if __name__ == '__main__':
-    main( sys.argv )
-
-
-# eof
diff --git a/src/tools/docmaker/docmaker.py b/src/tools/docmaker/docmaker.py
deleted file mode 100644
index eb49afb0a..000000000
--- a/src/tools/docmaker/docmaker.py
+++ /dev/null
@@ -1,115 +0,0 @@
-#!/usr/bin/env python
-#
-#  docmaker.py
-#
-#    Convert source code markup to HTML documentation.
-#
-#  Copyright 2002-2018 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 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 *
-from content   import *
-from utils     import *
-from formatter import *
-from tohtml    import *
-
-import utils
-
-import sys, glob, getopt
-
-
-def  usage():
-    print( "\nDocMaker Usage information\n" )
-    print( "  docmaker [options] file1 [file2 ...]\n" )
-    print( "using the following options:\n" )
-    print( "  -h : print this page" )
-    print( "  -t : set project title, as in '-t \"My Project\"'" )
-    print( "  -o : set output directory, as in '-o mydir'" )
-    print( "  -p : set documentation prefix, as in '-p ft2'" )
-    print( "" )
-    print( "  --title  : same as -t, as in '--title=\"My Project\"'" )
-    print( "  --output : same as -o, as in '--output=mydir'" )
-    print( "  --prefix : same as -p, as in '--prefix=ft2'" )
-
-
-def  main( argv ):
-    """Main program loop."""
-
-    global output_dir
-
-    try:
-        opts, args = getopt.getopt( sys.argv[1:],
-                                    "ht:o:p:",
-                                    ["help", "title=", "output=", "prefix="] )
-    except getopt.GetoptError:
-        usage()
-        sys.exit( 2 )
-
-    if args == []:
-        usage()
-        sys.exit( 1 )
-
-    # process options
-    project_title  = "Project"
-    project_prefix = None
-    output_dir     = None
-
-    for opt in opts:
-        if opt[0] in ( "-h", "--help" ):
-            usage()
-            sys.exit( 0 )
-
-        if opt[0] in ( "-t", "--title" ):
-            project_title = opt[1]
-
-        if opt[0] in ( "-o", "--output" ):
-            utils.output_dir = opt[1]
-
-        if opt[0] in ( "-p", "--prefix" ):
-            project_prefix = opt[1]
-
-    check_output()
-
-    # create context and processor
-    source_processor  = SourceProcessor()
-    content_processor = ContentProcessor()
-
-    # retrieve the list of files to process
-    file_list = make_file_list( args )
-    for filename in file_list:
-        source_processor.parse_file( filename )
-        content_processor.parse_sources( source_processor )
-
-    # process sections
-    content_processor.finish()
-
-    formatter = HtmlFormatter( content_processor,
-                               project_title,
-                               project_prefix )
-
-    formatter.toc_dump()
-    formatter.index_dump()
-    formatter.section_dump_all()
-
-
-# if called from the command line
-if __name__ == '__main__':
-    main( sys.argv )
-
-# eof
diff --git a/src/tools/docmaker/formatter.py b/src/tools/docmaker/formatter.py
deleted file mode 100644
index 2708fd40d..000000000
--- a/src/tools/docmaker/formatter.py
+++ /dev/null
@@ -1,228 +0,0 @@
-#
-#  formatter.py
-#
-#    Convert parsed content blocks to a structured document (library file).
-#
-#  Copyright 2002-2018 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 *
-
-
-################################################################
-##
-##  FORMATTER CLASS
-##
-class  Formatter:
-
-    def  __init__( self, processor ):
-        self.processor   = processor
-        self.identifiers = {}
-        self.chapters    = processor.chapters
-        self.sections    = processor.sections.values()
-        self.block_index = []
-
-        # store all blocks in a dictionary
-        self.blocks = []
-        for section in self.sections:
-            for block in section.blocks.values():
-                self.add_identifier( block.name, block )
-
-                # add enumeration values to the index, since this is useful
-                for markup in block.markups:
-                    if markup.tag == 'values':
-                        for field in markup.fields:
-                            self.add_identifier( field.name, block )
-
-        self.block_index = self.identifiers.keys()
-        self.block_index.sort( key = index_key )
-
-        # also add section names to dictionary (without making them appear
-        # in the index)
-        for section in self.sections:
-            self.add_identifier( section.name, section )
-
-    def  add_identifier( self, name, block ):
-        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" )
-        else:
-            self.identifiers[name] = block
-
-    #
-    # formatting the table of contents
-    #
-    def  toc_enter( self ):
-        pass
-
-    def  toc_chapter_enter( self, chapter ):
-        pass
-
-    def  toc_section_enter( self, section ):
-        pass
-
-    def  toc_section_exit( self, section ):
-        pass
-
-    def  toc_chapter_exit( self, chapter ):
-        pass
-
-    def  toc_index( self, index_filename ):
-        pass
-
-    def  toc_exit( self ):
-        pass
-
-    def  toc_dump( self, toc_filename = None, index_filename = None ):
-        output = None
-        if toc_filename:
-            output = open_output( toc_filename )
-
-        self.toc_enter()
-
-        for chap in self.processor.chapters:
-
-            self.toc_chapter_enter( chap )
-
-            for section in chap.sections:
-                self.toc_section_enter( section )
-                self.toc_section_exit( section )
-
-            self.toc_chapter_exit( chap )
-
-        self.toc_index( index_filename )
-
-        self.toc_exit()
-
-        if output:
-            close_output( output )
-
-    #
-    # formatting the index
-    #
-    def  index_enter( self ):
-        pass
-
-    def  index_name_enter( self, name ):
-        pass
-
-    def  index_name_exit( self, name ):
-        pass
-
-    def  index_exit( self ):
-        pass
-
-    def  index_dump( self, index_filename = None ):
-        output = None
-        if index_filename:
-            output = open_output( index_filename )
-
-        self.index_enter()
-
-        for name in self.block_index:
-            self.index_name_enter( name )
-            self.index_name_exit( name )
-
-        self.index_exit()
-
-        if output:
-            close_output( output )
-
-    #
-    # formatting a section
-    #
-    def  section_enter( self, section ):
-        pass
-
-    def  block_enter( self, block ):
-        pass
-
-    def  markup_enter( self, markup, block = None ):
-        pass
-
-    def  field_enter( self, field, markup = None, block = None ):
-        pass
-
-    def  field_exit( self, field, markup = None, block = None ):
-        pass
-
-    def  markup_exit( self, markup, block = None ):
-        pass
-
-    def  block_exit( self, block ):
-        pass
-
-    def  section_exit( self, section ):
-        pass
-
-    def  section_dump( self, section, section_filename = None ):
-        output = None
-        if section_filename:
-            output = open_output( section_filename )
-
-        self.section_enter( section )
-
-        for name in section.block_names:
-            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!
-                self.markup_enter( markup, block )
-
-                for field in markup.fields:
-                    self.field_enter( field, markup, block )
-                    self.field_exit( field, markup, block )
-
-                self.markup_exit( markup, block )
-
-            self.block_exit( block )
-
-        self.section_exit( section )
-
-        if output:
-            close_output( output )
-
-    def  section_dump_all( self ):
-        for section in self.sections:
-            self.section_dump( section )
-
-# eof
diff --git a/src/tools/docmaker/sources.py b/src/tools/docmaker/sources.py
deleted file mode 100644
index e3b95e0fa..000000000
--- a/src/tools/docmaker/sources.py
+++ /dev/null
@@ -1,410 +0,0 @@
-#
-#  sources.py
-#
-#    Convert source code comments to multi-line blocks (library file).
-#
-#  Copyright 2002-2018 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 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.
-#
-#   - Documentation blocks, which have restricted formatting, and whose text
-#     always start with a documentation markup tag like `',
-#     `', etc.
-#
-# 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, string
-
-
-################################################################
-##
-##  SOURCE BLOCK FORMAT CLASS
-##
-##  A simple class containing compiled regular expressions 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.
-##
-##  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."""
-        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.
-#
-#    /************************************/ (at least 2 asterisks)
-#    /*                                  */
-#    /*                                  */
-#    /*                                  */
-#    /************************************/ (at least 2 asterisks)
-#
-start = r'''
-  \s*      # any number of whitespace
-  /\*{2,}/ # followed by '/' and at least two asterisks then '/'
-  \s*$     # probably followed by whitespace
-'''
-
-column = r'''
-  \s*      # any number of whitespace
-  /\*{1}   # followed by '/' and precisely one asterisk
-  ([^*].*) # followed by anything (group 1)
-  \*{1}/   # followed by one asterisk and a '/'
-  \s*$     # probably followed by whitespace
-'''
-
-re_source_block_format1 = SourceBlockFormat( 1, start, column, start )
-
-
-#
-# Format 2 documentation comment blocks.
-#
-#    /************************************ (at least 2 asterisks)
-#     *
-#     *                                    (1 asterisk)
-#     *
-#     */                                   (1 or more asterisks)
-#
-start = r'''
-  \s*     # any number of whitespace
-  /\*{2,} # followed by '/' and at least two asterisks
-  \s*$    # probably followed by whitespace
-'''
-
-column = r'''
-  \s*           # any number of whitespace
-  \*{1}(?![*/]) # followed by precisely one asterisk not followed by `/'
-  (.*)          # then anything (group1)
-'''
-
-end = r'''
-  \s*  # any number of whitespace
-  \*+/ # followed by at least one asterisk, then '/'
-'''
-
-re_source_block_format2 = SourceBlockFormat( 2, start, column, end )
-
-
-#
-# 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 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 that a markup tag _must_ begin a new paragraph.
-#
-re_markup_tag1 = re.compile( r'''\s*<((?:\w|-)*)>''' )  #  format
-re_markup_tag2 = re.compile( r'''\s*@((?:\w|-)*):''' )  # @xxxx: format
-
-#
-# The list of supported markup tags.  We could add new ones quite easily.
-#
-re_markup_tags = [re_markup_tag1, re_markup_tag2]
-
-
-#
-# A regular expression to detect a cross reference, after markup tags have
-# been stripped off.
-#
-# Two syntax forms are supported:
-#
-#   @
-#   @[]
-#
-# where both `' and `' consist of alphanumeric characters, `_',
-# and `-'.  Use `' if there are multiple, valid `' entries.
-#
-# Example: @foo[bar]
-#
-re_crossref = re.compile( r"""
-                            @
-                            (?P(?:\w|-)+
-                                     (?:\[(?:\w|-)+\])?)
-                            (?P.*)
-                          """, re.VERBOSE )
-
-#
-# 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 characters `_' and `-', 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*
-
-#
-# This regular expression code to identify an URL has been taken from
-#
-#   https://mail.python.org/pipermail/tutor/2002-September/017228.html
-#
-# (with slight modifications).
-#
-urls = r'(?:https?|telnet|gopher|file|wais|ftp)'
-ltrs = r'\w'
-gunk = r'/#~:.?+=&%@!\-'
-punc = r'.:?\-'
-any  = "%(ltrs)s%(gunk)s%(punc)s" % { 'ltrs' : ltrs,
-                                      'gunk' : gunk,
-                                      'punc' : punc }
-url  = r"""
-         (
-           \b                    # start at word boundary
-           %(urls)s :            # need resource and a colon
-           [%(any)s] +?          # followed by one or more of any valid
-                                 # character, but be conservative and
-                                 # take only what you need to...
-           (?=                   # [look-ahead non-consumptive assertion]
-             [%(punc)s]*         # either 0 or more punctuation
-             (?:                 # [non-grouping parentheses]
-               [^%(any)s] | $    # followed by a non-url char
-                                 # or end of the string
-             )
-           )
-         )
-        """ % {'urls' : urls,
-               'any'  : any,
-               'punc' : punc }
-
-re_url = re.compile( url, re.VERBOSE | re.MULTILINE )
-
-#
-# A regular expression that stops collection of comments for the current
-# block.
-#
-re_source_sep = re.compile( r'\s*/\*\s*\*/' )   #  /* */
-
-#
-# 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 regular expression that matches a list of reserved C source keywords.
-#
-re_source_keywords = re.compile( '''\\b ( typedef   |
-                                          struct    |
-                                          enum      |
-                                          union     |
-                                          const     |
-                                          char      |
-                                          int       |
-                                          short     |
-                                          long      |
-                                          void      |
-                                          signed    |
-                                          unsigned  |
-                                          \#include |
-                                          \#define  |
-                                          \#undef   |
-                                          \#if      |
-                                          \#ifdef   |
-                                          \#ifndef  |
-                                          \#else    |
-                                          \#endif   ) \\b''', re.VERBOSE )
-
-
-################################################################
-##
-##  SOURCE BLOCK CLASS
-##
-##  There are two important fields in a `SourceBlock' object.
-##
-##    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)
-##
-class  SourceBlock:
-
-    def  __init__( self, processor, filename, lineno, lines ):
-        self.processor = processor
-        self.filename  = filename
-        self.lineno    = lineno
-        self.lines     = lines[:]
-        self.format    = processor.format
-        self.content   = []
-
-        if self.format == None:
-            return
-
-        words = []
-
-        # extract comment lines
-        lines = []
-
-        for line0 in self.lines:
-            m = self.format.column.match( line0 )
-            if m:
-                lines.append( m.group( 1 ) )
-
-        # now, look for a markup tag
-        for l in lines:
-            l = string.strip( l )
-            if len( l ) > 0:
-                for tag in re_markup_tags:
-                    if tag.match( l ):
-                        self.content = lines
-                        return
-
-    def  location( self ):
-        return "(" + self.filename + ":" + repr( self.lineno ) + ")"
-
-    # debugging only -- not used in normal operations
-    def  dump( self ):
-        if self.content:
-            print( "{{{content start---" )
-            for l in self.content:
-                print( l )
-            print( "---content end}}}" )
-            return
-
-        fmt = ""
-        if self.format:
-            fmt = repr( self.format.id ) + " "
-
-        for line in self.lines:
-            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.
-##
-##  A SourceBlock object consists of the following data.
-##
-##    - A documentation comment block using one of the layouts above.  Its
-##      exact format will be discussed later.
-##
-##    - Normal sources lines, including comments.
-##
-##
-class  SourceProcessor:
-
-    def  __init__( self ):
-        """Initialize a source processor."""
-        self.blocks   = []
-        self.filename = None
-        self.format   = None
-        self.lines    = []
-
-    def  reset( self ):
-        """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."""
-        self.reset()
-
-        self.filename = filename
-
-        fileinput.close()
-        self.format = None
-        self.lineno = 0
-        self.lines  = []
-
-        for line in fileinput.input( filename ):
-            # strip trailing newlines, important on Windows machines!
-            if line[-1] == '\012':
-                line = line[0:-1]
-
-            if self.format == None:
-                self.process_normal_line( line )
-            else:
-                if self.format.end.match( line ):
-                    # 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 ):
-                    # A normal column line.  Add it to `lines'.
-                    self.lines.append( line )
-                else:
-                    # 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
-                    self.process_normal_line( line )
-
-        # record the last lines
-        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."""
-        for f in re_source_block_formats:
-            if f.start.match( line ):
-                self.add_block_lines()
-                self.format = f
-                self.lineno = fileinput.filelineno()
-
-        self.lines.append( line )
-
-    def  add_block_lines( self ):
-        """Add the current accumulated lines and create a new block."""
-        if self.lines != []:
-            block = SourceBlock( self,
-                                 self.filename,
-                                 self.lineno,
-                                 self.lines )
-
-            self.blocks.append( block )
-            self.format = None
-            self.lines  = []
-
-    # debugging only, not used in normal operations
-    def  dump( self ):
-        """Print all blocks in a processor."""
-        for b in self.blocks:
-            b.dump()
-
-# eof
diff --git a/src/tools/docmaker/tohtml.py b/src/tools/docmaker/tohtml.py
deleted file mode 100644
index 97a5459bc..000000000
--- a/src/tools/docmaker/tohtml.py
+++ /dev/null
@@ -1,726 +0,0 @@
-#
-#  tohtml.py
-#
-#    A sub-class container of the `Formatter' class to produce HTML.
-#
-#  Copyright 2002-2018 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 *
-from formatter import *
-
-import time
-
-
-# The following strings define the HTML header used by all generated pages.
-html_header_1 = """\
-
-
-
-
-\
-"""
-
-html_header_2 = """\
- API Reference
-
-
-
-"""
-
-html_header_3l = """
-
[
[Index][TOC]

-
\
-"""
-
-html_header_5i = """\
-">Index]
-
\
-"""
-
-html_header_6 = """\
- API Reference

-"""
-
-
-# The HTML footer used by all generated pages.
-html_footer = """\
-
-\
-"""
-
-# The header and footer used for each section.
-section_title_header1 = '
'
-section_title_footer = "
"
-
-# The header and footer used for code segments.
-code_header = '
'
-code_footer = '
'
-
-# Paragraph header and footer.
-para_header = "
"
-para_footer = "
"
-
-# Block header and footer.
-block_header        = '
'
-block_footer_start  = """\
-

-\
-\
-
[Index][Top][TOC]

-"""
-
-# Description header/footer.
-description_header = ""
-description_footer = ""
-
-# Marker header/inter/footer combination.
-marker_header = "
"
-marker_inter  = "
"
-marker_footer = ""
-
-# Header location header/footer.
-header_location_header = "
"
-header_location_footer = "
"
-
-# Source code extracts header/footer.
-source_header = "
"
-source_footer = "
"
-
-# Chapter header/inter/footer.
-chapter_header = """\
-

-
\
-"""
-chapter_inter  = '
'
-chapter_footer = '
'
-
-# Index footer.
-index_footer_start = """\
-

-
[TOC]

-"""
-
-# TOC footer.
-toc_footer_start = """\
-

-
[Index]

-"""
-
-
-# Source language keyword coloration and styling.
-keyword_prefix = ''
-keyword_suffix = ''
-
-section_synopsis_header = '
Synopsis
'
-section_synopsis_footer = ''
-
-
-# Translate a single line of source to HTML.  This converts `<', `>', and
-# `&' into `<',`>', and `&'.
-#
-def  html_quote( line ):
-    result = string.replace( line,   "&", "&" )
-    result = string.replace( result, "<", "<"  )
-    result = string.replace( result, ">", ">"  )
-    return result
-
-
-################################################################
-##
-##  HTML FORMATTER CLASS
-##
-class  HtmlFormatter( Formatter ):
-
-    def  __init__( self, processor, project_title, file_prefix ):
-        Formatter.__init__( self, processor )
-
-        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_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 = (
-          '
generated on '
-          + time.asctime( time.localtime( time.time() ) )
-          + "
" + html_footer )
-
-        self.columns = 3
-
-    def  make_section_url( self, section ):
-        return self.file_prefix + section.name + ".html"
-
-    def  make_block_url( self, block, name = None ):
-        if name == None:
-            name = block.name
-
-        try:
-            section_url = self.make_section_url( block.section )
-        except:
-            # we already have a section
-            section_url = self.make_section_url( block )
-
-        return section_url + "#" + name
-
-    def  make_html_word( self, word ):
-        """Analyze a simple word to detect cross-references and markup."""
-        # handle cross-references
-        m = re_crossref.match( word )
-        if m:
-            try:
-                name = m.group( 'name' )
-                rest = m.group( 'rest' )
-                block = self.identifiers[name]
-                url   = self.make_block_url( block )
-                # display `foo[bar]' as `foo'
-                name = re.sub( r'\[.*\]', '', name )
-                # normalize url, following RFC 3986
-                url = string.replace( url, "[", "(" )
-                url = string.replace( url, "]", ")" )
-
-                try:
-                    # for sections, display title
-                    url = ( '‘'
-                            + block.title + '’'
-                            + rest )
-                except:
-                    url = ( ''
-                            + name + ''
-                            + rest )
-
-                return url
-            except:
-                # we detected a cross-reference to an unknown item
-                sys.stderr.write( "WARNING: undefined cross reference"
-                                  + " '" + name + "'.\n" )
-                return '?' + name + '?' + rest
-
-        # handle markup for italic and bold
-        m = re_italic.match( word )
-        if m:
-            name = m.group( 1 )
-            rest = m.group( 2 )
-            return '' + name + '' + rest
-
-        m = re_bold.match( word )
-        if m:
-            name = m.group( 1 )
-            rest = m.group( 2 )
-            return '' + name + '' + rest
-
-        return html_quote( word )
-
-    def  make_html_para( self, words ):
-        """Convert words of a paragraph into tagged HTML text.  Also handle
-           cross references."""
-        line = ""
-        if words:
-            line = self.make_html_word( words[0] )
-            for word in words[1:]:
-                line = line + " " + self.make_html_word( word )
-            # handle hyperlinks
-            line = re_url.sub( r'\1', line )
-            # convert `...' quotations into real left and right single quotes
-            line = re.sub( r"(^|\W)`(.*?)'(\W|$)",
-                           r'\1‘\2’\3',
-                           line )
-            # convert tilde into non-breakable space
-            line = string.replace( line, "~", " " )
-
-        return para_header + line + para_footer
-
-    def  make_html_code( self, lines ):
-        """Convert a code sequence to HTML."""
-        line = code_header + '\n'
-        for l in lines:
-            line = line + html_quote( l ).rstrip() + '\n'
-
-        return line + code_footer
-
-    def  make_html_items( self, items ):
-        """Convert a field's content into HTML."""
-        lines = []
-        for item in items:
-            if item.lines:
-                lines.append( self.make_html_code( item.lines ) )
-            else:
-                lines.append( self.make_html_para( item.words ) )
-
-        return string.join( lines, '\n' )
-
-    def  print_html_items( self, items ):
-        print( self.make_html_items( items ) )
-
-    def  print_html_field( self, field ):
-        if field.name:
-            print( '
'
-                   + field.name
-                   + "" )
-
-        print( self.make_html_items( field.items ) )
-
-        if field.name:
-            print( "
" )
-
-    def  html_source_quote( self, line, block_name = None ):
-        result = ""
-        while line:
-            m = re_source_crossref.match( line )
-            if m:
-                name   = m.group( 2 )
-                prefix = html_quote( m.group( 1 ) )
-                length = len( m.group( 0 ) )
-
-                if name == block_name:
-                    # this is the current block name, if any
-                    result = result + prefix + '' + name + ''
-                elif re_source_keywords.match( name ):
-                    # this is a C keyword
-                    result = ( result + prefix
-                               + keyword_prefix + name + keyword_suffix )
-                elif name in self.identifiers:
-                    # this is a known identifier
-                    block = self.identifiers[name]
-                    id = block.name
-
-                    # link to a field ID if possible
-                    try:
-                      for markup in block.markups:
-                          if markup.tag == 'values':
-                              for field in markup.fields:
-                                  if field.name:
-                                      id = name
-
-                      result = ( result + prefix
-                                 + '' + name + '' )
-                    except:
-                      # sections don't have `markups'; however, we don't
-                      # want references to sections here anyway
-                      result = result + html_quote( line[:length] )
-
-                else:
-                    result = result + html_quote( line[:length] )
-
-                line = line[length:]
-            else:
-                result = result + html_quote( line )
-                line   = []
-
-        return result
-
-    def  print_html_field_list( self, fields ):
-        print( '' )
-        for field in fields:
-            print( '" )
-        print( "
'
-                   + field.name
-                   + '' )
-            self.print_html_items( field.items )
-            print( "
" )
-
-    def  print_html_markup( self, markup ):
-        table_fields = []
-        for field in markup.fields:
-            if field.name:
-                # 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:
-                    self.print_html_field_list( table_fields )
-                    table_fields = []
-
-                self.print_html_items( field.items )
-
-        if table_fields:
-            self.print_html_field_list( table_fields )
-
-    #
-    # formatting the index
-    #
-    def  index_enter( self ):
-        print( self.html_index_header )
-        self.index_items = {}
-
-    def  index_name_enter( self, name ):
-        block = self.identifiers[name]
-        url   = self.make_block_url( block )
-        self.index_items[name] = url
-
-    def  index_exit( self ):
-        # `block_index' already contains the sorted list of index names
-        count = len( self.block_index )
-        rows  = ( count + self.columns - 1 ) // self.columns
-
-        print( '' )
-        for r in range( rows ):
-            line = ""
-            for c in range( self.columns ):
-                i = r + c * rows
-                if i < count:
-                    bname = self.block_index[r + c * rows]
-                    url   = self.index_items[bname]
-                    # display `foo[bar]' as `foo (bar)'
-                    bname = string.replace( bname, "[", " (" )
-                    bname = string.replace( bname, "]", ")"  )
-                    # normalize url, following RFC 3986
-                    url = string.replace( url, "[", "(" )
-                    url = string.replace( url, "]", ")" )
-                    line  = ( line + '' )
-                else:
-                    line = line + ''
-            line = line + ""
-            print( line )
-
-        print( "
'
-                              + bname + '
" )
-
-        print( index_footer_start
-               + self.file_prefix + "toc.html"
-               + index_footer_end )
-
-        print( self.html_footer )
-
-        self.index_items = {}
-
-    def  index_dump( self, index_filename = None ):
-        if index_filename == None:
-            index_filename = self.file_prefix + "index.html"
-
-        Formatter.index_dump( self, index_filename )
-
-    #
-    # formatting the table of contents
-    #
-    def  toc_enter( self ):
-        print( self.html_toc_header )
-        print( "
Table of Contents
" )
-
-    def  toc_chapter_enter( self, chapter ):
-        print( chapter_header + string.join( chapter.title ) + chapter_inter )
-        print( '' )
-
-    def  toc_section_enter( self, section ):
-        print( '" )
-
-    def  toc_chapter_exit( self, chapter ):
-        print( "
'
-               + ''
-               + section.title + '' )
-        print( self.make_html_para( section.abstract ) )
-
-    def  toc_section_exit( self, section ):
-        print( "
" )
-        print( chapter_footer )
-
-    def  toc_index( self, index_filename ):
-        print( chapter_header
-               + 'Global Index'
-               + chapter_inter + chapter_footer )
-
-    def  toc_exit( self ):
-        print( toc_footer_start
-               + self.file_prefix + "index.html"
-               + toc_footer_end )
-
-        print( self.html_footer )
-
-    def  toc_dump( self, toc_filename = None, index_filename = None ):
-        if toc_filename == None:
-            toc_filename = self.file_prefix + "toc.html"
-
-        if index_filename == None:
-            index_filename = self.file_prefix + "index.html"
-
-        Formatter.toc_dump( self, toc_filename, index_filename )
-
-    #
-    # formatting sections
-    #
-    def  section_enter( self, section ):
-        print( self.html_header )
-
-        print( section_title_header1 + section.name + section_title_header2
-               + section.title
-               + section_title_footer )
-
-        maxwidth = 0
-        for b in section.blocks.values():
-            if len( b.name ) > maxwidth:
-                maxwidth = len( b.name )
-
-        width = 70  # XXX magic number
-        if maxwidth > 0:
-            # print section synopsis
-            print( section_synopsis_header )
-            print( '' )
-
-            columns = width // maxwidth
-            if columns < 1:
-                columns = 1
-
-            count = len( section.block_names )
-            # 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 = ""
-                for c in range( columns ):
-                    i = r + c * rows
-                    line = line + ''
-                line = line + ""
-                print( line )
-
-            print( "
'
-                    if i < count:
-                        name = section.block_names[i]
-                        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 + " "
-                        else:
-                            url = name
-                            # display `foo[bar]' as `foo'
-                            name = re.sub( r'\[.*\]', '', name )
-                            # normalize url, following RFC 3986
-                            url = string.replace( url, "[", "(" )
-                            url = string.replace( url, "]", ")" )
-                            line = ( line + ''
-                                     + name + '' )
-
-                    line = line + '
" )
-            print( section_synopsis_footer )
-
-        print( description_header )
-        print( self.make_html_items( section.description ) )
-        print( description_footer )
-
-    def  block_enter( self, block ):
-        print( block_header )
-
-        # place html anchor if needed
-        if block.name:
-            url = block.name
-            # display `foo[bar]' as `foo'
-            name = re.sub( r'\[.*\]', '', block.name )
-            # normalize url, following RFC 3986
-            url = string.replace( url, "[", "(" )
-            url = string.replace( url, "]", ")" )
-            print( '
' + name + '
' )
-
-        # dump the block C source lines now
-        if block.code:
-            header = ''
-            for f in self.headers.keys():
-                header_filename = os.path.normpath(block.source.filename)
-                if header_filename.find( os.path.normpath( f ) ) >= 0:
-                    header = self.headers[f] + ' (' + f + ')'
-                    break
-
-#           if not header:
-#               sys.stderr.write(
-#                 "WARNING: No header macro for"
-#                 + " '" + block.source.filename + "'.\n" )
-
-            if header:
-                print( header_location_header
-                       + 'Defined in ' + header + '.'
-                       + header_location_footer )
-
-            print( source_header )
-            for l in block.code:
-                print( self.html_source_quote( l, block.name ) )
-            print( source_footer )
-
-    def  markup_enter( self, markup, block ):
-        if markup.tag == "description":
-            print( description_header )
-        else:
-            print( marker_header + markup.tag + marker_inter )
-
-        self.print_html_markup( markup )
-
-    def  markup_exit( self, markup, block ):
-        if markup.tag == "description":
-            print( description_footer )
-        else:
-            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 )
-
-    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' )
-
-# eof
diff --git a/src/tools/docmaker/utils.py b/src/tools/docmaker/utils.py
deleted file mode 100644
index f40f1674a..000000000
--- a/src/tools/docmaker/utils.py
+++ /dev/null
@@ -1,127 +0,0 @@
-#
-#  utils.py
-#
-#    Auxiliary functions for the `docmaker' tool (library file).
-#
-#  Copyright 2002-2018 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.
-
-
-import string, sys, os, glob, itertools
-
-
-# current output directory
-#
-output_dir = None
-
-
-# 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.
-#
-def  sort_order_list( input_list, order_list ):
-    new_list = order_list[:]
-    for id in input_list:
-        if not id in order_list:
-            new_list.append( id )
-    return new_list
-
-
-# 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
-
-    if output_dir and output_dir != "":
-        filename = output_dir + os.sep + filename
-
-    old_stdout = sys.stdout
-    new_file   = open( filename, "w" )
-    sys.stdout = new_file
-
-    return ( new_file, old_stdout )
-
-
-# Close the output that was returned by `open_output'.
-#
-def  close_output( output ):
-    output[0].close()
-    sys.stdout = output[1]
-
-
-# Check output directory.
-#
-def  check_output():
-    global output_dir
-    if output_dir:
-        if output_dir != "":
-            if not os.path.isdir( output_dir ):
-                sys.stderr.write( "argument"
-                                  + " '" + output_dir + "' "
-                                  + "is not a valid directory\n" )
-                sys.exit( 2 )
-        else:
-            output_dir = None
-
-
-def  file_exists( pathname ):
-    """Check that a given file exists."""
-    result = 1
-    try:
-        file = open( pathname, "r" )
-        file.close()
-    except:
-        result = None
-        sys.stderr.write( pathname + " couldn't be accessed\n" )
-
-    return result
-
-
-def  make_file_list( args = None ):
-    """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:]
-
-    for pathname in args:
-        if string.find( pathname, '*' ) >= 0:
-            newpath = glob.glob( pathname )
-            newpath.sort()  # sort files -- this is important because
-                            # of the order of files
-        else:
-            newpath = [pathname]
-
-        file_list.extend( newpath )
-
-    if len( file_list ) == 0:
-        file_list = None
-    else:
-        # now filter the file list to remove non-existing ones
-        file_list = filter( file_exists, file_list )
-
-    return file_list
-
-# eof