ref: fd74ec68b44fe2346b89ccc485a1d451f26df9d6
parent: 94168f0b4184f08cd0f6f5661152de3895284bd9
author: Werner Lemberg <[email protected]>
date: Fri May 12 00:00:44 EDT 2006
* README: Minor updates. * include/freetype/*: s/scale/scaling value/ where appropriate. Many other minor documentation improvements. * src/tools/docmaker/sources.py (re_italic, re_bold): Handle trailing punctuation. * src/tools/docmaker/tohtml.py (HtmlFormatter::make_html_word): Add warning message for undefined cross references. Update handling of re_italic and re_bold.
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2006-05-11 Werner Lemberg <[email protected]>
+
+ * README: Minor updates.
+
+ * include/freetype/*: s/scale/scaling value/ where appropriate.
+ Many other minor documentation improvements.
+
+ * src/tools/docmaker/sources.py (re_italic, re_bold): Handle
+ trailing punctuation.
+ * src/tools/docmaker/tohtml.py (HtmlFormatter::make_html_word): Add
+ warning message for undefined cross references.
+ Update handling of re_italic and re_bold.
+
2006-05-11 Masatake YAMATO <[email protected]>
* builds/unix/ftsystem.c (FT_Stream_Open): Check errno only if
--- a/README
+++ b/README
@@ -17,8 +17,10 @@
Read the files `docs/INSTALL' for installation instructions.
- Note that the FreeType 2 documentation (together with signature
- files) is now available as a separate package from our sites. Go to
+ The FreeType 2 API reference is located in `docs/reference'; use the
+ file `ft2-doc.html' as the top entry point. Additional
+ documentation is available as a separate package from our sites. Go
+ to
http://download.savannah.gnu.org/releases/freetype/
--- a/include/freetype/config/ftoption.h
+++ b/include/freetype/config/ftoption.h
@@ -471,7 +471,7 @@
/* component offsets in composite glyphs. */
/* */
/* Apple and MS disagree on the default behavior of component offsets */
- /* in composites. Apple says that they should be scaled by the scale */
+ /* in composites. Apple says that they should be scaled by the scaling */
/* factors in the transformation matrix (roughly, it's more complex) */
/* while MS says they should not. OpenType defines two bits in the */
/* composite flags array which can be used to disambiguate, but old */
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -490,7 +490,7 @@
/* FT_ENC_TAG */
/* */
/* <Description> */
- /* This macro converts four letter tags into an unsigned long. It is */
+ /* This macro converts four-letter tags into an unsigned long. It is */
/* used to define `encoding' identifiers (see @FT_Encoding). */
/* */
/* <Note> */
@@ -498,7 +498,9 @@
/* should redefine this macro in case of problems to something like */
/* this: */
/* */
+ /* { *//* #define FT_ENC_TAG( value, a, b, c, d ) value */
+ /* } */
/* */
/* to get a simple enumeration without assigning special numbers. */
/* */
@@ -621,23 +623,24 @@
/* */
/* FT_ENCODING_NONE is set by the BDF and PCF drivers if the charmap */
/* is neither Unicode nor ISO-8859-1 (otherwise it is set to */
- /* FT_ENCODING_UNICODE). Use `FT_Get_BDF_Charset_ID' to find out */
- /* which encoding is really present. If, for example, the */
- /* `cs_registry' field is `KOI8' and the `cs_encoding' field is `R', */
- /* the font is encoded in KOI8-R. */
+ /* FT_ENCODING_UNICODE). Use @FT_Get_BDF_Charset_ID to find out which */
+ /* encoding is really present. If, for example, the `cs_registry' */
+ /* field is `KOI8' and the `cs_encoding' field is `R', the font is */
+ /* encoded in KOI8-R. */
/* */
/* FT_ENCODING_NONE is always set (with a single exception) by the */
- /* winfonts driver. Use `FT_Get_WinFNT_Header' and examine the */
- /* `charset' field of the `FT_WinFNT_HeaderRec' structure to find out */
- /* which encoding is really present. For example, FT_WinFNT_ID_CP1251 */
- /* (204) means Windows code page 1251 (for Russian). */
+ /* winfonts driver. Use @FT_Get_WinFNT_Header and examine the */
+ /* `charset' field of the @FT_WinFNT_HeaderRec structure to find out */
+ /* which encoding is really present. For example, */
+ /* @FT_WinFNT_ID_CP1251 (204) means Windows code page 1251 (for */
+ /* Russian). */
/* */
- /* FT_ENCODING_NONE is set if `platform_id' is `TT_PLATFORM_MACINTOSH' */
- /* and `encoding_id' is not `TT_MAC_ID_ROMAN' (otherwise it is set to */
+ /* FT_ENCODING_NONE is set if `platform_id' is @TT_PLATFORM_MACINTOSH */
+ /* and `encoding_id' is not @TT_MAC_ID_ROMAN (otherwise it is set to */
/* FT_ENCODING_APPLE_ROMAN). */
/* */
- /* If `platform_id' is `TT_PLATFORM_MACINTOSH', use the function */
- /* `FT_Get_CMap_Language_ID' to query the Mac language ID which may be */
+ /* If `platform_id' is @TT_PLATFORM_MACINTOSH, use the function c */
+ /* @FT_Get_CMap_Language_ID to query the Mac language ID which may be */
/* needed to be able to distinguish Apple encoding variants. See */
/* */
/* http://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/README.TXT */
@@ -645,9 +648,9 @@
/* to get an idea how to do that. Basically, if the language ID is 0, */
/* dont use it, otherwise subtract 1 from the language ID. Then */
/* examine `encoding_id'. If, for example, `encoding_id' is */
- /* `TT_MAC_ID_ROMAN' and the language ID (minus 1) is */
+ /* @TT_MAC_ID_ROMAN and the language ID (minus 1) is */
/* `TT_MAC_LANGID_GREEK', it is the Greek encoding, not Roman. */
- /* `TT_MAC_ID_ARABIC' with `TT_MAC_LANGID_FARSI' means the Farsi */
+ /* @TT_MAC_ID_ARABIC with `TT_MAC_LANGID_FARSI' means the Farsi */
/* variant the Arabic encoding. */
/* */
typedef enum FT_Encoding_
@@ -756,7 +759,7 @@
/* FT_Face_Internal */
/* */
/* <Description> */
- /* An opaque handle to an FT_Face_InternalRec structure, used to */
+ /* An opaque handle to an `FT_Face_InternalRec' structure, used to */
/* model private data of a given @FT_Face object. */
/* */
/* This structure might change between releases of FreeType 2 and is */
@@ -834,16 +837,17 @@
/* @FT_Generic type description. */
/* */
/* bbox :: The font bounding box. Coordinates are */
- /* expressed in font units (see units_per_EM). */
- /* The box is large enough to contain any */
- /* glyph from the font. Thus, bbox.yMax can */
- /* be seen as the `maximal ascender', and */
- /* bbox.yMin as the `minimal descender'. Only */
- /* relevant for scalable formats. */
+ /* expressed in font units (see */
+ /* `units_per_EM'). The box is large enough */
+ /* to contain any glyph from the font. Thus, */
+ /* `bbox.yMax' can be seen as the `maximal */
+ /* ascender', and `bbox.yMin' as the `minimal */
+ /* descender'. Only relevant for scalable */
+ /* formats. */
/* */
/* units_per_EM :: The number of font units per EM square for */
/* this face. This is typically 2048 for */
- /* TrueType fonts, and 1000 for Type1 fonts. */
+ /* TrueType fonts, and 1000 for Type 1 fonts. */
/* Only relevant for scalable formats. */
/* */
/* ascender :: The typographic ascender of the face, */
@@ -1240,14 +1244,15 @@
/* hence the term `ppem' (pixels per EM). It is also */
/* referred to as `nominal height'. */
/* */
- /* x_scale :: A 16.16 fractional scale used to convert */
+ /* x_scale :: A 16.16 fractional scaling value used to convert */
/* horizontal metrics from font units to 26.6 */
/* fractional pixels. Only relevant for scalable */
/* font formats. */
/* */
- /* y_scale :: A 16.16 fractional scale used to convert vertical */
- /* metrics from font units to 26.6 fractional pixels. */
- /* Only relevant for scalable font formats. */
+ /* y_scale :: A 16.16 fractional scaling value used to convert */
+ /* vertical metrics from font units to 26.6 */
+ /* fractional pixels. Only relevant for scalable */
+ /* font formats. */
/* */
/* ascender :: The ascender in 26.6 fractional pixels. See */
/* @FT_FaceRec for the details. */
@@ -1262,8 +1267,8 @@
/* pixels. See @FT_FaceRec for the details. */
/* */
/* <Note> */
- /* The scales, if relevant, are determined first during a size */
- /* changing operation. The remaining fields are then set by the */
+ /* The scaling values, if relevant, are determined first during a */
+ /* size changing operation. The remaining fields are then set by the */
/* driver. For scalable formats, they are usually set to scaled */
/* values of the corresponding fields in @FT_FaceRec. */
/* */
@@ -1280,8 +1285,8 @@
FT_UShort x_ppem; /* horizontal pixels per EM */
FT_UShort y_ppem; /* vertical pixels per EM */
- FT_Fixed x_scale; /* two scales used to convert font units */
- FT_Fixed y_scale; /* to 26.6 fractional pixels */
+ FT_Fixed x_scale; /* scaling values used to convert font */
+ FT_Fixed y_scale; /* units to 26.6 fractional pixels */
FT_Pos ascender; /* ascender in 26.6 frac. pixels */
FT_Pos descender; /* descender in 26.6 frac. pixels */
@@ -2006,28 +2011,29 @@
/* <Values> */
/* FT_SIZE_REQUEST_TYPE_NOMINAL :: */
/* The nominal size. The `units_per_EM' field of @FT_FaceRec is */
- /* used to determine both scales. */
+ /* used to determine both scaling values. */
/* */
/* FT_SIZE_REQUEST_TYPE_REAL_DIM :: */
/* The real dimension. The sum of the the `Ascender' and (minus */
/* of) the `Descender' fields of @FT_FaceRec are used to determine */
- /* both scales. */
+ /* both scaling values. */
/* */
/* FT_SIZE_REQUEST_TYPE_BBOX :: */
/* The font bounding box. The width and height of the `bbox' field */
/* of @FT_FaceRec are used to determine the horizontal and vertical */
- /* scales respectively. */
+ /* scaling value, respectively. */
/* */
/* FT_SIZE_REQUEST_TYPE_CELL :: */
/* The `max_advance_width' field of @FT_FaceRec is used to */
- /* determine the horizontal scale, and the vertical scale is */
- /* determined the same way as @FT_SIZE_REQUEST_TYPE_REAL_DIM does. */
- /* Finally, both scales are set to the smaller one. This type is */
- /* useful if you want to specify the font size for, say, a window */
- /* of a given dimension and 80x24 cells. */
+ /* determine the horizontal scaling value; the vertical scaling */
+ /* value is determined the same way as */
+ /* @FT_SIZE_REQUEST_TYPE_REAL_DIM does. Finally, both scaling */
+ /* values are set to the smaller one. This type is useful if you */
+ /* want to specify the font size for, say, a window of a given */
+ /* dimension and 80x24 cells. */
/* */
/* FT_SIZE_REQUEST_TYPE_SCALES :: */
- /* Specify the scales directly. */
+ /* Specify the scaling values directly. */
/* */
/* <Note> */
/* The above descriptions only apply to scalable formats. For bitmap */
@@ -2034,7 +2040,7 @@
/* formats, the behavior is up to the driver. */
/* */
/* See the note section of @FT_Size_Metrics if you wonder how size */
- /* requesting relates to scales. */
+ /* requesting relates to scaling values. */
/* */
typedef enum FT_Size_Request_Type_
{@@ -2073,8 +2079,8 @@
/* value. */
/* */
/* <Note> */
- /* If `width' is zero, then the horizontal scale is set equal to the */
- /* vertical scale, and vice versa. */
+ /* If `width' is zero, then the horizontal scaling value is set */
+ /* equal to the vertical scaling value, and vice versa. */
/* */
typedef struct FT_Size_RequestRec_
{@@ -2699,7 +2705,7 @@
/* right_glyph :: The index of the right glyph in the kern pair. */
/* */
/* kern_mode :: See @FT_Kerning_Mode for more information. */
- /* Determines the scale/dimension of the returned */
+ /* Determines the scale and dimension of the returned */
/* kerning vector. */
/* */
/* <Output> */
--- a/include/freetype/ftimage.h
+++ b/include/freetype/ftimage.h
@@ -144,15 +144,15 @@
/* */
/* FT_PIXEL_MODE_LCD :: */
/* An 8-bit bitmap, used to represent RGB or BGR decimated glyph */
- /* images used for display on LCD displays; the bitmap's width is */
- /* three times wider than the original glyph image. See also */
+ /* images used for display on LCD displays; the bitmap is three */
+ /* times wider than the original glyph image. See also */
/* @FT_RENDER_MODE_LCD. */
/* */
/* FT_PIXEL_MODE_LCD_V :: */
/* An 8-bit bitmap, used to represent RGB or BGR decimated glyph */
- /* images used for display on rotated LCD displays; the bitmap's */
- /* height is three times taller than the original glyph image. */
- /* See also @FT_RENDER_MODE_LCD_V. */
+ /* images used for display on rotated LCD displays; the bitmap */
+ /* is three times taller than the original glyph image. See also */
+ /* @FT_RENDER_MODE_LCD_V. */
/* */
typedef enum FT_Pixel_Mode_
{@@ -179,11 +179,11 @@
/* @FT_Pixel_Mode values instead. */
/* */
/* <Values> */
- /* ft_pixel_mode_none :: see @FT_PIXEL_MODE_NONE */
- /* ft_pixel_mode_mono :: see @FT_PIXEL_MODE_MONO */
- /* ft_pixel_mode_grays :: see @FT_PIXEL_MODE_GRAY */
- /* ft_pixel_mode_pal2 :: see @FT_PIXEL_MODE_GRAY2 */
- /* ft_pixel_mode_pal4 :: see @FT_PIXEL_MODE_GRAY4 */
+ /* ft_pixel_mode_none :: See @FT_PIXEL_MODE_NONE. */
+ /* ft_pixel_mode_mono :: See @FT_PIXEL_MODE_MONO. */
+ /* ft_pixel_mode_grays :: See @FT_PIXEL_MODE_GRAY. */
+ /* ft_pixel_mode_pal2 :: See @FT_PIXEL_MODE_GRAY2. */
+ /* ft_pixel_mode_pal4 :: See @FT_PIXEL_MODE_GRAY4. */
/* */
#define ft_pixel_mode_none FT_PIXEL_MODE_NONE
#define ft_pixel_mode_mono FT_PIXEL_MODE_MONO
@@ -203,8 +203,8 @@
/* <Description> */
/* THIS TYPE IS DEPRECATED. DO NOT USE IT! */
/* */
- /* An enumeration type used to describe the format of a bitmap */
- /* palette, used with ft_pixel_mode_pal4 and ft_pixel_mode_pal8. */
+ /* An enumeration type to describe the format of a bitmap palette, */
+ /* used with ft_pixel_mode_pal4 and ft_pixel_mode_pal8. */
/* */
/* <Fields> */
/* ft_palette_mode_rgb :: The palette is an array of 3-bytes RGB */
@@ -258,7 +258,7 @@
/* most cases. */
/* */
/* num_grays :: This field is only used with */
- /* `FT_PIXEL_MODE_GRAY'; it gives the number of gray */
+ /* @FT_PIXEL_MODE_GRAY; it gives the number of gray */
/* levels used in the bitmap. */
/* */
/* pixel_mode :: The pixel mode, i.e., how pixel bits are stored. */
@@ -644,7 +644,7 @@
/* FT_IMAGE_TAG */
/* */
/* <Description> */
- /* This macro converts four letter tags into an unsigned long. */
+ /* This macro converts four-letter tags to an unsigned long type. */
/* */
/* <Note> */
/* Since many 16bit compilers don't like 32bit enumerations, you */
@@ -651,7 +651,9 @@
/* should redefine this macro in case of problems to something like */
/* this: */
/* */
+ /* { *//* #define FT_IMAGE_TAG( value, _x1, _x2, _x3, _x4 ) value */
+ /* } */
/* */
/* to get a simple enumeration without assigning special numbers. */
/* */
@@ -677,7 +679,7 @@
/* */
/* <Values> */
/* FT_GLYPH_FORMAT_NONE :: */
- /* The value 0 is reserved and does describe a glyph format. */
+ /* The value 0 is reserved. */
/* */
/* FT_GLYPH_FORMAT_COMPOSITE :: */
/* The glyph image is a composite of several other images. This */
@@ -690,13 +692,13 @@
/* the @FT_GlyphSlotRec structure to read it. */
/* */
/* FT_GLYPH_FORMAT_OUTLINE :: */
- /* The glyph image is a vertorial outline made of line segments */
+ /* The glyph image is a vectorial outline made of line segments */
/* and Bezier arcs; it can be described as an @FT_Outline; you */
/* generally want to access the `outline' field of the */
/* @FT_GlyphSlotRec structure to read it. */
/* */
/* FT_GLYPH_FORMAT_PLOTTER :: */
- /* The glyph image is a vectorial path with no inside/outside */
+ /* The glyph image is a vectorial path with no inside and outside */
/* contours. Some Type 1 fonts, like those in the Hershey family, */
/* contain glyphs in this format. These are described as */
/* @FT_Outline, but FreeType isn't currently capable of rendering */
@@ -724,11 +726,11 @@
/* @FT_Glyph_Format values instead. */
/* */
/* <Values> */
- /* ft_glyph_format_none :: see @FT_GLYPH_FORMAT_NONE */
- /* ft_glyph_format_composite :: see @FT_GLYPH_FORMAT_COMPOSITE */
- /* ft_glyph_format_bitmap :: see @FT_GLYPH_FORMAT_BITMAP */
- /* ft_glyph_format_outline :: see @FT_GLYPH_FORMAT_OUTLINE */
- /* ft_glyph_format_plotter :: see @FT_GLYPH_FORMAT_PLOTTER */
+ /* ft_glyph_format_none :: See @FT_GLYPH_FORMAT_NONE. */
+ /* ft_glyph_format_composite :: See @FT_GLYPH_FORMAT_COMPOSITE. */
+ /* ft_glyph_format_bitmap :: See @FT_GLYPH_FORMAT_BITMAP. */
+ /* ft_glyph_format_outline :: See @FT_GLYPH_FORMAT_OUTLINE. */
+ /* ft_glyph_format_plotter :: See @FT_GLYPH_FORMAT_PLOTTER. */
/* */
#define ft_glyph_format_none FT_GLYPH_FORMAT_NONE
#define ft_glyph_format_composite FT_GLYPH_FORMAT_COMPOSITE
--- a/include/freetype/ftincrem.h
+++ b/include/freetype/ftincrem.h
@@ -40,7 +40,7 @@
* Incremental Loading
*
* @abstract:
- * Custom Glyph Loading
+ * Custom Glyph Loading.
*
* @description:
* This section contains various functions used to perform so-called
--- a/include/freetype/ftmodapi.h
+++ b/include/freetype/ftmodapi.h
@@ -316,7 +316,7 @@
* The TrueType Engine
*
* @abstract:
- * TrueType bytecode support
+ * TrueType bytecode support.
*
* @description:
* This section contains a function used to query the level of TrueType
--- a/include/freetype/fttypes.h
+++ b/include/freetype/fttypes.h
@@ -273,8 +273,8 @@
/* FT_Fixed */
/* */
/* <Description> */
- /* This type is used to store 16.16 fixed float values, like scales */
- /* or matrix coefficients. */
+ /* This type is used to store 16.16 fixed float values, like scaling */
+ /* values or matrix coefficients. */
/* */
typedef signed long FT_Fixed;
@@ -409,7 +409,7 @@
/* */
/* <Description> */
/* Describes a function used to destroy the `client' data of any */
- /* FreeType object. See the description of the FT_Generic type for */
+ /* FreeType object. See the description of the @FT_Generic type for */
/* details of usage. */
/* */
/* <Input> */
@@ -461,7 +461,7 @@
/* FT_MAKE_TAG */
/* */
/* <Description> */
- /* This macro converts four letter tags which are used to label */
+ /* This macro converts four-letter tags which are used to label */
/* TrueType tables into an unsigned long to be used within FreeType. */
/* */
/* <Note> */
--- a/include/freetype/internal/psaux.h
+++ b/include/freetype/internal/psaux.h
@@ -516,9 +516,10 @@
/* */
/* last :: The last point position. */
/* */
- /* scale_x :: The horizontal scale (FUnits to sub-pixels). */
+ /* scale_x :: The horizontal scaling value (FUnits to */
+ /* sub-pixels). */
/* */
- /* scale_y :: The vertical scale (FUnits to sub-pixels). */
+ /* scale_y :: The vertical scaling value (FUnits to sub-pixels). */
/* */
/* pos_x :: The horizontal translation (if composite glyph). */
/* */
--- a/src/tools/docmaker/sources.py
+++ b/src/tools/docmaker/sources.py
@@ -135,8 +135,8 @@
#
# used to detect italic and bold styles in paragraph text
#
-re_italic = re.compile( r"_(\w(\w|')*)_" ) # _italic_
-re_bold = re.compile( r"\*(\w(\w|')*)\*" ) # *bold*
+re_italic = re.compile( r"_(\w(\w|')*)_(.*)" ) # _italic_
+re_bold = re.compile( r"\*(\w(\w|')*)\*(.*)" ) # *bold*
#
# used to detect the end of commented source lines
--- a/src/tools/docmaker/tohtml.py
+++ b/src/tools/docmaker/tohtml.py
@@ -155,7 +155,7 @@
self.html_header = html_header_1 + project_title + html_header_2 + \
project_title + html_header_3
- self.html_footer = "<center><font size=""-2"">generated on " + \
+ self.html_footer = "<center><font size=""-2"">generated on " + \
time.asctime( time.localtime( time.time() ) ) + \
"</font></center>" + html_footer
@@ -189,11 +189,13 @@
try:
name = m.group(1)
rest = m.group(2)
- block = self.identifiers[ name ]
+ block = self.identifiers[name]
url = self.make_block_url( block )
return '<a href="' + url + '">' + name + '</a>' + rest
except:
# we detected a cross-reference to an unknown item
+ sys.stderr.write( \
+ "WARNING: undefined cross reference '" + name + "'.\n" )
return '?' + name + '?' + rest
# look for italics and bolds
@@ -200,12 +202,14 @@
m = re_italic.match( word )
if m:
name = m.group(1)
- return '<i>' + name + '</i>'
+ rest = m.group(3)
+ return '<i>' + name + '</i>' + rest
m = re_bold.match( word )
if m:
name = m.group(1)
- return '<b>' + name + '</b>'
+ rest = m.group(3)
+ return '<b>' + name + '</b>' + rest
return html_quote(word)
@@ -283,9 +287,9 @@
result = result + prefix + '<a href="' + \
self.make_block_url(block) + '">' + name + '</a>'
else:
- result = result + html_quote(line[ : length ])
+ result = result + html_quote(line[:length])
- line = line[ length : ]
+ line = line[length:]
else:
result = result + html_quote(line)
line = []
@@ -336,9 +340,9 @@
self.index_items = {}def index_name_enter( self, name ):
- block = self.identifiers[ name ]
+ block = self.identifiers[name]
url = self.make_block_url( block )
- self.index_items[ name ] = url
+ self.index_items[name] = url
def index_exit( self ):
@@ -352,8 +356,8 @@
for c in range(self.columns):
i = r + c*rows
if i < count:
- bname = self.block_index[ r + c*rows ]
- url = self.index_items[ bname ]
+ bname = self.block_index[r + c * rows]
+ url = self.index_items[bname]
line = line + '<td><a href="' + url + '">' + bname + '</a></td>'
else:
line = line + '<td></td>'