update docmaker.py to support chapters and section block ordering

updated public header files, as well as "ftchapters.h" which only
contains comment that hold the list of section chapters..
This commit is contained in:
David Turner 2001-02-13 17:42:49 +00:00
parent 7fcdadc17a
commit cb36b4a37d
10 changed files with 425 additions and 169 deletions

View File

@ -1,3 +1,9 @@
2001-02-13 David Turner <david.turner@freetype.org>
* docs/docmaker.py, include/freetype/*.h: Updated the DocMaker script
to support chapters and section block ordering. Updated the public
header files accordingly.
2001-02-08 Tom Kacvinsky <tjk@ams.org>
* src/cff/cffparse.c (cff_parse_font_matrix): Removed an

View File

@ -55,6 +55,9 @@ marker_footer = "</td></tr></table></center>"
source_header = "<center><table width=87%><tr bgcolor=#D6E8FF width=100%><td><pre>"
source_footer = "</pre></table></center><br>"
chapter_header = "<center><table width=75%><tr><td><h2>"
chapter_inter = "</h2><ul>"
chapter_footer = "</ul></td></tr></table></center>"
current_section = None
@ -93,6 +96,16 @@ 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 ):
new_list = order_list[:]
for id in input_list:
if not id in order_list:
new_list.append(id)
return new_list
# The FreeType 2 reference is extracted from the source files. These contain
# various comment blocks that follow one of the following formats:
#
@ -229,7 +242,7 @@ class DocCode:
# line to avoid an additional blank line
#
sys.stdout.write( code_header )
for line in self.lines[0 : l]:
for line in self.lines[0 : l+1]:
sys.stdout.write( '\n' + line )
sys.stdout.write( code_footer )
@ -698,6 +711,13 @@ class DocBlock:
def location( self ):
return self.filename + ':' + str( self.lineno )
def print_warning( self, message ):
sys.stderr.write( "WARNING:"+self.location()+": "+message+'\n')
def print_error( self, message ):
sys.stderr.write( "ERROR:"+self.location()+": "+message+'\n')
sys.exit()
def dump( self ):
for i in range( len( self.items ) ):
@ -797,6 +817,7 @@ class DocSection:
self.elements = {}
self.list = []
self.filename = self.name + ".html"
self.chapter = None
# sys.stderr.write( "new section '" + self.name + "'" )
@ -806,15 +827,20 @@ class DocSection:
# section
#
if self.elements.has_key( block.name ):
sys.stderr.write( "ERROR - duplicate element definition for " +
"'" + block.name + "' in section '" +
self.name + "'" )
sys.exit()
print_error( "duplicate element definition for " +
"'" + block.name + "' in section '" + self.name + "'\n" +
"previous definition in '" + self.elements[block.name].location() + "'" )
self.elements[ block.name ] = block
self.list.append( block )
def print_warning( self, message ):
self.block.print_warning( message )
def print_error( self, message ):
self.block.print_error( message )
def dump_html( self, identifiers = None ):
"""make an HTML page from a given DocSection"""
@ -865,13 +891,12 @@ class DocSectionList:
# provide a new one.
#
if abstract:
stderr.write( "ERROR - duplicate section definition" +
" for '" + name + "'" )
stderr.write( "previous definition in" +
" '" + section.location() )
stderr.write( "second definition in" +
" '" + block.location() )
sys.quit()
print_error( "duplicate section definition" +
" for '" + name + "'\n" +
"previous definition in" +
" '" + section.block.location() + "'\n" +
"second definition in" +
" '" + block.location() + "'" )
else:
# The old section didn't contain an abstract; we are
# now going to replace it.
@ -935,42 +960,27 @@ class DocSectionList:
try:
words = element.get_words()
except:
sys.stderr.write(
"WARNING:" +
section.block.location() +
": invalid content in <order> marker\n" )
section.block.print_warning( "invalid content in <order> marker\n" )
if words:
for word in words:
block = self.identifiers.get( word )
if block:
if block.section == section:
order_list.append( word )
order_list.append( block )
else:
sys.stderr.write(
"WARNING:" +
section.block.location() +
": invalid reference to '" +
word +
"' defined in other section\n" )
section.block.print_warning( "invalid reference to '" +
word + "' defined in other section" )
else:
sys.stderr.write(
"WARNING:" +
section.block.location() +
": invalid reference to '" +
word + "'\n" )
section.block.print_warning( "invalid reference to '" + word + "'" )
# now sort the list of blocks according to the order list
#
new_list = []
old_list = section.list
for id in order_list:
new_list.append( section.elements[id] )
new_list = order_list[:]
for block in section.list:
if not block in order_list:
new_list.append(block)
for block in old_list:
if not block.name in order_list:
new_list.append( block )
section.list = new_list
section.list = new_list
# compute section filenames
#
@ -986,34 +996,6 @@ class DocSectionList:
self.index.sort( index_sort )
def dump_html_toc( self ):
# dump an html table of contents
#
old_stdout = sys.stdout
new_file = open( self.toc_filename, "w" )
sys.stdout = new_file
print html_header
print "<center><h1>Table of Contents</h1></center>"
print "<center><table cellpadding=5>"
for section in self.list:
if section.abstract:
print "<tr valign=top><td>"
sys.stdout.write( '<a href="' + section.filename + '">' )
sys.stdout.write( section.title )
sys.stdout.write( "</a></td><td>" + '\n' )
section.abstract.dump_html( self.identifiers )
print "</td></tr>"
print "</table></center>"
print html_footer
sys.stdout = old_stdout
def dump_html_sections( self ):
old_stdout = sys.stdout
@ -1066,6 +1048,146 @@ class DocSectionList:
# Filter a given list of DocBlocks. Returns a new list
# of DocBlock objects that only contains element whose
# "type" (i.e. first marker) is in the "types" parameter.
class DocChapter:
def __init__(self,block):
self.sections_names = [] # ordered list of section names
self.sections = [] # ordered list of DocSection objects for this chapter
self.block = block
# look for chapter title
content = block.find_content( "title" )
if content:
self.title = content.get_title()
else:
self.title = "UNKNOWN CHAPTER TITLE"
# look for section list
content = block.find_content( "sections" )
if not content:
block.print_error( "chapter has no <sections> content" )
# compute list of section names
slist = []
for item in content.items:
for element in item[1]:
try:
words = element.get_words()
l = len(slist)
slist[l:l] = words
except:
block.print_warning( "invalid content in <sections> marker" )
self.section_names = slist
class DocDocument:
def __init__( self ):
self.section_list = DocSectionList() # section list object
self.chapters = [] # list of chapters
self.lost_sections = [] # list of sections with no chapter
def append_block( self, block ):
if block.name:
content = block.find_content( "chapter" )
if content:
# it's a chapter definition - add it to our list
chapter = DocChapter( block )
self.chapters.append( chapter )
else:
self.section_list.append_block( block )
def prepare_chapters( self ):
# check section names
#
for chapter in self.chapters:
slist = []
for name in chapter.section_names:
section = self.section_list.sections.get(name)
if not section:
chapter.block.print_warning( "invalid reference to unknown section '"+name+"'" )
else:
section.chapter = chapter
slist.append( section )
chapter.sections = slist
for section in self.section_list.list:
if not section.chapter:
section.block.print_warning( "section '"+section.name+"' is not in any chapter" )
self.lost_sections.append( section )
def prepare_files( self, file_prefix = None ):
self.section_list.prepare_files( file_prefix )
self.prepare_chapters()
def dump_toc_html( self ):
# dump an html table of contents
#
old_stdout = sys.stdout
new_file = open( self.section_list.toc_filename, "w" )
sys.stdout = new_file
print html_header
print "<center><h1>Table of Contents</h1></center>"
for chapter in self.chapters:
print chapter_header + chapter.title + chapter_inter
print "<table cellpadding=5>"
for section in chapter.sections:
if section.abstract:
print "<tr valign=top><td>"
sys.stdout.write( '<a href="' + section.filename + '">' )
sys.stdout.write( section.title )
sys.stdout.write( "</a></td><td>" + '\n' )
section.abstract.dump_html( self.section_list.identifiers )
print "</td></tr>"
print "</table>"
print chapter_footer
# list lost sections
if self.lost_sections:
print chapter_header + "OTHER SECTIONS:" + chapter_inter
print "<table cellpadding=5>"
for section in self.lost_sections:
if section.abstract:
print "<tr valign=top><td>"
sys.stdout.write( '<a href="' + section.filename + '">' )
sys.stdout.write( section.title )
sys.stdout.write( "</a></td><td>" + '\n' )
section.abstract.dump_html( self.section_list.identifiers )
print "</td></tr>"
print "</table>"
print chapter_footer
print html_footer
sys.stdout = old_stdout
def dump_index_html( self ):
self.section_list.dump_html_index()
def dump_sections_html( self ):
self.section_list.dump_html_sections()
#
def filter_blocks_by_type( block_list, types ):
new_list = []
@ -1196,8 +1318,8 @@ def make_block_list():
# /* #.....
#
if format >= 4 and l > 2 and line2[0 : 2] == '/*':
if l < 4 or ( line2[3] != '@' and line2[3:4] != ' @' and
line2[3] != '#' and line2[3:4] != ' #'):
if l < 4 or ( line2[2] != '@' and line2[2:4] != ' @' and
line2[2] != '#' and line2[2:4] != ' #'):
add_new_block( list, fileinput.filename(),
lineno, block, source )
format = 0
@ -1333,26 +1455,27 @@ def main( argv ):
# now, sort the blocks into sections
#
section_list = DocSectionList()
document = DocDocument()
for block in list:
section_list.append_block( block )
document.append_block( block )
section_list.prepare_files( "ft2" )
document.prepare_files( "ft2" )
# dump the section list TOC and sections
#
section_list.dump_html_toc()
section_list.dump_html_sections()
section_list.dump_html_index()
document.dump_toc_html()
document.dump_sections_html()
document.dump_index_html()
## section_list = DocSectionList()
## for block in list:
## section_list.append_block( block )
##
## section_list.prepare_files( "ft2" )
# list2 = filter_blocks( list, ['type','macro','enum','constant','functype'] )
# list2 = list
# list2.sort( block_lexicographical_compare )
# dump_html_1( list2 )
# dump_doc_blocks( list )
# dump_block_lists( list )
# dump_html_1( list )
## # dump the section list TOC and sections
## #
## section_list.dump_html_toc()
## section_list.dump_html_sections()
## section_list.dump_html_index()
# If called from the command line

View File

@ -25,7 +25,6 @@
/* The `raster' component duplicates some of the declarations in */
/* freetype.h for stand-alone use if _FREETYPE_ isn't defined. */
/* */
#define _FREETYPE_
/*************************************************************************/
@ -56,21 +55,70 @@ FT_BEGIN_HEADER
/*************************************************************************/
/*************************************************************************/
/* */
/* <Section> */
/* base_interface */
/* */
/* <Title> */
/* Base Interface */
/* */
/* <Abstract> */
/* The FreeType 2 base font interface. */
/* */
/* <Description> */
/* This section describes the public high-level API of FreeType 2. */
/* */
/*************************************************************************/
/*************************************************************************
*
* <Section>
* base_interface
*
* <Title>
* Base Interface
*
* <Abstract>
* The FreeType 2 base font interface
*
* <Description>
* This section describes the public high-level API of FreeType 2
*
* <Order>
* FT_Library FT_Face FT_Size FT_GlyphSlot FT_CharMap FT_Encoding
*
* FT_FaceRec
*
* FT_FACE_FLAG_SCALABLE
* FT_FACE_FLAG_FIXED_SIZES
* FT_FACE_FLAG_FIXED_WIDTH
* FT_FACE_FLAG_HORIZONTAL
* FT_FACE_FLAG_VERTICAL
* FT_FACE_FLAG_SFNT
* FT_FACE_FLAG_KERNING
* FT_FACE_FLAG_MULTIPLE_MASTERS
* FT_FACE_FLAG_GLYPH_NAMES
* FT_FACE_FLAG_EXTERNAL_STREAM
* FT_FACE_FLAG_FAST_GLYPHS
*
* FT_STYLE_FLAG_BOLD
* FT_STYLE_FLAG_ITALIC
*
* FT_SizeRec FT_Size_Metrics
*
* FT_GlyphSlotRec FT_Glyph_Metrics FT_SubGlyph
*
* FT_Bitmap_Size
*
* FT_Init_FreeType FT_Done_FreeType
*
* FT_New_Face FT_Done_Face FT_New_Memory_Face
* FT_Open_Face FT_Open_Args FT_Open_Flags FT_Parameter
* FT_Attach_File FT_Attach_Stream
*
* FT_Set_Char_Size FT_Set_Pixel_Sizes FT_Set_Transform
* FT_Load_Glyph FT_Get_Char_Index FT_Load_Char
*
* FT_LOAD_DEFAULT FT_LOAD_RENDER FT_LOAD_MONOCHROME
* FT_LOAD_LINEAR_DESIGN FT_LOAD_NO_SCALE FT_LOAD_NO_HINTING
* FT_LOAD_NO_BITMAP FT_LOAD_CROP_BITMAP
*
* FT_LOAD_VERTICAL_LAYOUT FT_LOAD_IGNORE_TRANSFORM
* FT_LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH FT_LOAD_FORCE_AUTOHINT
* FT_LOAD_NO_RECURSE FT_LOAD_PEDANTIC
*
* FT_Render_Glyph FT_Render_Mode
* FT_Get_Kerning FT_Kerning_Mode FT_Get_Glyph_Name
*
* FT_CharMapRec FT_Select_Charmap FT_Set_Charmap
*
*/
/*************************************************************************/
@ -968,7 +1016,7 @@ FT_BEGIN_HEADER
/* generic :: A typeless pointer which is unused by the */
/* FreeType library or any of its drivers. It */
/* can be used by client applications to link */
/* their own data to each size object. */
/* their own data to each glyph slot object. */
/* */
/* metrics :: The metrics of the last loaded glyph in the */
/* slot. The returned values depend on the last */
@ -1051,9 +1099,10 @@ FT_BEGIN_HEADER
/* image format. */
/* */
/* <Note> */
/* If FT_Load_Glyph() is called with default flags (FT_LOAD_DEFAULT), */
/* the glyph image is loaded in the glyph slot in its native format */
/* (e.g. a vectorial outline for TrueType and Type 1 formats). */
/* If @FT_Load_Glyph() is called with default flags (see */
/* @FT_LOAD_DEFAULT ) the glyph image is loaded in the glyph slot in */
/* its native format (e.g. a vectorial outline for TrueType and */
/* Type 1 formats). */
/* */
/* This image can later be converted into a bitmap by calling */
/* FT_Render_Glyph(). This function finds the current renderer for */
@ -1295,14 +1344,10 @@ FT_BEGIN_HEADER
/* slot for the face object which can be accessed directly through */
/* `face->glyph'. */
/* */
/* Note that additional slots can be added to each face with the */
/* FT_New_GlyphSlot() API function. Slots are linked in a single */
/* list through their `next' field. */
/* */
/* FT_New_Face() can be used to determine and/or check the font */
/* format of a given font resource. If the `face_index' field is */
/* negative, the function will _not_ return any face handle in */
/* `aface'. Its return value should be 0 if the resource is */
/* `aface'. Its return value should be 0 if the font format is */
/* recognized, or non-zero if not. */
/* */
FT_EXPORT( FT_Error ) FT_New_Face( FT_Library library,
@ -1341,14 +1386,10 @@ FT_BEGIN_HEADER
/* slot for the face object which can be accessed directly through */
/* `face->glyph'. */
/* */
/* Note that additional slots can be added to each face with the */
/* FT_New_GlyphSlot() API function. Slots are linked in a single */
/* list through their `next' field. */
/* */
/* FT_New_Memory_Face() can be used to determine and/or check the */
/* font format of a given font resource. If the `face_index' field */
/* is negative, the function will _not_ return any face handle in */
/* `aface'. Its return value should be 0 if the resource is */
/* `aface'. Its return value should be 0 if the font format is */
/* recognized, or non-zero if not. */
/* */
FT_EXPORT( FT_Error ) FT_New_Memory_Face( FT_Library library,
@ -1388,14 +1429,10 @@ FT_BEGIN_HEADER
/* slot for the face object which can be accessed directly through */
/* `face->glyph'. */
/* */
/* Note that additional slots can be added to each face with the */
/* FT_New_GlyphSlot() API function. Slots are linked in a single */
/* list through their `next' field. */
/* */
/* FT_Open_Face() can be used to determine and/or check the font */
/* format of a given font resource. If the `face_index' field is */
/* negative, the function will _not_ return any face handle in */
/* `*face'. Its return value should be 0 if the resource is */
/* `*face'. Its return value should be 0 if the font format is */
/* recognized, or non-zero if not. */
/* */
FT_EXPORT( FT_Error ) FT_Open_Face( FT_Library library,
@ -2140,6 +2177,27 @@ FT_BEGIN_HEADER
FT_ULong charcode );
/*************************************************************************/
/* */
/* <Section> */
/* computations */
/* */
/* <Title> */
/* Computations */
/* */
/* <Abstract> */
/* Crunching fixed numbers and vectors */
/* */
/* <Description> */
/* This section contains various functions used to perform */
/* computations on 16.16 fixed-float numbers or 2d vectors. */
/* */
/* <Order> */
/* FT_MulDiv FT_MulFix FT_DivFix FT_Vector_Transform */
/* FT_Matrix_Multiply FT_Matrix_Invert */
/* */
/*************************************************************************/
/*************************************************************************/
/* */
/* <Function> */

View File

@ -0,0 +1,43 @@
/*************************************************************************
*
* <Chapter> core_api
*
* <Title> Core API
*
* <Sections>
* basic_types
* base_interface
* glyph_management
* mac_specific
* multiple_masters
* truetype_tables
* type1_tables
* sfnt_names
* module_management
* system_interface
*/
/*************************************************************************
*
* <Chapter> cache_subsystem
*
* <Title> Cache Sub-System
*
* <Sections>
* cache_subsystem
*
*/
/*************************************************************************
*
* <Chapter> support_api
*
* <Title> Support API
*
* <Sections>
* computations
* list_processing
* outline_processing
* raster
*/

View File

@ -412,7 +412,7 @@ FT_BEGIN_HEADER
/*************************************************************************/
/* */
/* <Section> */
/* base_interface */
/* computations */
/* */
/*************************************************************************/

View File

@ -77,6 +77,34 @@ FT_BEGIN_HEADER
} FT_Vector;
/*************************************************************************/
/* */
/* <Struct> */
/* FT_BBox */
/* */
/* <Description> */
/* A structure used to hold an outline's bounding box, i.e., the */
/* coordinates of its extrema in the horizontal and vertical */
/* directions. */
/* */
/* <Fields> */
/* xMin :: The horizontal minimum (left-most). */
/* */
/* yMin :: The vertical minimum (bottom-most). */
/* */
/* xMax :: The horizontal maximum (right-most). */
/* */
/* yMax :: The vertical maximum (top-most). */
/* */
typedef struct FT_BBox_
{
FT_Pos xMin, yMin;
FT_Pos xMax, yMax;
} FT_BBox;
/*************************************************************************/
/* */
/* <Enum> */
@ -649,33 +677,6 @@ FT_BEGIN_HEADER
typedef struct FT_RasterRec_* FT_Raster;
/*************************************************************************/
/* */
/* <Struct> */
/* FT_BBox */
/* */
/* <Description> */
/* A structure used to hold an outline's bounding box, i.e., the */
/* coordinates of its extrema in the horizontal and vertical */
/* directions. */
/* */
/* <Fields> */
/* xMin :: The horizontal minimum (left-most). */
/* */
/* yMin :: The vertical minimum (bottom-most). */
/* */
/* xMax :: The horizontal maximum (right-most). */
/* */
/* yMax :: The vertical maximum (top-most). */
/* */
typedef struct FT_BBox_
{
FT_Pos xMin, yMin;
FT_Pos xMax, yMax;
} FT_BBox;
/*************************************************************************/
/* */
/* <Struct> */

View File

@ -50,6 +50,13 @@ FT_BEGIN_HEADER
/* This section contains various definitions related to list */
/* processing using doubly-linked nodes. */
/* */
/* <Order> */
/* FT_List FT_ListNode FT_ListRec FT_ListNodeRec */
/* */
/* FT_List_Add FT_List_Insert FT_List_Find FT_List_Remove FT_List_Up */
/* FT_List_Iterate FT_List_Iterator FT_List_Finalize */
/* FT_List_Destructor */
/* */
/*************************************************************************/

View File

@ -38,7 +38,7 @@ FT_BEGIN_HEADER
/*************************************************************************/
/* */
/* <Section> */
/* Mac_Specific */
/* mac_specific */
/* */
/* <Title> */
/* Mac-Specific Interface */

View File

@ -44,6 +44,19 @@ FT_BEGIN_HEADER
/* glyph images known as `outlines'. These can also be measured, */
/* transformed, and converted into bitmaps and pixmaps. */
/* */
/* <Order> */
/* FT_Outline FT_Outline_Flags */
/* FT_Outline_New FT_Outline_Done FT_Outline_Copy */
/* FT_Outline_Translate FT_Outline_Transform FT_Outline_Reverse */
/* */
/* FT_Outline_Get_CBox FT_Outline_Get_BBox */
/* */
/* FT_Outline_Get_Bitmap FT_Outline_Render */
/* */
/* FT_Outline_Decompose FT_Outline_Funcs FT_Outline_MoveTo_Func */
/* FT_Outline_LineTo_Func FT_Outline_ConicTo_Func */
/* FT_Outline_CubicTo_Func */
/* */
/*************************************************************************/

View File

@ -30,28 +30,33 @@
FT_BEGIN_HEADER
/*************************************************************************/
/* */
/* <Section> */
/* basic_types */
/* */
/* <Title> */
/* Basic Data Types */
/* */
/* <Abstract> */
/* The basic data types defined by the library. */
/* */
/* <Description> */
/* This section contains the basic data types defined by FreeType 2, */
/* ranging from simple scalar types to font specific ones. */
/* */
/* <Order> */
/* FT_Byte FT_Char FT_Int FT_UInt FT_Short FT_UShort FT_Long */
/* FT_ULong FT_Fixed FT_Pointer FT_Vector FT_Matrix FT_BBox */
/* */
/*************************************************************************/
/*************************************************************************
*
* <Section>
* basic_types
*
* <Title>
* Basic Types
*
* <Abstract>
* The basic data types defined by the library.
*
* <Description>
* This section contains the basic data types defined by FreeType 2,
* ranging from simple scalar types to font specific ones
*
* <Order>
* FT_Byte FT_Char FT_Int FT_UInt FT_Short FT_UShort FT_Long FT_ULong
* FT_Bool FT_Error FT_Fixed FT_Pointer FT_Pos FT_Vector FT_BBox
* FT_Matrix
*
* FT_Generic FT_Generic_Finalizer
*
* FT_Bitmap FT_Pixel_Mode FT_Palette_Mode FT_Glyph_Format FT_IMAGE_TAG
* FT_Glyph_Format
*
*/
/*************************************************************************/
/* */
/* <Type> */