ref: ee42805e5f49ffc6c46d9f1045ca2fc63a09f246
parent: 94a8918b8f76a23e1e8e20d26e0b0d195e61f582
author: David Turner <[email protected]>
date: Fri Jan 16 09:26:32 EST 2004
* 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)
--- /dev/null
+++ b/src/tools/docmaker/docbeauty.py
@@ -1,0 +1,100 @@
+#!/usr/bin/env python
+#
+# DocBeuaty 0.2 (c) 2003 David Turner <[email protected]>
+#
+# 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
--- a/src/tools/docmaker/docmaker.py
+++ b/src/tools/docmaker/docmaker.py
@@ -24,48 +24,6 @@
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"
--- a/src/tools/docmaker/formatter.py
+++ b/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:
--- a/src/tools/docmaker/sources.py
+++ b/src/tools/docmaker/sources.py
@@ -200,7 +200,7 @@
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 @@
"""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 )
--- a/src/tools/docmaker/utils.py
+++ b/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 @@
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
+