diff --git a/src/tools/docmaker/content.py b/src/tools/docmaker/content.py index 3f2b4de43..d751c2102 100644 --- a/src/tools/docmaker/content.py +++ b/src/tools/docmaker/content.py @@ -48,8 +48,8 @@ re_identifier = re.compile( r'(\w*)' ) class DocCode: def __init__( self, margin, lines ): - self.lines = [] - self.words = None + self.lines = [] + self.words = None # remove margin spaces for l in lines: @@ -220,7 +220,7 @@ class DocField: # this regular expression is used to detect field definitions # -re_field = re.compile( r"\s*(\w*|\w(\w|\.)*\w)\s*::" ) +re_field = re.compile( r"\s*(\w*|\w(\w|\.)*\w)\s*::" ) @@ -473,12 +473,12 @@ 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 ) + 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: diff --git a/src/tools/docmaker/docbeauty.py b/src/tools/docmaker/docbeauty.py index 55c43297f..0e58f6644 100644 --- a/src/tools/docmaker/docbeauty.py +++ b/src/tools/docmaker/docbeauty.py @@ -1,23 +1,24 @@ #!/usr/bin/env python # -# DocBeauty (c) 2003, 2004 David Turner +# 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 * +from sources import * +from content import * +from utils import * import utils import sys, os, time, string, getopt + content_processor = ContentProcessor() -def beautify_block( block ): +def beautify_block( block ): if block.content: content_processor.reset() @@ -30,7 +31,7 @@ def beautify_block( block ): first = 0 # now beautify the documentation "borders" themselves - lines = [ " /*************************************************************************" ] + lines = [" /*************************************************************************"] for l in text: lines.append( " *" + l ) lines.append( " */" ) @@ -38,9 +39,9 @@ def beautify_block( block ): block.lines = lines -def usage(): +def usage(): print "\nDocBeauty 0.1 Usage information\n" - print " docbeauty [options] file1 [ file2 ... ]\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" @@ -48,7 +49,7 @@ def usage(): print " --backup : same as -b" -def main( argv ): +def main( argv ): """main program loop""" global output_dir @@ -56,7 +57,7 @@ def main( argv ): try: opts, args = getopt.getopt( sys.argv[1:], "hb", - [ "help", "backup" ] ) + ["help", "backup"] ) except getopt.GetoptError: usage() @@ -80,7 +81,7 @@ def main( argv ): do_backup = 1 # create context and processor - source_processor = SourceProcessor() + source_processor = SourceProcessor() # retrieve the list of files to process file_list = make_file_list( args ) @@ -100,6 +101,7 @@ def main( argv ): except: ok = 0 + # if called from the command line # if __name__ == '__main__': diff --git a/src/tools/docmaker/docmaker.py b/src/tools/docmaker/docmaker.py index d34b6e8f9..906ba8849 100644 --- a/src/tools/docmaker/docmaker.py +++ b/src/tools/docmaker/docmaker.py @@ -1,6 +1,6 @@ #!/usr/bin/env python # -# DocMaker (c) 2002, 2004 David Turner +# DocMaker (c) 2002, 2004, 2008 David Turner # # This program is a re-write of the original DocMaker took used # to generate the API Reference of the FreeType font engine @@ -24,9 +24,9 @@ import utils import sys, os, time, string, glob, getopt -def usage(): +def usage(): print "\nDocMaker Usage information\n" - print " docmaker [options] file1 [ file2 ... ]\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\"'" @@ -38,7 +38,7 @@ def usage(): print " --prefix : same as -p, as in '--prefix=ft2'" -def main( argv ): +def main( argv ): """main program loop""" global output_dir @@ -46,7 +46,7 @@ def main( argv ): try: opts, args = getopt.getopt( sys.argv[1:], "ht:o:p:", - [ "help", "title=", "output=", "prefix=" ] ) + ["help", "title=", "output=", "prefix="] ) except getopt.GetoptError: usage() @@ -76,7 +76,7 @@ def main( argv ): if opt[0] in ( "-p", "--prefix" ): project_prefix = opt[1] - check_output( ) + check_output() # create context and processor source_processor = SourceProcessor() diff --git a/src/tools/docmaker/formatter.py b/src/tools/docmaker/formatter.py index 363410efc..8796bb224 100644 --- a/src/tools/docmaker/formatter.py +++ b/src/tools/docmaker/formatter.py @@ -1,4 +1,4 @@ -# Formatter (c) 2002, 2004, 2007 David Turner +# Formatter (c) 2002, 2004, 2007, 2008 David Turner # from sources import * @@ -16,8 +16,7 @@ from utils import * class Formatter: - def __init__( self, processor ): - + def __init__( self, processor ): self.processor = processor self.identifiers = {} self.chapters = processor.chapters @@ -25,8 +24,9 @@ class Formatter: self.block_index = [] # store all blocks in a dictionary - self.blocks = [] + self.blocks = [] for section in self.sections: + self.add_identifier( section.name, section ); for block in section.blocks.values(): self.add_identifier( block.name, block ) @@ -36,26 +36,22 @@ class Formatter: for field in markup.fields: self.add_identifier( field.name, block ) - self.block_index = self.identifiers.keys() self.block_index.sort( index_sort ) - - def add_identifier( self, name, block ): + def add_identifier( self, name, block ): if self.identifiers.has_key( name ): - # duplicate name !! + # duplicate name! sys.stderr.write( \ "WARNING: duplicate definition for '" + name + "' in " + \ block.location() + ", previous definition in " + \ - self.identifiers[ name ].location() + "\n" ) + self.identifiers[name].location() + "\n" ) else: self.identifiers[name] = block - # # Formatting the table of contents # - def toc_enter( self ): pass @@ -78,7 +74,6 @@ class Formatter: pass def toc_dump( self, toc_filename = None, index_filename = None ): - output = None if toc_filename: output = open_output( toc_filename ) @@ -93,7 +88,7 @@ class Formatter: self.toc_section_enter( section ) self.toc_section_exit( section ) - self.toc_chapter_exit ( chap ) + self.toc_chapter_exit( chap ) self.toc_index( index_filename ) @@ -105,7 +100,6 @@ class Formatter: # # Formatting the index # - def index_enter( self ): pass @@ -119,7 +113,6 @@ class Formatter: pass def index_dump( self, index_filename = None ): - output = None if index_filename: output = open_output( index_filename ) @@ -128,7 +121,7 @@ class Formatter: for name in self.block_index: self.index_name_enter( name ) - self.index_name_exit ( name ) + self.index_name_exit( name ) self.index_exit() @@ -162,7 +155,6 @@ class Formatter: def section_exit( self, section ): pass - def section_dump( self, section, section_filename = None ): output = None @@ -172,33 +164,27 @@ class Formatter: self.section_enter( section ) for name in section.block_names: - block = self.identifiers[ name ] + block = self.identifiers[name] self.block_enter( block ) - for markup in block.markups[1:]: # always ignore first markup !! + 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.field_exit( field, markup, block ) self.markup_exit( markup, block ) self.block_exit( block ) - self.section_exit ( section ) + self.section_exit( section ) if output: close_output( output ) - - def section_dump_all( self ): + def section_dump_all( self ): for section in self.sections: self.section_dump( section ) - # - # Formatting a block - # - # eof diff --git a/src/tools/docmaker/sources.py b/src/tools/docmaker/sources.py index 09ff7f997..08f3b1413 100644 --- a/src/tools/docmaker/sources.py +++ b/src/tools/docmaker/sources.py @@ -1,4 +1,4 @@ -# Sources (c) 2002, 2003, 2004, 2006, 2007 +# Sources (c) 2002, 2003, 2004, 2006, 2007, 2008 # David Turner # # @@ -18,13 +18,11 @@ # the classes and methods found here only deal with text parsing # and basic documentation block extraction # + import fileinput, re, sys, os, string - - - ################################################################ ## ## BLOCK FORMAT PATTERN @@ -38,7 +36,7 @@ import fileinput, re, sys, os, string ## class SourceBlockFormat: - def __init__( self, id, start, column, end ): + def __init__( self, id, start, column, end ): """create a block pattern, used to recognize special documentation blocks""" self.id = id @@ -76,6 +74,7 @@ column = r''' re_source_block_format1 = SourceBlockFormat( 1, start, column, start ) + # # format 2 documentation comment blocks look like the following: # @@ -107,11 +106,12 @@ end = r''' re_source_block_format2 = SourceBlockFormat( 2, start, column, end ) + # # the list of supported documentation block formats, we could add new ones # relatively easily # -re_source_block_formats = [ re_source_block_format1, re_source_block_format2 ] +re_source_block_formats = [re_source_block_format1, re_source_block_format2] # @@ -128,7 +128,7 @@ re_markup_tag2 = re.compile( r'''\s*@(\w*):''' ) # @xxxx: format # the list of supported markup tags, we could add new ones relatively # easily # -re_markup_tags = [ re_markup_tag1, re_markup_tag2 ] +re_markup_tags = [re_markup_tag1, re_markup_tag2] # # used to detect a cross-reference, after markup tags have been stripped @@ -175,6 +175,7 @@ re_source_keywords = re.compile( '''\\b ( typedef | \#else | \#endif ) \\b''', re.VERBOSE ) + ################################################################ ## ## SOURCE BLOCK CLASS @@ -199,7 +200,7 @@ re_source_keywords = re.compile( '''\\b ( typedef | ## markup tag) ## class SourceBlock: - def __init__( self, processor, filename, lineno, lines ): + def __init__( self, processor, filename, lineno, lines ): self.processor = processor self.filename = filename self.lineno = lineno @@ -218,24 +219,23 @@ class SourceBlock: for line0 in self.lines: m = self.format.column.match( line0 ) if m: - lines.append( m.group(1) ) + lines.append( m.group( 1 ) ) # now, look for a markup tag for l in lines: - l = string.strip(l) - if len(l) > 0: + 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) + ")" + def location( self ): + return "(" + self.filename + ":" + repr( self.lineno ) + ")" # debugging only - not used in normal operations - def dump( self ): - + def dump( self ): if self.content: print "{{{content start---" for l in self.content: @@ -245,12 +245,13 @@ class SourceBlock: fmt = "" if self.format: - fmt = repr(self.format.id) + " " + fmt = repr( self.format.id ) + " " for line in self.lines: print line + ################################################################ ## ## SOURCE PROCESSOR CLASS @@ -281,7 +282,6 @@ class SourceProcessor: self.blocks = [] self.format = None - def parse_file( self, filename ): """parse a C source file, and adds its blocks to the processor's list""" @@ -290,12 +290,11 @@ class SourceProcessor: self.filename = filename fileinput.close() - self.format = None - self.lineno = 0 - self.lines = [] + 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] @@ -325,9 +324,7 @@ class SourceProcessor: # record the last lines self.add_block_lines() - - - def process_normal_line( self, line ): + def process_normal_line( self, line ): """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 ): @@ -337,9 +334,7 @@ class SourceProcessor: self.lines.append( line ) - - - def add_block_lines( self ): + 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 ) @@ -348,9 +343,8 @@ class SourceProcessor: self.format = None self.lines = [] - # debugging only, not used in normal operations - def dump( self ): + def dump( self ): """print all blocks in a processor""" for b in self.blocks: b.dump() diff --git a/src/tools/docmaker/tohtml.py b/src/tools/docmaker/tohtml.py index 5e9ae1838..af63f793d 100644 --- a/src/tools/docmaker/tohtml.py +++ b/src/tools/docmaker/tohtml.py @@ -1,4 +1,4 @@ -# ToHTML (c) 2002, 2003, 2005, 2006, 2007 +# ToHTML (c) 2002, 2003, 2005, 2006, 2007, 2008 # David Turner from sources import * @@ -7,6 +7,7 @@ from formatter import * import time + # The following defines the HTML header used by all generated pages. # html_header_1 = """\ @@ -51,7 +52,6 @@ html_header_3=""" API Reference """ - # The HTML footer used by all generated pages. # html_footer = """\ @@ -131,10 +131,11 @@ keyword_suffix = '' section_synopsis_header = '

