Chiebot-Mirror
/
freetype
mirror of https://github.com/freetype/freetype.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

improved the docmaker script

Browse Source
VER-2-0-4-PATCH
David Turner 24 years ago
parent e8c8e30163
commit 691e2426f4
9 changed files with 525 additions and 109 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 5
      ChangeLog
  2. 233
      docs/docmaker.py
  3. 65
      include/freetype/freetype.h
  4. 32
      include/freetype/ftimage.h
  5. 19
      include/freetype/ftlist.h
  6. 15
      include/freetype/ftoutln.h
  7. 177
      include/freetype/ftsystem.h
  8. 71
      include/freetype/fttypes.h
  9. 17
      include/freetype/tttables.h

5
ChangeLog
Unescape View File

@ -1,3 +1,8 @@
2000-01-09 David Turner <david.turner@freetype.org>
* docs/docmaker.py: improved script to generate table of contents and
index pages.
2000-01-04 Werner Lemberg <wl@gnu.org>
* include/freetype/ttnameid.h: Updated Unicode code range comments.

233
docs/docmaker.py
Unescape View File

@ -18,7 +18,6 @@ html_header = """
<style content="text/css">
P { text-align=justify }
H1 { text-align=center }
H2 { text-align=center }
LI { text-align=justify }
</style>
</header>
@ -55,13 +54,20 @@ code_footer = """
para_header = "<p>"
para_footer = "</p>"
block_header = """<center><hr width="550"><table width="550"><tr><td>"""
block_footer = "</table></center>"
block_header = """<center><hr width="750"><table width="750"><tr><td>"""
block_footer = "</td></tr></table></center>"
source_header = """<center><table width="550"><tr bgcolor="#D6E8FF" width="100%"><td><pre>
description_header = """<center><table width="650"><tr><td>"""
description_footer = """</td></tr></table></center><br>"""
marker_header = """<center><table width="650" cellpadding=5><tr bgcolor="#EEEEFF"><td><em><b>"""
marker_inter = "</b></em></td></tr><tr><td>"
marker_footer = "</td></tr></table></center>"
source_header = """<center><table width="650"><tr bgcolor="#D6E8FF" width="100%"><td><pre>
"""
source_footer = """</pre></table></center>
<br><br>
<br>
"""
@ -213,6 +219,7 @@ class DocCode:
#
# The paragraph is filled line by line by the parser.
#
class DocParagraph:
def __init__( self ):
@ -314,6 +321,7 @@ class DocParagraph:
# pass a list of input text lines in the "lines_list" parameter.
#
#
class DocContent:
def __init__( self, lines_list ):
@ -467,7 +475,7 @@ class DocContent:
else:
if not in_table:
print "<table cellpadding=4><tr valign=top><td>"
print '<table cellpadding=4><tr valign=top><td>'
in_table = 1
else:
print "</td></tr><tr valign=top><td>"
@ -481,6 +489,31 @@ class DocContent:
print "</td></tr></table>"
def dump_html_in_table( self ):
n = len( self.items )
in_table = 0
for i in range( n ):
item = self.items[i]
field = item[0]
if not field:
if item[1]:
print "<tr><td colspan=2>"
for element in item[1]:
element.dump_html()
print "</td></tr>"
else:
print "<tr><td><b>" + field + "</b></td><td>"
for element in item[1]:
element.dump_html()
print "</td></tr>"
######################################################################################
#
#
@ -494,14 +527,21 @@ class DocContent:
# "self.source" is simply a list of text lines taken from the
# uncommented source itself.
#
# Finally, "self.identifier" is a simple identifier used to
# uniquely identify the block.
# Finally, "self.name" is a simple identifier used to
# uniquely identify the block. it is taken from the first word of the first
# paragraphe of the first marker of a given block, i.e:
#
# <Type> Goo
# <Description> Bla bla bla
#
# will have a name of "Goo"
#
class DocBlock:
def __init__( self, block_line_list = [], source_line_list = [] ):
self.items = [] # current ( marker, contents ) list
self.identifier = None
self.items = [] # current ( marker, contents ) list
self.section = None # section this block belongs to
marker = None # current marker
content = [] # current content lines list
alphanum = string.letters + string.digits + "_"
@ -572,8 +612,6 @@ class DocBlock:
if l > 0 and marker:
content = DocContent( lines )
self.items.append( ( string.lower( marker ), content ) )
if not self.identifier:
self.identifier = content.get_identifier()
def find_content( self, marker ):
@ -594,14 +632,20 @@ class DocBlock:
types = [ 'type', 'struct', 'functype', 'function', 'constant',
'enum', 'macro' ]
parameters = [ 'input', 'inout', 'output', 'return' ]
if not self.items:
return
# place html anchor when needed
if self.name:
print '<a name="'+self.name+'">'
# start of a block
#
print block_header
print "<h2>" + self.identifier + "</h2>"
print "<h4>" + self.name + "</h4>"
# print source code
#
@ -617,6 +661,8 @@ class DocBlock:
print line
print source_footer
in_table = 0
# dump each (marker,content) element
#
for element in self.items:
@ -624,17 +670,19 @@ class DocBlock:
content = element[1]
if marker == "description":
print "<ul>"
print description_header
content.dump_html()
print "</ul>"
print description_footer
elif not ( marker in types ):
print "<h4>" + marker + "</h4>"
print "<ul>"
content.dump_html()
print "</ul>"
print ""
print marker_header
print marker
print marker_inter
content.dump_html()
print marker_footer
print ""
print block_footer
@ -649,6 +697,8 @@ class DocBlock:
#
# <Section> Basic_Data_Types
#
# <Title> FreeType 2 Basic Data Types
#
# <Abstract>
# Definitions of basic FreeType data types
#
@ -663,11 +713,6 @@ class DocSection:
self.name = string.lower( block.name )
self.abstract = block.find_content( "abstract" )
self.description = block.find_content( "description" )
title_content = block.find_content( "title" )
if title_content:
self.title = title_content.get_title()
else:
self.titles = "UNKNOWN_SECTION_TITLE!"
self.elements = {}
self.list = []
self.filename = self.name + ".html"
@ -722,6 +767,7 @@ class DocSectionList:
self.sections = {}
self.list = []
self.current_section = None
self.index = [] # sorted list of blocks that are not sections
def append_section( self, block ):
@ -748,6 +794,7 @@ class DocSectionList:
#
section.abstract = abstract
section.description = block.find_content( "description" )
section.block = block
else:
# a new section
@ -755,7 +802,7 @@ class DocSectionList:
section = DocSection( block )
self.sections[name] = section
self.list.append( section )
self.current_section = section
@ -768,11 +815,44 @@ class DocSectionList:
elif self.current_section:
# sys.stderr.write( " new block" )
self.current_section.add_element( block )
block.section = self.current_section
self.index.append( block )
def prepare_files( self, file_prefix = None ):
# prepare the section list, by computing section filenames
# and the index
if file_prefix:
prefix = file_prefix + "-"
else:
prefix = ""
# compute section names
for section in self.sections.values():
title_content = section.block.find_content( "title" )
if title_content:
section.title = title_content.get_title()
else:
section.title = "UNKNOWN_SECTION_TITLE!"
# compute section filenames
for section in self.sections.values():
section.filename = prefix + section.name + ".html"
self.toc_filename = prefix + "toc.html"
self.index_filename = prefix + "index.html"
# compute the sorted block list for the index
self.index.sort( block_lexicographical_compare )
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>"
@ -790,24 +870,64 @@ class DocSectionList:
print html_footer
sys.stdout = old_stdout
def dump_html_sections( self ):
old_stdout = sys.stdout
for section in self.sections.values():
new_file = open( section.filename, "w" )
sys.stdout = new_file
section.dump_html()
new_file.close()
if section.filename:
new_file = open( section.filename, "w" )
sys.stdout = new_file
section.dump_html()
new_file.close()
sys.stdout = old_stdout
def dump_html_index( self ):
old_stdout = sys.stdout
new_file = open( self.index_filename, "w" )
sys.stdout = new_file
num_columns = 3
total = len( self.index )
line = 0
print html_header
print "<center><h1>General Index</h1></center>"
print "<center><table cellpadding=5><tr valign=top><td>"
for block in self.index:
print '<a href="'+block.section.filename+'#'+block.name+'">'
print block.name
print "</a><br>"
if line*num_columns >= total:
print "</td><td>"
line = 0
else:
line = line+1
print "</tr></table></center>"
print html_footer
sys.stdout = old_stdout
# 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.
#
def filter_blocks( block_list, types ):
def filter_blocks_by_type( block_list, types ):
new_list = []
for block in block_list:
if block.items:
@ -819,17 +939,21 @@ def filter_blocks( block_list, types ):
return new_list
def filter_section_blocks( block ):
return block.section != None
# Perform a lexicographical comparison of two DocBlock
# objects. Returns -1, 0 or 1.
#
def block_lexicographical_compare( b1, b2 ):
if not b1.identifier:
if not b1.name:
return -1
if not b2.identifier:
if not b2.name:
return 1
id1 = string.lower( b1.identifier )
id2 = string.lower( b2.identifier )
id1 = string.lower( b1.name )
id2 = string.lower( b2.name )
if id1 < id2:
return -1
@ -839,15 +963,6 @@ def block_lexicographical_compare( b1, b2 ):
return 1
def block_make_list( source_block_list ):
list = []
for block in source_block_list:
docblock = DocBlock( block[0], block[1] )
list.append( docblock )
return list
# dump a list block as a single HTML page
#
@ -862,7 +977,7 @@ def dump_html_1( block_list ):
def make_block_list():
def make_block_list_inner():
"""parse a file and extract comments blocks from it"""
list = []
@ -1013,6 +1128,21 @@ def make_block_list():
return list
# create a list of DocBlock elements
#
def make_block_list():
source_block_list = make_block_list_inner()
list = []
for block in source_block_list:
docblock = DocBlock( block[0], block[1] )
list.append( docblock )
return list
# This function is only used for debugging
#
def dump_block_list( list ):
@ -1029,17 +1159,26 @@ def dump_block_list( list ):
def main( argv ):
"""main program loop"""
# we begin by simply building a list of DocBlock elements
#
sys.stderr.write( "extracting comment blocks from sources...\n" )
list = make_block_list()
list = block_make_list(list)
# now, sort the blocks into sections
#
section_list = DocSectionList()
for block in list:
section_list.append_block( block )
section_list.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()
# list2 = filter_blocks( list, ['type','macro','enum','constant', 'functype'] )
# list2 = list
# list2.sort( block_lexicographical_compare )

65
include/freetype/freetype.h
Unescape View File

@ -55,6 +55,18 @@ FT_BEGIN_HEADER
/*************************************************************************/
/*************************************************************************/
/*************************************************************************
*
* <Section> Base_Interface
*
* <Title> Base Interface
*
* <Abstract>
* The FreeType 2 base font interface
*
* <Description>
* This sections details the public high-level API of FreeType 2
*/
/*************************************************************************/
/* */
@ -99,59 +111,6 @@ FT_BEGIN_HEADER
} FT_Glyph_Metrics;
/*************************************************************************/
/* */
/* <FuncType> */
/* FT_Generic_Finalizer */
/* */
/* <Description> */
/* Describes a function used to destroy the `client' data of any */
/* FreeType object. See the description of the FT_Generic type for */
/* details of usage. */
/* */
/* <Input> */
/* The address of the FreeType object which is under finalization. */
/* Its client data is accessed through its `generic' field. */
/* */
typedef void (*FT_Generic_Finalizer)(void* object);
/*************************************************************************/
/* */
/* <Struct> */
/* FT_Generic */
/* */
/* <Description> */
/* Client applications often need to associate their own data to a */
/* variety of FreeType core objects. For example, a text layout API */
/* might want to associate a glyph cache to a given size object. */
/* */
/* Most FreeType object contains a `generic' field, of type */
/* FT_Generic, which usage is left to client applications and font */
/* servers. */
/* */
/* It can be used to store a pointer to client-specific data, as well */
/* as the address of a `finalizer' function, which will be called by */
/* FreeType when the object is destroyed (for example, the previous */
/* client example would put the address of the glyph cache destructor */
/* in the `finalizer' field). */
/* */
/* <Fields> */
/* data :: A typeless pointer to any client-specified data. This */
/* field is completely ignored by the FreeType library. */
/* */
/* finalizer :: A pointer to a `generic finalizer' function, which */
/* will be called when the object is destroyed. If this */
/* field is set to NULL, no code will be called. */
/* */
typedef struct FT_Generic_
{
void* data;
FT_Generic_Finalizer finalizer;
} FT_Generic;
/*************************************************************************/
/* */
/* <Struct> */

32
include/freetype/ftimage.h
Unescape View File

@ -33,6 +33,11 @@
FT_BEGIN_HEADER
/***********************************************************************
*
* <Section> Basic_Types
*
*/
/*************************************************************************/
/* */
@ -226,6 +231,12 @@ FT_BEGIN_HEADER
} FT_Bitmap;
/***********************************************************************
*
* <Section> outline_processing
*
*/
/*************************************************************************/
/* */
/* <Struct> */
@ -346,7 +357,8 @@ FT_BEGIN_HEADER
} FT_Outline_Flags;
/* */
#define FT_CURVE_TAG( flag ) ( flag & 3 )
#define FT_Curve_Tag_On 1
@ -516,6 +528,12 @@ FT_BEGIN_HEADER
} FT_Outline_Funcs;
/***********************************************************************
*
* <Section> Basic_Types
*
*/
/*************************************************************************/
/* */
/* <Macro> */
@ -594,6 +612,18 @@ FT_BEGIN_HEADER
/* */
/*************************************************************************/
/************************************************************************
*
* <Section> Raster
*
* <Title> Scanline converter
*
* <Abstract>
* How vectorial outlines are converted into bitmaps and pixmaps
*
* <Description>
* This section contains technical definitions
*/
/*************************************************************************/
/* */

19
include/freetype/ftlist.h
Unescape View File

@ -34,7 +34,21 @@
FT_BEGIN_HEADER
/**************************************************************************
*
* <Section> list_processing
*
* <Title> List Processing
*
* <Abstract>
* simple management of lists
*
* <Description>
* This section contains various definitions related to list processing
* using doubly-linked nodes.
*
*/
/*************************************************************************/
/* */
/* <Function> */
@ -213,7 +227,8 @@ FT_BEGIN_HEADER
FT_Memory memory,
void* user );
/* */
FT_END_HEADER
#endif /* __FTLIST_H__ */

15
include/freetype/ftoutln.h
Unescape View File

@ -27,6 +27,21 @@
FT_BEGIN_HEADER
/*************************************************************************/
/* */
/* <Section> outline_processing */
/* */
/* <Title> Outline Processing */
/* */
/* <Abstract> */
/* Functions to create, transform and render vectorial glyph images */
/* */
/* <Description> */
/* This sections contains routines used to create and destroy */
/* scalable glyph images known as "outlines". These can also be */
/* measured, transformed and converted into bitmaps, pixmaps and */
/* */
/* */
/*************************************************************************/
/* */

177
include/freetype/ftsystem.h
Unescape View File

@ -25,6 +25,22 @@
FT_BEGIN_HEADER
/**************************************************************************
*
* <Section> system_interface
*
* <Title> System Interface
*
* <Abstract>
* How FreeType manages memory and i/o
*
* <Description>
* This section contains various definitions related to memory
* management and i/o access. You'll need to understand this
* information if you want to use a custom memory manager or
* you own input i/o streams
*
*/
/*************************************************************************/
/* */
@ -32,22 +48,88 @@ FT_BEGIN_HEADER
/* */
/*************************************************************************/
/**********************************************************************
*
* @type: FT_Memory
*
* @description:
* a handle to a given memory manager object, defined with a
* @FT_MemoryRec structure.
*/
typedef struct FT_MemoryRec_* FT_Memory;
/**********************************************************************
*
* @functype: FT_Alloc_Func
*
* @description:
* a function used to allocate "size" bytes from "memory"
*
* @input:
* memory :: handle to source memory manager
* size :: size in bytes to allocate
*
* @return:
* address of new memory block. 0 in case of failure
*/
typedef void* (*FT_Alloc_Func)( FT_Memory memory,
long size );
/**********************************************************************
*
* @functype: FT_Free_Func
*
* @description:
* a function used to release a given block of memory
*
* @input:
* memory :: handle to source memory manager
* block :: address of target memory block
*/
typedef void (*FT_Free_Func)( FT_Memory memory,
void* block );
/**********************************************************************
*
* @functype: FT_Realloc_Func
*
* @description:
* a function used to re-allocate a given block of memory
*
* @input:
* memory :: handle to source memory manager
* cur_size :: the block's current size in bytes
* new_size :: the block's requested new size
* block :: the block's current address
*
* @return:
* new block address. 0 in case of memory shortage.
*
* @note:
* note that in case of error, the old block must still be available
*/
typedef void* (*FT_Realloc_Func)( FT_Memory memory,
long cur_size,
long new_size,
void* block );
/**********************************************************************
*
* @struct: FT_MemoryRec
*
* @description:
* a structure used to describe a given memory manager to FreeType 2
*
* @fields:
* user ::
* alloc ::
* free ::
* realloc ::
*
*/
struct FT_MemoryRec_
{
void* user;
@ -64,6 +146,26 @@ FT_BEGIN_HEADER
/*************************************************************************/
/************************************************************************
*
* @type: FT_Stream
*
* @description:
* a handle to an input stream.
*/
typedef struct FT_StreamRec_* FT_Stream;
/************************************************************************
*
* @struct: FT_StreamDesc
*
* @description:
* a union type used to store either a long or a pointer. This is
* used to store a file descriptor or a FILE* in an input stream
*
*/
typedef union FT_StreamDesc_
{
long value;
@ -72,17 +174,80 @@ FT_BEGIN_HEADER
} FT_StreamDesc;
typedef struct FT_StreamRec_* FT_Stream;
/************************************************************************
*
* @functype: FT_Stream_IO
*
* @description:
* a function used to seek and read data from a given input stream
*
* @input:
* stream :: handle to source stream
* offset :: offset of read in stream (always from start)
* buffer :: address of read buffer
* count :: number of bytes to read from the stream
*
* @return:
* number of bytes effectively read by the stream
*
* @note:
* this function might be called to perform seek / skip with
* a "count" of 0
*/
typedef unsigned long (*FT_Stream_IO)( FT_Stream stream,
unsigned long offset,
unsigned char* buffer,
unsigned long count );
/************************************************************************
*
* @functype: FT_Stream_Close
*
* @description:
* a function used to close a given input stream
*
* @input:
* stream :: handle to target stream
*/
typedef void (*FT_Stream_Close)( FT_Stream stream );
/************************************************************************
*
* @struct: FT_StreamRec
*
* @description:
* a structure used to describe an input stream
*
* @input:
* base :: for memory-based stream, this is the address of the first
* stream byte in memory. this field should always be set to
* NULL for disk-based streams.
*
* size :: the stream size in bytes
* pos :: the current position within the stream
*
* descriptor :: this field is a union that can hold an integer or a pointer
* it is used by stream implementations to store file
* descriptors or FILE* pointers..
*
* pathname :: this field is completely ignored by FreeType, however,
* it's often useful during debugging to use it to store
* the stream's filename, where available
*
* read :: the stream's input function
* close :: the stream close function
*
* memory :: memory manager to use to preload frames. this is set
* internally by FreeType and shouldn't be touched by
* stream implementations
*
* cursor :: this field is set and used internally by FreeType
* when parsing frames.
*
* limit :: this field is set and used internally by FreeType
* when parsing frames.
*/
struct FT_StreamRec_
{
unsigned char* base;
@ -90,8 +255,7 @@ FT_BEGIN_HEADER
unsigned long pos;
FT_StreamDesc descriptor;
FT_StreamDesc pathname; /* ignored by FreeType -- */
/* useful for debugging */
FT_StreamDesc pathname;
FT_Stream_IO read;
FT_Stream_Close close;
@ -100,6 +264,7 @@ FT_BEGIN_HEADER
unsigned char* limit;
};
/* */
FT_END_HEADER

71
include/freetype/fttypes.h
Unescape View File

@ -29,6 +29,19 @@
FT_BEGIN_HEADER
/*************************************************************************/
/* */
/* <Section> Basic_Types */
/* */
/* <Title> Basic Data Types */
/* */
/* <Abstract> */
/* The basic data types defined by the library */
/* */
/* <Description> */
/* This sections contains the basic data types defined by FreeType 2, */
/* rangine from simple scalar types to font specific ones */
/* */
/*************************************************************************/
/* */
@ -275,6 +288,60 @@ FT_BEGIN_HEADER
} FT_Matrix;
/*************************************************************************/
/* */
/* <FuncType> */
/* FT_Generic_Finalizer */
/* */
/* <Description> */
/* Describes a function used to destroy the `client' data of any */
/* FreeType object. See the description of the FT_Generic type for */
/* details of usage. */
/* */
/* <Input> */
/* The address of the FreeType object which is under finalization. */
/* Its client data is accessed through its `generic' field. */
/* */
typedef void (*FT_Generic_Finalizer)(void* object);
/*************************************************************************/
/* */
/* <Struct> */
/* FT_Generic */
/* */
/* <Description> */
/* Client applications often need to associate their own data to a */
/* variety of FreeType core objects. For example, a text layout API */
/* might want to associate a glyph cache to a given size object. */
/* */
/* Most FreeType object contains a `generic' field, of type */
/* FT_Generic, which usage is left to client applications and font */
/* servers. */
/* */
/* It can be used to store a pointer to client-specific data, as well */
/* as the address of a `finalizer' function, which will be called by */
/* FreeType when the object is destroyed (for example, the previous */
/* client example would put the address of the glyph cache destructor */
/* in the `finalizer' field). */
/* */
/* <Fields> */
/* data :: A typeless pointer to any client-specified data. This */
/* field is completely ignored by the FreeType library. */
/* */
/* finalizer :: A pointer to a `generic finalizer' function, which */
/* will be called when the object is destroyed. If this */
/* field is set to NULL, no code will be called. */
/* */
typedef struct FT_Generic_
{
void* data;
FT_Generic_Finalizer finalizer;
} FT_Generic;
/*************************************************************************/
/* */
/* <Macro> */
@ -299,6 +366,10 @@ FT_BEGIN_HEADER
/*************************************************************************/
/*************************************************************************/
/**************************************************************************
*
* <Section> list_processing
*/
/*************************************************************************/
/* */

17
include/freetype/tttables.h
Unescape View File

@ -27,6 +27,19 @@
FT_BEGIN_HEADER
/*************************************************************************/
/* */
/* <Section> TrueType_Tables */
/* */
/* <Title> TrueType Tables */
/* */
/* <Abstract> */
/* TrueType-specific table types and functions */
/* */
/* <Description> */
/* This sections contains the definition of TrueType-specific tables */
/* as well as some routines used to access and process them. */
/* */
/*************************************************************************/
/* */
@ -520,6 +533,8 @@ FT_BEGIN_HEADER
} TT_MaxProfile;
/* */
typedef enum
{
ft_sfnt_head = 0,
@ -569,6 +584,8 @@ FT_BEGIN_HEADER
FT_Sfnt_Tag tag );
/* */
FT_END_HEADER
#endif /* __TTTABLES_H__ */

Write Preview
Loading…
Cancel
Save