ftsnames.h, ttnameid.h, tttables.h: Revise documentation.

Show more macros in the reference: TT_MAC_LANGID_XXX, TT_MS_LANGID_XXX,
TT_NAME_ID_XXX, TT_UCR_XXX.

This commit is viewed best with

  git diff --color-words='[^*/ ]+'

1 files changed, 157 insertions, 167 deletions

diff --git a/include/freetype/tttables.h b/include/freetype/tttables.h
index 7a278e2b1..58312044c 100644
--- a/include/freetype/tttables.h
+++ b/include/freetype/tttables.h
@@ -45,8 +45,9 @@ FT_BEGIN_HEADER
   /*    TrueType specific table types and functions.                       */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    This section contains the definition of TrueType-specific tables   */
-  /*    as well as some routines used to access and process them.          */
+  /*    This section contains definitions of some basic tables specific to */
+  /*    TrueType and OpenType as well as some routines used to access and  */
+  /*    process them.                                                      */
   /*                                                                       */
   /* <Order>                                                               */
   /*    TT_Header                                                          */
@@ -76,8 +77,8 @@ FT_BEGIN_HEADER
   /*    TT_Header                                                          */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    A structure used to model a TrueType font header table.  All       */
-  /*    fields follow the TrueType specification.                          */
+  /*    A structure to model a TrueType font header table.  All fields     */
+  /*    follow the OpenType specification.                                 */
   /*                                                                       */
   typedef struct  TT_Header_
   {
@@ -114,9 +115,9 @@ FT_BEGIN_HEADER
   /*    TT_HoriHeader                                                      */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    A structure used to model a TrueType horizontal header, the `hhea' */
+  /*    A structure to model a TrueType horizontal header, the `hhea'      */
   /*    table, as well as the corresponding horizontal metrics table,      */
-  /*    i.e., the `hmtx' table.                                            */
+  /*    `hmtx'.                                                            */
   /*                                                                       */
   /* <Fields>                                                              */
   /*    Version                :: The table version.                       */
@@ -131,7 +132,7 @@ FT_BEGIN_HEADER
   /*                              glyphs found in the font (maybe ASCII).  */
   /*                                                                       */
   /*                              You should use the `sTypoAscender' field */
-  /*                              of the OS/2 table instead if you want    */
+  /*                              of the `OS/2' table instead if you want  */
   /*                              the correct one.                         */
   /*                                                                       */
   /*    Descender              :: The font's descender, i.e., the distance */
@@ -145,7 +146,7 @@ FT_BEGIN_HEADER
   /*                              glyphs found in the font (maybe ASCII).  */
   /*                                                                       */
   /*                              You should use the `sTypoDescender'      */
-  /*                              field of the OS/2 table instead if you   */
+  /*                              field of the `OS/2' table instead if you */
   /*                              want the correct one.                    */
   /*                                                                       */
   /*    Line_Gap               :: The font's line gap, i.e., the distance  */
@@ -195,14 +196,6 @@ FT_BEGIN_HEADER
   /*    friends) if the font contains an `MVAR' table: `caret_Slope_Rise', */
   /*    `caret_Slope_Run', and `caret_Offset'.                             */
   /*                                                                       */
-  /*    IMPORTANT: The TT_HoriHeader and TT_VertHeader structures should   */
-  /*               be identical except for the names of their fields,      */
-  /*               which are different.                                    */
-  /*                                                                       */
-  /*               This ensures that a single function in the `ttload'     */
-  /*               module is able to read both the horizontal and vertical */
-  /*               headers.                                                */
-  /*                                                                       */
   typedef struct  TT_HoriHeader_
   {
     FT_Fixed   Version;
@@ -224,7 +217,7 @@ FT_BEGIN_HEADER
     FT_Short   metric_Data_Format;
     FT_UShort  number_Of_HMetrics;
 
-    /* The following fields are not defined by the TrueType specification */
+    /* The following fields are not defined by the OpenType specification */
     /* but they are used to connect the metrics header to the relevant    */
     /* `hmtx' table.                                                      */
 
@@ -241,8 +234,8 @@ FT_BEGIN_HEADER
   /*                                                                       */
   /* <Description>                                                         */
   /*    A structure used to model a TrueType vertical header, the `vhea'   */
-  /*    table, as well as the corresponding vertical metrics table, i.e.,  */
-  /*    the `vmtx' table.                                                  */
+  /*    table, as well as the corresponding vertical metrics table,        */
+  /*    `vmtx'.                                                            */
   /*                                                                       */
   /* <Fields>                                                              */
   /*    Version                 :: The table version.                      */
@@ -258,8 +251,8 @@ FT_BEGIN_HEADER
   /*                               ASCII).                                 */
   /*                                                                       */
   /*                               You should use the `sTypoAscender'      */
-  /*                               field of the OS/2 table instead if you  */
-  /*                               want the correct one.                   */
+  /*                               field of the `OS/2' table instead if    */
+  /*                               you want the correct one.               */
   /*                                                                       */
   /*    Descender               :: The font's descender, i.e., the         */
   /*                               distance from the baseline to the       */
@@ -273,8 +266,8 @@ FT_BEGIN_HEADER
   /*                               ASCII).                                 */
   /*                                                                       */
   /*                               You should use the `sTypoDescender'     */
-  /*                               field of the OS/2 table instead if you  */
-  /*                               want the correct one.                   */
+  /*                               field of the `OS/2' table instead if    */
+  /*                               you want the correct one.               */
   /*                                                                       */
   /*    Line_Gap                :: The font's line gap, i.e., the distance */
   /*                               to add to the ascender and descender to */
@@ -309,7 +302,7 @@ FT_BEGIN_HEADER
   /*                                                                       */
   /*    metric_Data_Format      :: Always~0.                               */
   /*                                                                       */
-  /*    number_Of_HMetrics      :: Number of VMetrics entries in the       */
+  /*    number_Of_VMetrics      :: Number of VMetrics entries in the       */
   /*                               `vmtx' table -- this value can be       */
   /*                               smaller than the total number of glyphs */
   /*                               in the font.                            */
@@ -325,14 +318,6 @@ FT_BEGIN_HEADER
   /*    `Descender', `Line_Gap', `caret_Slope_Rise', `caret_Slope_Run',    */
   /*    and `caret_Offset'.                                                */
   /*                                                                       */
-  /*    IMPORTANT: The TT_HoriHeader and TT_VertHeader structures should   */
-  /*               be identical except for the names of their fields,      */
-  /*               which are different.                                    */
-  /*                                                                       */
-  /*               This ensures that a single function in the `ttload'     */
-  /*               module is able to read both the horizontal and vertical */
-  /*               headers.                                                */
-  /*                                                                       */
   typedef struct  TT_VertHeader_
   {
     FT_Fixed   Version;
@@ -342,9 +327,9 @@ FT_BEGIN_HEADER
 
     FT_UShort  advance_Height_Max;      /* advance height maximum */
 
-    FT_Short   min_Top_Side_Bearing;    /* minimum left-sb or top-sb       */
-    FT_Short   min_Bottom_Side_Bearing; /* minimum right-sb or bottom-sb   */
-    FT_Short   yMax_Extent;             /* xmax or ymax extents            */
+    FT_Short   min_Top_Side_Bearing;    /* minimum top-sb          */
+    FT_Short   min_Bottom_Side_Bearing; /* minimum bottom-sb       */
+    FT_Short   yMax_Extent;             /* ymax extents            */
     FT_Short   caret_Slope_Rise;
     FT_Short   caret_Slope_Run;
     FT_Short   caret_Offset;
@@ -354,9 +339,9 @@ FT_BEGIN_HEADER
     FT_Short   metric_Data_Format;
     FT_UShort  number_Of_VMetrics;
 
-    /* The following fields are not defined by the TrueType specification */
+    /* The following fields are not defined by the OpenType specification */
     /* but they are used to connect the metrics header to the relevant    */
-    /* `hmtx' or `vmtx' table.                                            */
+    /* `vmtx' table.                                                      */
 
     void*      long_metrics;
     void*      short_metrics;
@@ -370,12 +355,14 @@ FT_BEGIN_HEADER
   /*    TT_OS2                                                             */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    A structure used to model a TrueType `OS/2' table.  All fields     */
-  /*    comply to the OpenType specification.                              */
+  /*    A structure to model a TrueType `OS/2' table.  All fields comply   */
+  /*    to the OpenType specification.                                     */
   /*                                                                       */
-  /*    Note that we now support old Mac fonts that do not include an OS/2 */
-  /*    table.  In this case, the `version' field is always set to 0xFFFF. */
+  /*    Note that we now support old Mac fonts that do not include an      */
+  /*    `OS/2' table.  In this case, the `version' field is always set to  */
+  /*    0xFFFF.                                                            */
   /*                                                                       */
+  /* <Note>                                                                */
   /*    For an OpenType variation font, the values of the following fields */
   /*    can change after a call to @FT_Set_Var_Design_Coordinates (and     */
   /*    friends) if the font contains an `MVAR' table: `sCapHeight',       */
@@ -385,6 +372,10 @@ FT_BEGIN_HEADER
   /*    `ySubscriptYOffset', `ySubscriptYSize', `ySuperscriptXOffset',     */
   /*    `ySuperscriptXSize', `ySuperscriptYOffset', and                    */
   /*    `ySuperscriptYSize'.                                               */
+  /*                                                                       */
+  /*    Possible values for bits in the `ulUnicodeRangeX' fields are given */
+  /*    by the @TT_UCR_XXX macros.                                         */
+  /*                                                                       */
 
   typedef struct  TT_OS2_
   {
@@ -450,10 +441,10 @@ FT_BEGIN_HEADER
   /*    TT_Postscript                                                      */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    A structure used to model a TrueType `post' table.  All fields     */
-  /*    comply to the TrueType specification.  This structure does not     */
-  /*    reference the PostScript glyph names, which can be nevertheless    */
-  /*    accessed with the `ttpost' module.                                 */
+  /*    A structure to model a TrueType `post' table.  All fields comply   */
+  /*    to the OpenType specification.  This structure does not reference  */
+  /*    a font's PostScript glyph names; use @FT_Get_Glyph_Name to         */
+  /*    retrieve them.                                                     */
   /*                                                                       */
   /* <Note>                                                                */
   /*    For an OpenType variation font, the values of the following fields */
@@ -473,8 +464,8 @@ FT_BEGIN_HEADER
     FT_ULong  minMemType1;
     FT_ULong  maxMemType1;
 
-    /* Glyph names follow in the file, but we don't   */
-    /* load them by default.  See file `ttpost.c'.    */
+    /* Glyph names follow in the `post' table, but we don't */
+    /* load them by default.                                */
 
   } TT_Postscript;
 
@@ -485,8 +476,8 @@ FT_BEGIN_HEADER
   /*    TT_PCLT                                                            */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    A structure used to model a TrueType `PCLT' table.  All fields     */
-  /*    comply to the TrueType specification.                              */
+  /*    A structure to model a TrueType `PCLT' table.  All fields comply   */
+  /*    to the OpenType specification.                                     */
   /*                                                                       */
   typedef struct  TT_PCLT_
   {
@@ -516,8 +507,8 @@ FT_BEGIN_HEADER
   /*                                                                       */
   /* <Description>                                                         */
   /*    The maximum profile (`maxp') table contains many max values, which */
-  /*    can be used to pre-allocate arrays.  This ensures that no memory   */
-  /*    allocation occurs during a glyph load.                             */
+  /*    can be used to pre-allocate arrays for speeding up glyph loading   */
+  /*    and hinting.                                                       */
   /*                                                                       */
   /* <Fields>                                                              */
   /*    version               :: The version number.                       */
@@ -527,21 +518,19 @@ FT_BEGIN_HEADER
   /*                                                                       */
   /*    maxPoints             :: The maximum number of points in a         */
   /*                             non-composite TrueType glyph.  See also   */
-  /*                             the structure element                     */
   /*                             `maxCompositePoints'.                     */
   /*                                                                       */
   /*    maxContours           :: The maximum number of contours in a       */
   /*                             non-composite TrueType glyph.  See also   */
-  /*                             the structure element                     */
   /*                             `maxCompositeContours'.                   */
   /*                                                                       */
   /*    maxCompositePoints    :: The maximum number of points in a         */
-  /*                             composite TrueType glyph.  See also the   */
-  /*                             structure element `maxPoints'.            */
+  /*                             composite TrueType glyph.  See also       */
+  /*                             `maxPoints'.                              */
   /*                                                                       */
   /*    maxCompositeContours  :: The maximum number of contours in a       */
-  /*                             composite TrueType glyph.  See also the   */
-  /*                             structure element `maxContours'.          */
+  /*                             composite TrueType glyph.  See also       */
+  /*                             `maxContours'.                            */
   /*                                                                       */
   /*    maxZones              :: The maximum number of zones used for      */
   /*                             glyph hinting.                            */
@@ -602,8 +591,9 @@ FT_BEGIN_HEADER
   /*    FT_Sfnt_Tag                                                        */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    An enumeration used to specify the index of an SFNT table.         */
-  /*    Used in the @FT_Get_Sfnt_Table API function.                       */
+  /*    An enumeration to specify indices of SFNT tables loaded and parsed */
+  /*    by FreeType during initialization of an SFNT font.  Used in the    */
+  /*    @FT_Get_Sfnt_Table API function.                                   */
   /*                                                                       */
   /* <Values>                                                              */
   /*    FT_SFNT_HEAD :: To access the font's @TT_Header structure.         */
@@ -651,7 +641,7 @@ FT_BEGIN_HEADER
   /*    FT_Get_Sfnt_Table                                                  */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    Return a pointer to a given SFNT table within a face.              */
+  /*    Return a pointer to a given SFNT table stored within a face.       */
   /*                                                                       */
   /* <Input>                                                               */
   /*    face :: A handle to the source.                                    */
@@ -659,7 +649,7 @@ FT_BEGIN_HEADER
   /*    tag  :: The index of the SFNT table.                               */
   /*                                                                       */
   /* <Return>                                                              */
-  /*    A type-less pointer to the table.  This will be~0 in case of       */
+  /*    A type-less pointer to the table.  This will be NULL in case of    */
   /*    error, or if the corresponding table was not found *OR* loaded     */
   /*    from the file.                                                     */
   /*                                                                       */
@@ -688,70 +678,70 @@ FT_BEGIN_HEADER
                      FT_Sfnt_Tag  tag );
 
 
- /**************************************************************************
-  *
-  * @function:
-  *   FT_Load_Sfnt_Table
-  *
-  * @description:
-  *   Load any font table into client memory.
-  *
-  * @input:
-  *   face ::
-  *     A handle to the source face.
-  *
-  *   tag ::
-  *     The four-byte tag of the table to load.  Use the value~0 if you want
-  *     to access the whole font file.  Otherwise, you can use one of the
-  *     definitions found in the @FT_TRUETYPE_TAGS_H file, or forge a new
-  *     one with @FT_MAKE_TAG.
-  *
-  *   offset ::
-  *     The starting offset in the table (or file if tag == 0).
-  *
-  * @output:
-  *   buffer ::
-  *     The target buffer address.  The client must ensure that the memory
-  *     array is big enough to hold the data.
-  *
-  * @inout:
-  *   length ::
-  *     If the `length' parameter is NULL, then try to load the whole table.
-  *     Return an error code if it fails.
-  *
-  *     Else, if `*length' is~0, exit immediately while returning the
-  *     table's (or file) full size in it.
-  *
-  *     Else the number of bytes to read from the table or file, from the
-  *     starting offset.
-  *
-  * @return:
-  *   FreeType error code.  0~means success.
-  *
-  * @note:
-  *   If you need to determine the table's length you should first call this
-  *   function with `*length' set to~0, as in the following example:
-  *
-  *     {
-  *       FT_ULong  length = 0;
-  *
-  *
-  *       error = FT_Load_Sfnt_Table( face, tag, 0, NULL, &length );
-  *       if ( error ) { ... table does not exist ... }
-  *
-  *       buffer = malloc( length );
-  *       if ( buffer == NULL ) { ... not enough memory ... }
-  *
-  *       error = FT_Load_Sfnt_Table( face, tag, 0, buffer, &length );
-  *       if ( error ) { ... could not load table ... }
-  *     }
-  *
-  *   Note that structures like @TT_Header or @TT_OS2 can't be used with
-  *   this function; they are limited to @FT_Get_Sfnt_Table.  Reason is that
-  *   those structures depend on the processor architecture, with varying
-  *   size (e.g. 32bit vs. 64bit) or order (big endian vs. little endian).
-  *
-  */
+  /**************************************************************************
+   *
+   * @function:
+   *   FT_Load_Sfnt_Table
+   *
+   * @description:
+   *   Load any SFNT font table into client memory.
+   *
+   * @input:
+   *   face ::
+   *     A handle to the source face.
+   *
+   *   tag ::
+   *     The four-byte tag of the table to load.  Use value~0 if you want
+   *     to access the whole font file.  Otherwise, you can use one of the
+   *     definitions found in the @FT_TRUETYPE_TAGS_H file, or forge a new
+   *     one with @FT_MAKE_TAG.
+   *
+   *   offset ::
+   *     The starting offset in the table (or file if tag~==~0).
+   *
+   * @output:
+   *   buffer ::
+   *     The target buffer address.  The client must ensure that the memory
+   *     array is big enough to hold the data.
+   *
+   * @inout:
+   *   length ::
+   *     If the `length' parameter is NULL, try to load the whole table.
+   *     Return an error code if it fails.
+   *
+   *     Else, if `*length' is~0, exit immediately while returning the
+   *     table's (or file) full size in it.
+   *
+   *     Else the number of bytes to read from the table or file, from the
+   *     starting offset.
+   *
+   * @return:
+   *   FreeType error code.  0~means success.
+   *
+   * @note:
+   *   If you need to determine the table's length you should first call this
+   *   function with `*length' set to~0, as in the following example:
+   *
+   *     {
+   *       FT_ULong  length = 0;
+   *
+   *
+   *       error = FT_Load_Sfnt_Table( face, tag, 0, NULL, &length );
+   *       if ( error ) { ... table does not exist ... }
+   *
+   *       buffer = malloc( length );
+   *       if ( buffer == NULL ) { ... not enough memory ... }
+   *
+   *       error = FT_Load_Sfnt_Table( face, tag, 0, buffer, &length );
+   *       if ( error ) { ... could not load table ... }
+   *     }
+   *
+   *   Note that structures like @TT_Header or @TT_OS2 can't be used with
+   *   this function; they are limited to @FT_Get_Sfnt_Table.  Reason is that
+   *   those structures depend on the processor architecture, with varying
+   *   size (e.g. 32bit vs. 64bit) or order (big endian vs. little endian).
+   *
+   */
   FT_EXPORT( FT_Error )
   FT_Load_Sfnt_Table( FT_Face    face,
                       FT_ULong   tag,
@@ -760,41 +750,41 @@ FT_BEGIN_HEADER
                       FT_ULong*  length );
 
 
- /**************************************************************************
-  *
-  * @function:
-  *   FT_Sfnt_Table_Info
-  *
-  * @description:
-  *   Return information on an SFNT table.
-  *
-  * @input:
-  *   face ::
-  *     A handle to the source face.
-  *
-  *   table_index ::
-  *     The index of an SFNT table.  The function returns
-  *     FT_Err_Table_Missing for an invalid value.
-  *
-  * @inout:
-  *   tag ::
-  *     The name tag of the SFNT table.  If the value is NULL, `table_index'
-  *     is ignored, and `length' returns the number of SFNT tables in the
-  *     font.
-  *
-  * @output:
-  *   length ::
-  *     The length of the SFNT table (or the number of SFNT tables, depending
-  *     on `tag').
-  *
-  * @return:
-  *   FreeType error code.  0~means success.
-  *
-  * @note:
-  *   While parsing fonts, FreeType handles SFNT tables with length zero as
-  *   missing.
-  *
-  */
+  /**************************************************************************
+   *
+   * @function:
+   *   FT_Sfnt_Table_Info
+   *
+   * @description:
+   *   Return information on an SFNT table.
+   *
+   * @input:
+   *   face ::
+   *     A handle to the source face.
+   *
+   *   table_index ::
+   *     The index of an SFNT table.  The function returns
+   *     FT_Err_Table_Missing for an invalid value.
+   *
+   * @inout:
+   *   tag ::
+   *     The name tag of the SFNT table.  If the value is NULL, `table_index'
+   *     is ignored, and `length' returns the number of SFNT tables in the
+   *     font.
+   *
+   * @output:
+   *   length ::
+   *     The length of the SFNT table (or the number of SFNT tables, depending
+   *     on `tag').
+   *
+   * @return:
+   *   FreeType error code.  0~means success.
+   *
+   * @note:
+   *   While parsing fonts, FreeType handles SFNT tables with length zero as
+   *   missing.
+   *
+   */
   FT_EXPORT( FT_Error )
   FT_Sfnt_Table_Info( FT_Face    face,
                       FT_UInt    table_index,
@@ -808,16 +798,16 @@ FT_BEGIN_HEADER
   /*    FT_Get_CMap_Language_ID                                            */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    Return TrueType/sfnt specific cmap language ID.  Definitions of    */
-  /*    language ID values are in `ttnameid.h'.                            */
+  /*    Return cmap language ID as specified in the OpenType standard.     */
+  /*    Definitions of language ID values are in file @FT_TRUETYPE_IDS_H.  */
   /*                                                                       */
   /* <Input>                                                               */
   /*    charmap ::                                                         */
   /*      The target charmap.                                              */
   /*                                                                       */
   /* <Return>                                                              */
-  /*    The language ID of `charmap'.  If `charmap' doesn't belong to a    */
-  /*    TrueType/sfnt face, just return~0 as the default value.            */
+  /*    The language ID of `charmap'.  If `charmap' doesn't belong to an   */
+  /*    SFNT face, just return~0 as the default value.                     */
   /*                                                                       */
   /*    For a format~14 cmap (to access Unicode IVS), the return value is  */
   /*    0xFFFFFFFF.                                                        */
@@ -832,15 +822,15 @@ FT_BEGIN_HEADER
   /*    FT_Get_CMap_Format                                                 */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    Return TrueType/sfnt specific cmap format.                         */
+  /*    Return the format of an SFNT `cmap' table.                         */
   /*                                                                       */
   /* <Input>                                                               */
   /*    charmap ::                                                         */
   /*      The target charmap.                                              */
   /*                                                                       */
   /* <Return>                                                              */
-  /*    The format of `charmap'.  If `charmap' doesn't belong to a         */
-  /*    TrueType/sfnt face, return -1.                                     */
+  /*    The format of `charmap'.  If `charmap' doesn't belong to an SFNT   */
+  /*    face, return -1.                                                   */
   /*                                                                       */
   FT_EXPORT( FT_Long )
   FT_Get_CMap_Format( FT_CharMap  charmap );