Synopsis

' section_synopsis_footer = '' + # Translate a single line of source to HTML. This will convert # a "<" into "<.", ">" into ">.", etc. # -def html_quote( line ): +def html_quote( line ): result = string.replace( line, "&", "&" ) result = string.replace( result, "<", "<" ) result = string.replace( result, ">", ">" ) @@ -143,11 +144,11 @@ def html_quote( line ): # same as 'html_quote', but ignores left and right brackets # -def html_quote0( line ): +def html_quote0( line ): return string.replace( line, "&", "&" ) -def dump_html_code( lines, prefix = "" ): +def dump_html_code( lines, prefix = "" ): # clean the last empty lines # l = len( self.lines ) @@ -159,15 +160,14 @@ def dump_html_code( lines, prefix = "" ): # print prefix + code_header, for line in self.lines[0 : l+1]: - print '\n' + prefix + html_quote(line), + print '\n' + prefix + html_quote( line ), print prefix + code_footer, -class HtmlFormatter(Formatter): - - def __init__( self, processor, project_title, file_prefix ): +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, html_footer @@ -191,11 +191,9 @@ class HtmlFormatter(Formatter): 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_html_words( self, words ): """ convert a series of simple words into some HTML text """ line = "" @@ -206,7 +204,6 @@ class HtmlFormatter(Formatter): return line - def make_html_word( self, word ): """analyze a simple word to detect cross-references and styling""" # look for cross-references @@ -214,8 +211,8 @@ class HtmlFormatter(Formatter): m = re_crossref.match( word ) if m: try: - name = m.group(1) - rest = m.group(2) + name = m.group( 1 ) + rest = m.group( 2 ) block = self.identifiers[name] url = self.make_block_url( block ) return '' + name + '' + rest @@ -228,18 +225,17 @@ class HtmlFormatter(Formatter): # look for italics and bolds m = re_italic.match( word ) if m: - name = m.group(1) - rest = m.group(3) + name = m.group( 1 ) + rest = m.group( 3 ) return '' + name + '' + rest m = re_bold.match( word ) if m: - name = m.group(1) - rest = m.group(3) + name = m.group( 1 ) + rest = m.group( 3 ) return '' + name + '' + rest - return html_quote(word) - + return html_quote( word ) def make_html_para( self, words ): """ convert a paragraph's words into tagged HTML text, handle xrefs """ @@ -255,7 +251,6 @@ class HtmlFormatter(Formatter): return para_header + line + para_footer - def make_html_code( self, lines ): """ convert a code sequence to HTML """ line = code_header + '\n' @@ -264,7 +259,6 @@ class HtmlFormatter(Formatter): return line + code_footer - def make_html_items( self, items ): """ convert a field's content into some valid HTML """ lines = [] @@ -276,12 +270,10 @@ class HtmlFormatter(Formatter): return string.join( lines, '\n' ) - def print_html_items( self, items ): print self.make_html_items( items ) - - def print_html_field( self, field ): + def print_html_field( self, field ): if field.name: print "

