Emit header info for defined FreeType objects in reference.

ChangeLog

@@ -1,4 +1,19 @@
-2008-05-01  Werner Lemberg  <wl@gnu.org>
+2008-06-02  Werner Lemberg  <wl@gnu.org>
+
+	Emit header info for defined FreeType objects in reference.
+
+	* src/tools/docmaker/content.py (re_header_macro): New regexp.
+	(ContentProcessor::__init__): Initialize new dictionary `headers'.
+	(DocBlock::__init__): Collect macro header definitions.
+
+	* src/tools/docmaker/tohtml.py (header_location_header,
+	header_location_footer): New strings.
+	(HtmlFormatter::__init__): Pass `headers' dictionary.
+	(HtmlFormatter::print_html_field): Don't emit paragraph tags.
+	(HtmlFormatter::print_html_field_list): Emit empty paragraph.
+	(HtmlFormatter::block_enter): Emit header info.
+
+2008-06-01  Werner Lemberg  <wl@gnu.org>
 
 	* include/freetype/config/ftheader.h (FT_UNPATENTED_HINTING_H,
 	FT_INCREMENTAL_H): Added.

src/tools/docmaker/content.py

@@ -34,6 +34,12 @@ re_code_end   = re.compile( r"(\s*)}\s*$" )
 re_identifier = re.compile( r'(\w*)' )
 
 
+# we collect macros ending in `_H'; while outputting the object data, we use
+# this info together with the object's file location to emit the appropriate
+# header file macro and name before the object itself
+#
+re_header_macro = re.compile( r'^#define\s{1,}(\w{1,}_H)\s{1,}<(.*)>' )
+
 
 #############################################################################
 #
@@ -339,7 +345,9 @@ class  ContentProcessor:
         self.sections = {}    # dictionary of documentation sections
         self.section  = None  # current documentation section
 
-        self.chapters = []        # list of chapters
+        self.chapters = []    # list of chapters
+
+        self.headers  = {}    # dictionary of header macros
 
     def  set_section( self, section_name ):
         """set current section during parsing"""
@@ -511,6 +519,11 @@ class  DocBlock:
             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

src/tools/docmaker/tohtml.py

@@ -93,6 +93,10 @@ marker_header = '<table align=center width="87%" cellpadding=5><tr bgcolor="#EEE
 marker_inter  = "</b></em></td></tr><tr><td>"
 marker_footer = "</td></tr></table>"
 
+# Header location header/footer.
+header_location_header = '<table align=center width="87%"><tr><td>'
+header_location_footer = "</td></tr></table><br>"
+
 # Source code extracts header/footer.
 source_header = '<table align=center width="87%"><tr bgcolor="#D6E8FF"><td><pre>\n'
 source_footer = "\n</pre></table><br>"
@@ -162,6 +166,7 @@ class  HtmlFormatter( Formatter ):
         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 + \
@@ -259,7 +264,7 @@ class  HtmlFormatter( Formatter ):
 
     def  print_html_field( self, field ):
         if field.name:
-            print "<table><tr valign=top><td><p><b>" + field.name + "</b></p></td><td>"
+            print "<table><tr valign=top><td><b>" + field.name + "</b></td><td>"
 
         print self.make_html_items( field.items )
 
@@ -297,6 +302,7 @@ class  HtmlFormatter( Formatter ):
         return result
 
     def  print_html_field_list( self, fields ):
+        print "<p></p>"
         print "<table cellpadding=3 border=0>"
         for field in fields:
             if len( field.name ) > 22:
@@ -472,6 +478,21 @@ class  HtmlFormatter( Formatter ):
 
         # dump the block C source lines now
         if block.code:
+            header = ''
+            for f in self.headers.keys():
+                if block.source.filename.find( 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
+                print 'Defined in ' + header + '.'
+                print header_location_footer
+
             print source_header
             for l in block.code:
                 print self.html_source_quote( l, block.name )