diff --git a/ChangeLog b/ChangeLog index b6302b5b0..c56aa3c72 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,16 @@ +2006-05-11 Werner Lemberg + + * 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 * builds/unix/ftsystem.c (FT_Stream_Open): Check errno only if diff --git a/README b/README index 65164ea17..d38bce03c 100644 --- 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/ diff --git a/include/freetype/config/ftoption.h b/include/freetype/config/ftoption.h index e4a445ec4..62bcd505f 100644 --- a/include/freetype/config/ftoption.h +++ b/include/freetype/config/ftoption.h @@ -471,7 +471,7 @@ FT_BEGIN_HEADER /* 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 */ diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h index 76aebc42c..417a00c83 100644 --- a/include/freetype/freetype.h +++ b/include/freetype/freetype.h @@ -490,7 +490,7 @@ FT_BEGIN_HEADER /* FT_ENC_TAG */ /* */ /* */ - /* 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). */ /* */ /* */ @@ -498,7 +498,9 @@ FT_BEGIN_HEADER /* 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_BEGIN_HEADER /* */ /* 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 @@ FT_BEGIN_HEADER /* 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_BEGIN_HEADER /* FT_Face_Internal */ /* */ /* */ - /* 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_BEGIN_HEADER /* @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 @@ FT_BEGIN_HEADER /* 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 @@ FT_BEGIN_HEADER /* pixels. See @FT_FaceRec for the details. */ /* */ /* */ - /* 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_BEGIN_HEADER 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,35 +2011,36 @@ FT_BEGIN_HEADER /* */ /* 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. */ /* */ /* */ /* The above descriptions only apply to scalable formats. For bitmap */ /* 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 @@ FT_BEGIN_HEADER /* value. */ /* */ /* */ - /* 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 @@ FT_BEGIN_HEADER /* 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. */ /* */ /* */ diff --git a/include/freetype/ftimage.h b/include/freetype/ftimage.h index 2694f6f02..bbdfbadb6 100644 --- a/include/freetype/ftimage.h +++ b/include/freetype/ftimage.h @@ -144,15 +144,15 @@ FT_BEGIN_HEADER /* */ /* 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_BEGIN_HEADER /* @FT_Pixel_Mode values instead. */ /* */ /* */ - /* 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 @@ FT_BEGIN_HEADER /* */ /* 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. */ /* */ /* */ /* ft_palette_mode_rgb :: The palette is an array of 3-bytes RGB */ @@ -258,7 +258,7 @@ FT_BEGIN_HEADER /* 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,14 +644,16 @@ FT_BEGIN_HEADER /* FT_IMAGE_TAG */ /* */ /* */ - /* This macro converts four letter tags into an unsigned long. */ + /* This macro converts four-letter tags to an unsigned long type. */ /* */ /* */ /* Since many 16bit compilers don't like 32bit enumerations, you */ /* 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 @@ FT_BEGIN_HEADER /* */ /* */ /* 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 @@ FT_BEGIN_HEADER /* 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_BEGIN_HEADER /* @FT_Glyph_Format values instead. */ /* */ /* */ - /* 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 diff --git a/include/freetype/ftincrem.h b/include/freetype/ftincrem.h index 3db0f7954..f0859133b 100644 --- a/include/freetype/ftincrem.h +++ b/include/freetype/ftincrem.h @@ -40,7 +40,7 @@ FT_BEGIN_HEADER * Incremental Loading * * @abstract: - * Custom Glyph Loading + * Custom Glyph Loading. * * @description: * This section contains various functions used to perform so-called diff --git a/include/freetype/ftmodapi.h b/include/freetype/ftmodapi.h index 27dc26997..ab9082f8f 100644 --- a/include/freetype/ftmodapi.h +++ b/include/freetype/ftmodapi.h @@ -316,7 +316,7 @@ FT_BEGIN_HEADER * The TrueType Engine * * @abstract: - * TrueType bytecode support + * TrueType bytecode support. * * @description: * This section contains a function used to query the level of TrueType diff --git a/include/freetype/fttypes.h b/include/freetype/fttypes.h index fc65404bd..44a1cafa6 100644 --- a/include/freetype/fttypes.h +++ b/include/freetype/fttypes.h @@ -273,8 +273,8 @@ FT_BEGIN_HEADER /* FT_Fixed */ /* */ /* */ - /* 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 @@ FT_BEGIN_HEADER /* */ /* */ /* 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. */ /* */ /* */ @@ -461,7 +461,7 @@ FT_BEGIN_HEADER /* FT_MAKE_TAG */ /* */ /* */ - /* 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. */ /* */ /* */ diff --git a/include/freetype/internal/psaux.h b/include/freetype/internal/psaux.h index 6f8ba6cc8..d2e491000 100644 --- a/include/freetype/internal/psaux.h +++ b/include/freetype/internal/psaux.h @@ -516,9 +516,10 @@ FT_BEGIN_HEADER /* */ /* 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). */ /* */ diff --git a/src/tools/docmaker/sources.py b/src/tools/docmaker/sources.py index 923fa7b6e..264569e5b 100644 --- a/src/tools/docmaker/sources.py +++ b/src/tools/docmaker/sources.py @@ -135,8 +135,8 @@ re_crossref = re.compile( r'@(\w*)(.*)' ) # # 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 diff --git a/src/tools/docmaker/tohtml.py b/src/tools/docmaker/tohtml.py index 813092a4d..338dd256b 100644 --- a/src/tools/docmaker/tohtml.py +++ b/src/tools/docmaker/tohtml.py @@ -155,7 +155,7 @@ class HtmlFormatter(Formatter): self.html_header = html_header_1 + project_title + html_header_2 + \ project_title + html_header_3 - self.html_footer = "
generated on " + \ + self.html_footer = "
generated on " + \ time.asctime( time.localtime( time.time() ) ) + \ "
" + html_footer @@ -189,23 +189,27 @@ class HtmlFormatter(Formatter): try: name = m.group(1) rest = m.group(2) - block = self.identifiers[ name ] + block = self.identifiers[name] url = self.make_block_url( block ) return '' + name + '' + 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 m = re_italic.match( word ) if m: name = m.group(1) - return '' + name + '' + rest = m.group(3) + return '' + name + '' + rest m = re_bold.match( word ) if m: name = m.group(1) - return '' + name + '' + rest = m.group(3) + return '' + name + '' + rest return html_quote(word) @@ -283,9 +287,9 @@ class HtmlFormatter(Formatter): result = result + prefix + '' + name + '' 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 @@ class HtmlFormatter(Formatter): 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 @@ class HtmlFormatter(Formatter): 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 + '' + bname + '' else: line = line + ''