ref: 53286c097018f3e13c5511c1931370ade7a1c493
parent: 4af139d2e4d61b2771717ec712c787f1a5b0b87e
author: Werner Lemberg <[email protected]>
date: Fri Jan 18 00:14:13 EST 2008
more formatting and whitespace
--- a/src/tools/docmaker/content.py
+++ b/src/tools/docmaker/content.py
@@ -48,8 +48,8 @@
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 @@
# 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 @@
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:
--- 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 <[email protected]>
+# DocBeauty (c) 2003, 2004, 2008 David Turner <[email protected]>
#
# 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 @@
first = 0
# now beautify the documentation "borders" themselves
- lines = [ " /*************************************************************************" ]
+ lines = [" /*************************************************************************"]
for l in text:
lines.append( " *" + l )
lines.append( " */" )
@@ -38,9 +39,9 @@
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 @@
print " --backup : same as -b"
-def main( argv ):
+def main( argv ):
"""main program loop"""
global output_dir
@@ -56,7 +57,7 @@
try:
opts, args = getopt.getopt( sys.argv[1:],
"hb",
- [ "help", "backup" ] )
+ ["help", "backup"] )
except getopt.GetoptError:
usage()
@@ -80,7 +81,7 @@
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 )
@@ -99,6 +100,7 @@
file.close()
except:
ok = 0
+
# if called from the command line
#
--- 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 <[email protected]>
+# DocMaker (c) 2002, 2004, 2008 David Turner <[email protected]>
#
# 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 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 @@
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 @@
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 @@
if opt[0] in ( "-p", "--prefix" ):
project_prefix = opt[1]
- check_output( )
+ check_output()
# create context and processor
source_processor = SourceProcessor()
--- a/src/tools/docmaker/formatter.py
+++ b/src/tools/docmaker/formatter.py
@@ -1,4 +1,4 @@
-# Formatter (c) 2002, 2004, 2007 David Turner <[email protected]>
+# Formatter (c) 2002, 2004, 2007, 2008 David Turner <[email protected]>
#
from sources import *
@@ -16,8 +16,7 @@
class Formatter:
- def __init__( self, processor ):
-
+ def __init__( self, processor ):
self.processor = processor
self.identifiers = {}self.chapters = processor.chapters
@@ -25,8 +24,9 @@
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 @@
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 @@
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 @@
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 @@
#
# Formatting the index
#
-
def index_enter( self ):
pass
@@ -119,7 +113,6 @@
pass
def index_dump( self, index_filename = None ):
-
output = None
if index_filename:
output = open_output( index_filename )
@@ -128,7 +121,7 @@
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 @@
def section_exit( self, section ):
pass
-
def section_dump( self, section, section_filename = None ):
output = None
@@ -172,33 +164,27 @@
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
--- 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 <[email protected]>
#
#
@@ -18,14 +18,12 @@
# 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 @@
##
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 @@
re_source_block_format1 = SourceBlockFormat( 1, start, column, start )
+
#
# format 2 documentation comment blocks look like the following:
#
@@ -107,11 +106,12 @@
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 @@
# 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,7 +175,8 @@
\#else |
\#endif ) \\b''', re.VERBOSE )
-################################################################
+
+################################################################
##
## SOURCE BLOCK CLASS
##
@@ -199,7 +200,7 @@
## 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 @@
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,13 +245,14 @@
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 @@
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 @@
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 @@
# 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 @@
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 @@
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()
--- 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 <[email protected]>
from sources import *
@@ -7,6 +7,7 @@
import time
+
# The following defines the HTML header used by all generated pages.
#
html_header_1 = """\
@@ -51,7 +52,6 @@
"""
-
# The HTML footer used by all generated pages.
#
html_footer = """\
@@ -131,10 +131,11 @@
section_synopsis_header = '<h2>Synopsis</h2>'
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 @@
# 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 @@
#
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):
+class HtmlFormatter( Formatter ):
- def __init__( self, processor, project_title, file_prefix ):
-
+ 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 @@
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 @@
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 @@
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 '<a href="' + url + '">' + name + '</a>' + rest
@@ -228,19 +225,18 @@
# 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 '<i>' + name + '</i>' + 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 '<b>' + name + '</b>' + 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 """
line = ""
@@ -255,7 +251,6 @@
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 @@
return line + code_footer
-
def make_html_items( self, items ):
""" convert a field's content into some valid HTML """
lines = []
@@ -276,12 +270,10 @@
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 "<table><tr valign=top><td><p><b>"+field.name+"</b></p></td><td>"
@@ -290,44 +282,42 @@
if field.name:
print "</td></tr></table>"
-
- 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 + '<b>' + name + '</b>'
- 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 + '<a href="' + \
- self.make_block_url(block) + '">' + name + '</a>'
+ self.make_block_url( block ) + '">' + name + '</a>'
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 "<table cellpadding=3 border=0>"
for field in fields:
- if len(field.name) > 22:
+ if len( field.name ) > 22:
print "<tr valign=top><td colspan=0><b>"+field.name+"</b></td></tr>"
print "<tr valign=top><td></td><td>"
else:
@@ -337,8 +327,7 @@
print "</td></tr>"
print "</table>"
-
- 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 @@
#
# Formatting the index
#
-
def index_enter( self ):
print self.html_header
self.index_items = {}@@ -372,15 +360,14 @@
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 "<table align=center border=0 cellpadding=0 cellspacing=0>"
- for r in range(rows):
+ for r in range( rows ):
line = "<tr>"
- 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 @@
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 @@
print "<center><h1>Table of Contents</h1></center>"
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 "<table cellpadding=5>"
def toc_section_enter( self, section ):
@@ -461,7 +447,7 @@
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 @@
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 @@
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' )
--- a/src/tools/docmaker/utils.py
+++ b/src/tools/docmaker/utils.py
@@ -1,4 +1,4 @@
-# Utils (c) 2002, 2004, 2007 David Turner <[email protected]>
+# Utils (c) 2002, 2004, 2007, 2008 David Turner <[email protected]>
#
import string, sys, os, glob
@@ -11,7 +11,7 @@
# 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 @@
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 @@
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,7 +71,7 @@
# Close the output that was returned by "close_output".
#
-def close_output( output ):
+def close_output( output ):
output[0].close()
sys.stdout = output[1]
@@ -78,7 +78,7 @@
# Check output directory.
#
-def check_output( ):
+def check_output():
global output_dir
if output_dir:
if output_dir != "":
@@ -89,7 +89,8 @@
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 @@
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 = []