updated documentation in public header files
diff --git a/ChangeLog b/ChangeLog
index b1215b7..ef0bfa0 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,7 +1,11 @@
2000-01-09 David Turner <david.turner@freetype.org>
* docs/docmaker.py: improved script to generate table of contents and
- index pages.
+ index pages. it also supports wildcards on non Unix systems
+
+ * include/freetype/*.h, include/freetype/cache/*.h: updated comments
+ to include section definitions / delimitations for the API Reference
+ generator..
2000-01-04 Werner Lemberg <wl@gnu.org>
diff --git a/docs/docmaker.py b/docs/docmaker.py
index c3b367d..c3d69c4 100644
--- a/docs/docmaker.py
+++ b/docs/docmaker.py
@@ -8,7 +8,7 @@
# - David
#
-import fileinput, sys, string
+import fileinput, sys, string, glob
html_header = """
<html>
@@ -771,7 +771,7 @@
def append_section( self, block ):
- name = block.name
+ name = string.lower( block.name )
abstract = block.find_content( "abstract" )
if self.sections.has_key( name ):
@@ -859,12 +859,13 @@
print "<center><table cellpadding=5>"
for section in self.list:
- print "<tr valign=top><td>"
- print '<a href="' + section.filename + '">'
- print section.title
- print "</a></td><td>"
- section.abstract.dump_html()
- print "</td></tr>"
+ if section.abstract:
+ print "<tr valign=top><td>"
+ print '<a href="' + section.filename + '">'
+ print section.title
+ print "</a></td><td>"
+ section.abstract.dump_html()
+ print "</td></tr>"
print "</table></center>"
@@ -980,6 +981,18 @@
def make_block_list_inner():
"""parse a file and extract comments blocks from it"""
+ file_list = []
+ sys.stderr.write( repr( sys.argv[1:] ) + '\n' )
+
+ for pathname in sys.argv[1:]:
+ newpath = glob.glob( pathname )
+ sys.stderr.write ( repr(newpath) + '\n' )
+ last = len(file_list)
+ file_list[last:last] = newpath
+
+ if len( file_list ) == 0:
+ file_list = None
+
list = []
block = []
format = 0
@@ -997,7 +1010,7 @@
source = []
state = 0
- for line in fileinput.input():
+ for line in fileinput.input( file_list ):
l = len( line )
if l > 0 and line[l - 1] == '\012':
line = line[0 : l - 1]
diff --git a/include/freetype/cache/ftcimage.h b/include/freetype/cache/ftcimage.h
index 58ed204..7c10ef5 100644
--- a/include/freetype/cache/ftcimage.h
+++ b/include/freetype/cache/ftcimage.h
@@ -35,6 +35,10 @@
FT_BEGIN_HEADER
+ /***
+ * <Section> cache_subsystem
+ */
+
/*************************************************************************/
/*************************************************************************/
/*************************************************************************/
@@ -60,7 +64,7 @@
/* monochrome bitmap */
#define ftc_image_mono ftc_image_format_bitmap | \
- ftc_image_flag_monochrome
+ ftc_image_flag_monochrome
/* anti-aliased bitmap */
#define ftc_image_grays ftc_image_format_bitmap
/* scaled outline */
@@ -159,6 +163,7 @@
FT_UInt gindex,
FT_Glyph *aglyph );
+ /* */
FT_END_HEADER
diff --git a/include/freetype/cache/ftcmanag.h b/include/freetype/cache/ftcmanag.h
index 72794da..40d107b 100644
--- a/include/freetype/cache/ftcmanag.h
+++ b/include/freetype/cache/ftcmanag.h
@@ -70,6 +70,9 @@
FT_BEGIN_HEADER
+ /***
+ * <Section> cache_subsystem
+ */
#define FTC_MAX_FACES_DEFAULT 2
#define FTC_MAX_SIZES_DEFAULT 4
diff --git a/include/freetype/cache/ftcsbits.h b/include/freetype/cache/ftcsbits.h
index 6de4ed4..e86ea9d 100644
--- a/include/freetype/cache/ftcsbits.h
+++ b/include/freetype/cache/ftcsbits.h
@@ -29,13 +29,60 @@
FT_BEGIN_HEADER
- /* handle to small bitmap */
+ /***
+ * <Section> cache_subsystem
+ */
+
+ /***********************************************************************
+ *
+ * <Type> FTC_SBit
+ *
+ * <Description>
+ * handle to a small bitmap descriptor. see the FTC_SBitRec
+ * structure for details..
+ */
typedef struct FTC_SBitRec_* FTC_SBit;
- /* handle to small bitmap cache */
+ /***********************************************************************
+ *
+ * <Type> FTC_SBit_Cache
+ *
+ * <Description>
+ * handle to a small bitmap cache. These are special cache objects
+ * used to store small glyph bitmaps (and anti-aliased pixmaps) in
+ * a much more efficient way than the traditional glyph image cache
+ * implemented by FTC_Image_Cache
+ */
typedef struct FTC_SBit_CacheRec_* FTC_SBit_Cache;
- /* a compact structure used to hold a single small bitmap */
+ /***********************************************************************
+ *
+ * <Struct> FTC_SBitRec
+ *
+ * <Description>
+ * a very compact structure used to describe a small glyph bitmap
+ *
+ * <Fields>
+ * width :: bitmap width in pixels
+ * height :: bitmap height in pixels
+ *
+ * left :: horizontal distance from pen position to left bitmap
+ * border (a.k.a. "left side bearing", or "lsb")
+ *
+ * top :: vertical distance from pen position (on the baseline)
+ * to the upper bitmap border (a.k.a. "top side bearing")
+ * the distance is positive for upwards Y coordinates.
+ *
+ * format :: format of glyph bitmap (mono or gray)
+ *
+ * pitch :: number of bytes per bitmap lines. may be positive or
+ * negative
+ *
+ * xadvance :: horizontal advance width in pixels
+ * yadvance :: vertical advance height in pixels
+ *
+ * buffer :: pointer to bitmap pixels
+ */
typedef struct FTC_SBitRec_
{
FT_Byte width;
@@ -53,14 +100,59 @@
} FTC_SBitRec;
+ /*************************************************************************
+ *
+ * <Section> FTC_SBit_Cache_New
+ *
+ * <Description>
+ * Create a new cache to store small glyph bitmaps
+ *
+ * <Input>
+ * manager :: handle to source cache manager
+ *
+ * <Output>
+ * acache :: handle to new sbit cache. NULL in case of error
+ *
+ * <Return>
+ * error code. 0 means success
+ */
FT_EXPORT( FT_Error ) FTC_SBit_Cache_New( FTC_Manager manager,
FTC_SBit_Cache *acache );
+ /*************************************************************************
+ *
+ * <Section> FTC_SBit_Cache_Lookup
+ *
+ * <Description>
+ * Lookup a given small glyph bitmap in a given sbit cache
+ *
+ * <Input>
+ * cache :: handle to source sbit cache
+ * desc :: pointer to glyph image descriptor
+ * gindex :: glyph index
+ *
+ * <Output>
+ * sbit :: handle to a small bitmap descriptor
+ *
+ * <Return>
+ * error code. 0 means success
+ *
+ * <Note>
+ * the small bitmap descriptor, and its bit buffer are owned by the
+ * cache and should never be freed by the application. They might
+ * as well disappear from memory on the next cache lookup, so don't
+ * treat them like persistent data..
+ *
+ * the descriptor's "buffer" field is set to 0 to indicate a missing
+ * glyph bitmap.
+ */
FT_EXPORT( FT_Error ) FTC_SBit_Cache_Lookup( FTC_SBit_Cache cache,
FTC_Image_Desc* desc,
FT_UInt gindex,
FTC_SBit *sbit );
+ /* */
+
FT_END_HEADER
#endif /* __FTCSBITS_H__ */
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index e6d55e4..17ec707 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -57,7 +57,7 @@
/*************************************************************************
*
- * <Section> Base_Interface
+ * <Section> base_interface
*
* <Title> Base Interface
*
diff --git a/include/freetype/ftbbox.h b/include/freetype/ftbbox.h
index 7cf149c..9d9252f 100644
--- a/include/freetype/ftbbox.h
+++ b/include/freetype/ftbbox.h
@@ -38,6 +38,10 @@
FT_BEGIN_HEADER
+ /********************************
+ * <Section> outline_processing
+ */
+
/*************************************************************************/
/* */
/* <Function> */
diff --git a/include/freetype/ftcache.h b/include/freetype/ftcache.h
index 0fcca41..81b8d49 100644
--- a/include/freetype/ftcache.h
+++ b/include/freetype/ftcache.h
@@ -50,6 +50,19 @@
#define FT_CACHE_INTERNAL_GLYPH_H FT2_PUBLIC_FILE(cache/ftcglyph.h)
#define FT_CACHE_INTERNAL_CHUNK_H FT2_PUBLIC_FILE(cache/ftcchunk.h)
+ /**************************************************************************
+ *
+ * <Section> cache_subsystem
+ *
+ * <Title> Cache Sub-System
+ *
+ * <Abstract>
+ * How to cache face, size and glyph data with FreeType 2
+ *
+ * <Description>
+ * This section details the FreeType 2 cache sub-system which is still
+ * in beta.
+ */
/*************************************************************************/
/*************************************************************************/
diff --git a/include/freetype/ftglyph.h b/include/freetype/ftglyph.h
index 6f2349e..7824b81 100644
--- a/include/freetype/ftglyph.h
+++ b/include/freetype/ftglyph.h
@@ -39,6 +39,20 @@
FT_BEGIN_HEADER
+ /*************************************************************************/
+ /* */
+ /* <Section> glyph_management */
+ /* */
+ /* <Title> Glyph Management */
+ /* */
+ /* <Abstract> */
+ /* Generic interface to manage individual glyph data */
+ /* */
+ /* <Description> */
+ /* This section contains definitions used to manage glyph data */
+ /* through generic FT_Glyph objects. Each one of them can contain */
+ /* a bitmap, a vector outline, or even images in other formats. */
+ /* */
/* forward declaration to a private type */
typedef struct FT_Glyph_Class_ FT_Glyph_Class;
@@ -218,17 +232,8 @@
FT_Matrix* matrix,
FT_Vector* delta );
-
- enum
- {
- ft_glyph_bbox_unscaled = 0, /* return unscaled font units */
- ft_glyph_bbox_subpixels = 0, /* return unfitted 26.6 coordinates */
- ft_glyph_bbox_gridfit = 1, /* return grid-fitted 26.6 coordinates */
- ft_glyph_bbox_truncate = 2, /* return coordinates in integer pixels */
- ft_glyph_bbox_pixels = 3 /* return grid-fitted pixel coordinates */
- };
-
-
+ /* */
+
/*************************************************************************/
/* */
/* <Function> */
@@ -291,6 +296,17 @@
/* */
/* The default value for `bbox_mode' is `ft_glyph_bbox_pixels'. */
/* */
+
+ enum
+ {
+ ft_glyph_bbox_unscaled = 0, /* return unscaled font units */
+ ft_glyph_bbox_subpixels = 0, /* return unfitted 26.6 coordinates */
+ ft_glyph_bbox_gridfit = 1, /* return grid-fitted 26.6 coordinates */
+ ft_glyph_bbox_truncate = 2, /* return coordinates in integer pixels */
+ ft_glyph_bbox_pixels = 3 /* return grid-fitted pixel coordinates */
+ };
+
+
FT_EXPORT( void ) FT_Glyph_Get_CBox( FT_Glyph glyph,
FT_UInt bbox_mode,
FT_BBox *acbox );
@@ -389,6 +405,9 @@
/* other helpful functions */
+ /*****
+ * <Section> base_interface
+ */
/*************************************************************************/
/* */
diff --git a/include/freetype/ftimage.h b/include/freetype/ftimage.h
index 3a8138f..19e2b9b 100644
--- a/include/freetype/ftimage.h
+++ b/include/freetype/ftimage.h
@@ -35,7 +35,7 @@
/***********************************************************************
*
- * <Section> Basic_Types
+ * <Section> basic_types
*
*/
diff --git a/include/freetype/ftmac.h b/include/freetype/ftmac.h
index a258a04..99654c7 100644
--- a/include/freetype/ftmac.h
+++ b/include/freetype/ftmac.h
@@ -34,6 +34,19 @@
FT_BEGIN_HEADER
+ /*******************************************************************
+ *
+ * <Section> Mac_Specific
+ *
+ * <Title> Mac-Specific Interface
+ *
+ * <Abstract>
+ * Only available on the Macintosh
+ *
+ * <Description>
+ * The following definitions are only available when FreeType
+ * is compiled on a Macintosh.
+ */
/*************************************************************************/
/* */
@@ -62,14 +75,18 @@
/* This function can be used to create FT_Face abjects from fonts */
/* that are installed in the system like so: */
/* */
+ /* { */
/* fond = GetResource( 'FOND', fontName ); */
/* error = FT_New_Face_From_FOND( library, fond, 0, &face ); */
/* */
+ /* } */
+ /* */
FT_EXPORT( FT_Error ) FT_New_Face_From_FOND( FT_Library library,
Handle fond,
FT_Long face_index,
FT_Face *aface );
+ /* */
FT_END_HEADER
diff --git a/include/freetype/ftmm.h b/include/freetype/ftmm.h
index 719fe65..bf4a1e6 100644
--- a/include/freetype/ftmm.h
+++ b/include/freetype/ftmm.h
@@ -26,6 +26,20 @@
FT_BEGIN_HEADER
+ /**********************************************************************
+ *
+ * <Section> Multiple_Masters
+ *
+ * <Title> Multiple Masters
+ *
+ * <Abstract>
+ * How to manage multiple masters fonts
+ *
+ * <Description>
+ * The following types and functions are used to manage multiple
+ * master fonts, i.e. choose specific design instances by setting
+ * design axis coordinates.
+ */
/*************************************************************************/
/* */
diff --git a/include/freetype/ftmodule.h b/include/freetype/ftmodule.h
index 06eca04..0416c64 100644
--- a/include/freetype/ftmodule.h
+++ b/include/freetype/ftmodule.h
@@ -26,6 +26,18 @@
FT_BEGIN_HEADER
+ /**************************************************************************
+ *
+ * <Section> Module_Management
+ *
+ * <Title> Module Management
+ *
+ * <Abstract> How to add, upgrade and remove modules from FreeType
+ *
+ * <Description>
+ * The definitions below are used to manage modules within FreeType.
+ * Modules can be added, upgraded and removed at runtime.
+ */
/* module bit flags */
typedef enum FT_Module_Flags_
diff --git a/include/freetype/ftnames.h b/include/freetype/ftnames.h
index 069ea3f..a824065 100644
--- a/include/freetype/ftnames.h
+++ b/include/freetype/ftnames.h
@@ -30,6 +30,25 @@
FT_BEGIN_HEADER
+ /**************************************************************************
+ *
+ * <Section> SFNT_Names
+ *
+ * <Title> SFNT Names
+ *
+ * <Abstract> Access the names embedded in TrueType and OpenType files
+ *
+ * <Description>
+ * The TrueType and OpenType specification allow the inclusion of
+ * a special "names table" in font files. This table contains textual
+ * (and internationalised) information regarding the font, like
+ * family name, copyright, version, etc..
+ *
+ * the definitions below are used to access them when available
+ *
+ * note that this has nothing to do with "glyph names" !!
+ */
+
/*************************************************************************/
/* */
/* <Struct> */
@@ -118,7 +137,7 @@
FT_EXPORT( FT_Error ) FT_Get_Sfnt_Name( FT_Face face,
FT_UInt index,
FT_SfntName *aname );
-
+ /* */
FT_END_HEADER
diff --git a/include/freetype/ftrender.h b/include/freetype/ftrender.h
index c807705..fa4d1f9 100644
--- a/include/freetype/ftrender.h
+++ b/include/freetype/ftrender.h
@@ -27,6 +27,9 @@
FT_BEGIN_HEADER
+ /****
+ * <Section> Module_Management
+ */
/* create a new glyph object */
typedef FT_Error (*FT_Glyph_Init_Func) ( FT_Glyph glyph,
diff --git a/include/freetype/fttypes.h b/include/freetype/fttypes.h
index 51c64ea..4f03c8b 100644
--- a/include/freetype/fttypes.h
+++ b/include/freetype/fttypes.h
@@ -31,7 +31,7 @@
/*************************************************************************/
/* */
- /* <Section> Basic_Types */
+ /* <Section> basic_types */
/* */
/* <Title> Basic Data Types */
/* */
diff --git a/include/freetype/t1tables.h b/include/freetype/t1tables.h
index 1091e88..696c4cb 100644
--- a/include/freetype/t1tables.h
+++ b/include/freetype/t1tables.h
@@ -28,6 +28,18 @@
FT_BEGIN_HEADER
+ /********************************************************************
+ *
+ * <Section> Type1_Tables
+ *
+ * <Title> Type 1 Tables
+ *
+ * <Abstract> Type 1 (Postscript) specific font tables
+ *
+ * <Description>
+ * This section ....
+ */
+
/* Note that we separate font data in T1_FontInfo and T1_Private */
/* structures in order to support Multiple Master fonts. */