"+field.name+"

" @@ -290,44 +282,42 @@ class HtmlFormatter(Formatter): if field.name: print "
" - - def html_source_quote( self, line, block_name = None ): + 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) ) + 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): + 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): + elif self.identifiers.has_key( name ): # this is a known identifier block = self.identifiers[name] result = result + prefix + '' + name + '' + self.make_block_url( block ) + '">' + name + '' else: - result = result + html_quote(line[:length]) + result = result + html_quote( line[:length] ) line = line[length:] else: - result = result + html_quote(line) + result = result + html_quote( line ) line = [] return result - - def print_html_field_list( self, fields ): + def print_html_field_list( self, fields ): print "" for field in fields: - if len(field.name) > 22: + if len( field.name ) > 22: print "" print "" print "
"+field.name+"
" else: @@ -337,8 +327,7 @@ class HtmlFormatter(Formatter): print "
" - - def print_html_markup( self, markup ): + def print_html_markup( self, markup ): table_fields = [] for field in markup.fields: if field.name: @@ -361,7 +350,6 @@ class HtmlFormatter(Formatter): # # Formatting the index # - def index_enter( self ): print self.html_header self.index_items = {} @@ -372,15 +360,14 @@ class HtmlFormatter(Formatter): 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 + rows = ( count + self.columns - 1 ) / self.columns print "" - for r in range(rows): + for r in range( rows ): line = "" - for c in range(self.columns): + for c in range( self.columns ): i = r + c*rows if i < count: bname = self.block_index[r + c * rows] @@ -400,7 +387,6 @@ class HtmlFormatter(Formatter): self.index_items = {} def index_dump( self, index_filename = None ): - if index_filename == None: index_filename = self.file_prefix + "index.html" @@ -414,7 +400,7 @@ class HtmlFormatter(Formatter): print "

