ref: 613ea866747502f26b7cb3ffba0a77b6893eaf74
parent: 7c25946f085d5aaec73aaf5dbeb1b9be6d8ecbff
author: Werner Lemberg <[email protected]>
date: Wed Oct 5 06:21:58 EDT 2005
Grammatical fixes (this is, removing future tense in most cases). Other minor documentation improvements.
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -419,7 +419,7 @@
/* */
/* <Note> */
/* Each face object owns one or more sizes. There is however a */
- /* single _active_ size for the face at any time that will be used by */
+ /* single _active_ size for the face at any time that is used by */
/* functions like @FT_Load_Glyph, @FT_Get_Kerning, etc. */
/* */
/* You can use the @FT_Activate_Size API to change the current */
@@ -616,8 +616,8 @@
/* <Note> */
/* By default, FreeType automatically synthetizes a Unicode charmap */
/* for Postscript fonts, using their glyph names dictionaries. */
- /* However, it will also report the encodings defined explicitly in */
- /* the font file, for the cases when they are needed, with the Adobe */
+ /* However, it also reports the encodings defined explicitly in the */
+ /* font file, for the cases when they are needed, with the Adobe */
/* values as well. */
/* */
/* FT_ENCODING_NONE is set by the BDF and PCF drivers if the charmap */
@@ -1038,8 +1038,9 @@
/* FT_FACE_FLAG_KERNING :: */
/* Indicates that the face contains kerning information. If set, */
/* the kerning distance can be retrieved through the function */
- /* @FT_Get_Kerning. Note that if unset, this function will always */
- /* return the vector (0,0). */
+ /* @FT_Get_Kerning. Otherwise the function always return the */
+ /* vector (0,0). Note that FreeType doesn't handle kerning data */
+ /* from the `GPOS' table (as present in some OpenType fonts). */
/* */
/* FT_FACE_FLAG_FAST_GLYPHS :: */
/* THIS FLAG IS DEPRECATED. DO NOT USE OR TEST IT. */
@@ -1485,9 +1486,9 @@
/* data. */
/* */
/* other :: Really wicked formats can use this pointer to */
- /* present their own glyph image to client apps. */
- /* Note that the app will need to know about the */
- /* image format. */
+ /* present their own glyph image to client */
+ /* applications. Note that the application */
+ /* needs to know about the image format. */
/* */
/* lsb_delta :: The difference between hinted and unhinted */
/* left side bearing while autohinting is */
@@ -1761,8 +1762,8 @@
/* */
/* driver :: This field is exclusively used by @FT_Open_Face; */
/* it simply specifies the font driver to use to open */
- /* the face. If set to 0, FreeType will try to load */
- /* the face with each one of the drivers in its list. */
+ /* the face. If set to 0, FreeType tries to load the */
+ /* face with each one of the drivers in its list. */
/* */
/* num_params :: The number of extra parameters. */
/* */
@@ -1782,12 +1783,11 @@
/* Otherwise, if the `FT_OPEN_PATHNAME' bit is set, assume that this */
/* is a normal file and use `pathname' to open it. */
/* */
- /* If the `FT_OPEN_DRIVER' bit is set, @FT_Open_Face will only try to */
+ /* If the `FT_OPEN_DRIVER' bit is set, @FT_Open_Face only tries to */
/* open the file with the driver whose handler is in `driver'. */
/* */
/* If the `FT_OPEN_PARAMS' bit is set, the parameters given by */
- /* `num_params' and `params' will be used. They are ignored */
- /* otherwise. */
+ /* `num_params' and `params' is used. They are ignored otherwise. */
/* */
typedef struct FT_Open_Args_
{@@ -1834,7 +1834,7 @@
/* */
/* @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'; the */
+ /* the function does _not_ return any face handle in `aface'; the */
/* return value is 0 if the font format is recognized, or non-zero */
/* otherwise. */
/* */
@@ -1886,7 +1886,7 @@
/* */
/* @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 */
+ /* negative, the function does _not_ return any face handle in */
/* `aface'; the return value is 0 if the font format is recognized, */
/* or non-zero otherwise. */
/* */
@@ -1906,7 +1906,7 @@
/* <Description> */
/* Opens a face object from a given resource and typeface index using */
/* an `FT_Open_Args' structure. If the face object doesn't exist, it */
- /* will be created. */
+ /* is created. */
/* */
/* <InOut> */
/* library :: A handle to the library resource. */
@@ -1931,7 +1931,7 @@
/* */
/* @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 */
+ /* negative, the function does _not_ return any face handle in */
/* `*aface'; the function's return value is 0 if the font format is */
/* recognized, or non-zero otherwise. */
/* */
@@ -2104,11 +2104,10 @@
/* */
/* The `character size' is really the size of an abstract square */
/* called the `EM', used to design the font. However, depending */
- /* on the font design, glyphs will be smaller or greater than the */
- /* EM. */
+ /* on the font design, glyphs is smaller or greater than the EM. */
/* */
/* This means that setting the pixel size to, say, 8x8 doesn't */
- /* guarantee in any way that you will get glyph bitmaps that all fit */
+ /* guarantee in any way that you get glyph bitmaps that all fit */
/* within an 8x8 cell (sometimes even far from it). */
/* */
/* For bitmap fonts, `pixel_height' usually is a reliable value for */
@@ -2136,7 +2135,7 @@
/* */
/* <InOut> */
/* face :: A handle to the target face object where the glyph */
- /* will be loaded. */
+ /* is loaded. */
/* */
/* <Input> */
/* glyph_index :: The index of the glyph in the font file. For */
@@ -2154,8 +2153,8 @@
/* */
/* <Note> */
/* If the glyph image is not a bitmap, and if the bit flag */
- /* FT_LOAD_IGNORE_TRANSFORM is unset, the glyph image will be */
- /* transformed with the information passed to a previous call to */
+ /* FT_LOAD_IGNORE_TRANSFORM is unset, the glyph image is transformed */
+ /* with the information passed to a previous call to */
/* @FT_Set_Transform. */
/* */
/* Note that this also transforms the `face.glyph.advance' field, but */
@@ -2178,7 +2177,7 @@
/* */
/* <InOut> */
/* face :: A handle to a target face object where the glyph */
- /* will be loaded. */
+ /* is loaded. */
/* */
/* <Input> */
/* char_code :: The glyph's character code, according to the */
@@ -2195,11 +2194,10 @@
/* */
/* <Note> */
/* If the face has no current charmap, or if the character code */
- /* is not defined in the charmap, this function will return an */
- /* error. */
+ /* is not defined in the charmap, this function returns an error. */
/* */
/* If the glyph image is not a bitmap, and if the bit flag */
- /* FT_LOAD_IGNORE_TRANSFORM is unset, the glyph image will be */
+ /* FT_LOAD_IGNORE_TRANSFORM is unset, the glyph image is */
/* transformed with the information passed to a previous call to */
/* @FT_Set_Transform. */
/* */
@@ -2224,7 +2222,7 @@
* @values:
* FT_LOAD_DEFAULT ::
* Corresponding to 0, this value is used a default glyph load. In this
- * case, the following will happen:
+ * case, the following happens:
*
* 1. FreeType looks for a bitmap for the glyph corresponding to the
* face's current size. If one is found, the function returns. The
@@ -2264,7 +2262,7 @@
*
* FT_LOAD_NO_BITMAP ::
* Don't look for bitmaps when loading the glyph. Only scalable
- * outlines will be loaded when available, and scaled, hinted, or
+ * outlines are loaded when available, and scaled, hinted, or
* rendered depending on other bit flags.
*
* This does not prevent you from rendering outlines to bitmaps
@@ -2272,9 +2270,9 @@
*
* FT_LOAD_VERTICAL_LAYOUT ::
* Prepare the glyph image for vertical text layout. This basically
- * means that `face.glyph.advance' will correspond to the vertical
+ * means that `face.glyph.advance' corresponds to the vertical
* advance height (instead of the default horizontal advance width),
- * and that the glyph image will be translated to match the vertical
+ * and that the glyph image is translated to match the vertical
* bearings positions.
*
* FT_LOAD_FORCE_AUTOHINT ::
@@ -2658,7 +2656,7 @@
/* buffer. */
/* */
/* <Output> */
- /* buffer :: A pointer to a target buffer where the name will be */
+ /* buffer :: A pointer to a target buffer where the name is */
/* copied to. */
/* */
/* <Return> */
@@ -2667,7 +2665,7 @@
/* <Note> */
/* An error is returned if the face doesn't provide glyph names or if */
/* the glyph index is invalid. In all cases of failure, the first */
- /* byte of `buffer' will be set to 0 to indicate an empty name. */
+ /* byte of `buffer' is set to 0 to indicate an empty name. */
/* */
/* The glyph name is truncated to fit within the buffer if it is too */
/* long. The returned string is always zero-terminated. */
@@ -2725,7 +2723,7 @@
/* FreeType error code. 0 means success. */
/* */
/* <Note> */
- /* This function will return an error if no charmap in the face */
+ /* This function returns an error if no charmap in the face */
/* corresponds to the encoding queried here. */
/* */
FT_EXPORT( FT_Error )
@@ -2752,7 +2750,7 @@
/* FreeType error code. 0 means success. */
/* */
/* <Note> */
- /* This function will return an error if the charmap is not part of */
+ /* This function returns an error if the charmap is not part of */
/* the face (i.e., if it is not listed in the face->charmaps[] */
/* table). */
/* */
@@ -2815,7 +2813,7 @@
/* */
/* <Description> */
/* This function is used to return the first character code in the */
- /* current charmap of a given face. It will also return the */
+ /* current charmap of a given face. It also returns the */
/* corresponding glyph index. */
/* */
/* <Input> */
@@ -2847,9 +2845,9 @@
/* } */
/* } */
/* */
- /* Note that `*agindex' will be set to 0 if the charmap is empty. */
- /* The result itself can be 0 in two cases: if the charmap is empty */
- /* or when the value 0 is the first valid character code. */
+ /* Note that `*agindex' is set to 0 if the charmap is empty. The */
+ /* result itself can be 0 in two cases: if the charmap is empty or */
+ /* when the value 0 is the first valid character code. */
/* */
FT_EXPORT( FT_ULong )
FT_Get_First_Char( FT_Face face,
@@ -2882,8 +2880,8 @@
/* through all character codes available in a given charmap. See */
/* the note for this function for a simple code example. */
/* */
- /* Note that `*agindex' will be set to 0 when there are no more codes */
- /* in the charmap. */
+ /* Note that `*agindex' is set to 0 when there are no more codes in */
+ /* the charmap. */
/* */
FT_EXPORT( FT_ULong )
FT_Get_Next_Char( FT_Face face,