diff --git a/ChangeLog b/ChangeLog index e3a53d212..8f568a012 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2001-02-13 David Turner + + * 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 * src/cff/cffparse.c (cff_parse_font_matrix): Removed an diff --git a/docs/docmaker.py b/docs/docmaker.py index 592731d76..e48dac16e 100644 --- a/docs/docmaker.py +++ b/docs/docmaker.py @@ -55,6 +55,9 @@ marker_footer = "" source_header = "
"
 source_footer = "

" +chapter_header = "

" +chapter_inter = "

    " +chapter_footer = "
" 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 marker\n" ) + section.block.print_warning( "invalid content in 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 "

Table of Contents

" - - print "
" - for section in self.list: - if section.abstract: - print "" - - print "
" - sys.stdout.write( '' ) - sys.stdout.write( section.title ) - sys.stdout.write( "" + '\n' ) - section.abstract.dump_html( self.identifiers ) - print "
" - - 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 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 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 "

Table of Contents

" + + for chapter in self.chapters: + + print chapter_header + chapter.title + chapter_inter + + print "" + for section in chapter.sections: + if section.abstract: + print "" + + print "
" + sys.stdout.write( '' ) + sys.stdout.write( section.title ) + sys.stdout.write( "" + '\n' ) + section.abstract.dump_html( self.section_list.identifiers ) + print "
" + + print chapter_footer + + # list lost sections + if self.lost_sections: + print chapter_header + "OTHER SECTIONS:" + chapter_inter + + print "" + for section in self.lost_sections: + if section.abstract: + print "" + + print "
" + sys.stdout.write( '' ) + sys.stdout.write( section.title ) + sys.stdout.write( "" + '\n' ) + section.abstract.dump_html( self.section_list.identifiers ) + print "
" + + 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 diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h index 6f98776e3..cc5e521bf 100644 --- a/include/freetype/freetype.h +++ b/include/freetype/freetype.h @@ -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 /*************************************************************************/ - /*************************************************************************/ - /* */ - /*
*/ - /* base_interface */ - /* */ - /* */ - /* 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> */ diff --git a/include/freetype/ftchapters.h b/include/freetype/ftchapters.h new file mode 100644 index 000000000..285f0c1d5 --- /dev/null +++ b/include/freetype/ftchapters.h @@ -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 + */ + + diff --git a/include/freetype/ftglyph.h b/include/freetype/ftglyph.h index 60dcf3592..0e27c0417 100644 --- a/include/freetype/ftglyph.h +++ b/include/freetype/ftglyph.h @@ -412,7 +412,7 @@ FT_BEGIN_HEADER /*************************************************************************/ /* */ /* <Section> */ - /* base_interface */ + /* computations */ /* */ /*************************************************************************/ diff --git a/include/freetype/ftimage.h b/include/freetype/ftimage.h index 8db53395f..22e93bb9e 100644 --- a/include/freetype/ftimage.h +++ b/include/freetype/ftimage.h @@ -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> */ diff --git a/include/freetype/ftlist.h b/include/freetype/ftlist.h index d0b96df4d..d6d8a27f6 100644 --- a/include/freetype/ftlist.h +++ b/include/freetype/ftlist.h @@ -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 */ + /* */ /*************************************************************************/ diff --git a/include/freetype/ftmac.h b/include/freetype/ftmac.h index 442a27c7c..4c7f06938 100644 --- a/include/freetype/ftmac.h +++ b/include/freetype/ftmac.h @@ -38,7 +38,7 @@ FT_BEGIN_HEADER /*************************************************************************/ /* */ /* <Section> */ - /* Mac_Specific */ + /* mac_specific */ /* */ /* <Title> */ /* Mac-Specific Interface */ diff --git a/include/freetype/ftoutln.h b/include/freetype/ftoutln.h index 52b2d57a0..ffc8e1572 100644 --- a/include/freetype/ftoutln.h +++ b/include/freetype/ftoutln.h @@ -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 */ + /* */ /*************************************************************************/ diff --git a/include/freetype/fttypes.h b/include/freetype/fttypes.h index e95d8488e..14cd791de 100644 --- a/include/freetype/fttypes.h +++ b/include/freetype/fttypes.h @@ -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> */