Table of Contents

" def toc_chapter_enter( self, chapter ): - print chapter_header + string.join(chapter.title) + chapter_inter + print chapter_header + string.join( chapter.title ) + chapter_inter print "
" def toc_section_enter( self, section ): @@ -461,7 +447,7 @@ class HtmlFormatter(Formatter): if len( b.name ) > maxwidth: maxwidth = len( b.name ) - width = 70 # XXX magic number + width = 70 # XXX magic number if maxwidth <> 0: # print section synopsis print section_synopsis_header @@ -508,7 +494,6 @@ class HtmlFormatter(Formatter): print self.html_source_quote( l, block.name ) print source_footer - def markup_enter( self, markup, block ): if markup.tag == "description": print description_header @@ -528,12 +513,10 @@ class HtmlFormatter(Formatter): block_footer_middle + self.file_prefix + "toc.html" + \ block_footer_end - def section_exit( self, section ): print html_footer - - def section_dump_all( self ): + def section_dump_all( self ): for section in self.sections: self.section_dump( section, self.file_prefix + section.name + '.html' ) diff --git a/src/tools/docmaker/utils.py b/src/tools/docmaker/utils.py index e751c5631..adafa4fa5 100644 --- a/src/tools/docmaker/utils.py +++ b/src/tools/docmaker/utils.py @@ -1,4 +1,4 @@ -# Utils (c) 2002, 2004, 2007 David Turner +# Utils (c) 2002, 2004, 2007, 2008 David Turner # import string, sys, os, glob @@ -11,7 +11,7 @@ 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. # -def index_sort( s1, s2 ): +def index_sort( s1, s2 ): if not s1: return -1 @@ -41,9 +41,10 @@ def index_sort( s1, s2 ): return 0 + # Sort input_list, placing the elements of order_list in front. # -def sort_order_list( input_list, order_list ): +def sort_order_list( input_list, order_list ): new_list = order_list[:] for id in input_list: if not id in order_list: @@ -51,12 +52,11 @@ 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. # -def open_output( filename ): +def open_output( filename ): global output_dir if output_dir and output_dir != "": @@ -71,14 +71,14 @@ def open_output( filename ): # Close the output that was returned by "close_output". # -def close_output( output ): +def close_output( output ): output[0].close() sys.stdout = output[1] # Check output directory. # -def check_output( ): +def check_output(): global output_dir if output_dir: if output_dir != "": @@ -89,7 +89,8 @@ def check_output( ): else: output_dir = None -def file_exists( pathname ): + +def file_exists( pathname ): """checks that a given file exists""" result = 1 try: @@ -102,7 +103,7 @@ def file_exists( pathname ): return result -def make_file_list( args = None ): +def make_file_list( args = None ): """builds a list of input files from command-line arguments""" file_list = []