* src/tools/docmaker/*: updating the DocMaker tool, adding a new

tool named "docbeauty" to beautify the documentation comments
        (e.g. convert them to a single block border mode)

src/tools/docmaker/docbeauty.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python
+#
+#  DocBeuaty 0.2 (c) 2003 David Turner <david@freetype.org>
+#
+# This program is used to beautify the documentation comments used
+# in the FreeType 2 public headers.
+#
+# For now, it basically converts all document blocks to a single
+# format. It should be able to re-justify all text later in the
+# future..
+#
+
+from sources   import *
+from utils     import *
+
+import utils
+
+import sys, os, time, string, getopt
+
+
+def beautify_block( block ):
+    if block.content:
+        # only beautify documentation blocks
+        lines = [ " /*************************************************************************" ]
+        for l in block.content:
+            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

src/tools/docmaker/docmaker.py

@@ -24,48 +24,6 @@ import utils
 import sys, os, time, string, glob, getopt
 
 
-def file_exists( pathname ):
-    """checks 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 ):
-    """builds 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
-
-
-
 def usage():
     print "\nDocMaker 0.2 Usage information\n"
     print "  docmaker [options] file1 [ file2 ... ]\n"

src/tools/docmaker/formatter.py

@@ -1,6 +1,15 @@
 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'll 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 !
+#
 
 class Formatter:
 

src/tools/docmaker/sources.py

@@ -200,7 +200,7 @@ class SourceBlock:
         self.processor = processor
         self.filename  = filename
         self.lineno    = lineno
-        self.lines     = lines
+        self.lines     = lines[:]
         self.format    = processor.format
         self.content   = []
 
@@ -328,9 +328,9 @@ class SourceProcessor:
         """process a normal line and check if it's the start of a new block"""
         for f in re_source_block_formats:
           if f.start.match( line ):
-            self.add_block_lines()
+            self.add_block_lines()
             self.format = f
-            self.lineno = fileinput.filelineno()
+            self.lineno = fileinput.filelineno()
 
         self.lines.append( line )
 

src/tools/docmaker/utils.py

@@ -1,4 +1,4 @@
-import string, sys, os
+import string, sys, os, glob
 
 # current output directory
 #
@@ -85,3 +85,44 @@ def check_output( ):
                 sys.exit( 2 )
         else:
             output_dir = None
+
+def file_exists( pathname ):
+    """checks 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 ):
+    """builds 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
+