API documentation: Re-organize chapters and sections
* Split the very long 'Base Interface' section into smaller sections.
* Split the 'Core API' chapter into two chapters.
* Remove single enumeration values from `@order` fields since they have no
effect.
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index efff74f..4d3269f 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -102,61 +102,25 @@
*/
-
- /*************************************************************************/
- /*************************************************************************/
- /* */
- /* B A S I C T Y P E S */
- /* */
- /*************************************************************************/
- /*************************************************************************/
-
-
/**************************************************************************
*
* @section:
- * base_interface
+ * font_testing_macros
*
* @title:
- * Base Interface
+ * Font Testing Macros
*
* @abstract:
- * The FreeType~2 base font interface.
+ * Macros to test various properties of fonts.
*
* @description:
- * This section describes the most important public high-level API
- * functions of FreeType~2.
+ * Macros to test the most important font properties.
+ *
+ * It is recommended to use these high-level macros instead of directly
+ * testing the corresponding flags, which are scattered over various
+ * structures.
*
* @order:
- * FT_Library
- * FT_Face
- * FT_Size
- * FT_GlyphSlot
- * FT_CharMap
- * FT_Encoding
- * FT_ENC_TAG
- *
- * FT_FaceRec
- *
- * FT_FACE_FLAG_SCALABLE
- * FT_FACE_FLAG_FIXED_SIZES
- * FT_FACE_FLAG_FIXED_WIDTH
- * FT_FACE_FLAG_HORIZONTAL
- * FT_FACE_FLAG_VERTICAL
- * FT_FACE_FLAG_COLOR
- * FT_FACE_FLAG_SFNT
- * FT_FACE_FLAG_CID_KEYED
- * FT_FACE_FLAG_TRICKY
- * FT_FACE_FLAG_KERNING
- * FT_FACE_FLAG_MULTIPLE_MASTERS
- * FT_FACE_FLAG_VARIATION
- * FT_FACE_FLAG_GLYPH_NAMES
- * FT_FACE_FLAG_EXTERNAL_STREAM
- * FT_FACE_FLAG_HINTER
- * FT_FACE_FLAG_SVG
- * FT_FACE_FLAG_SBIX
- * FT_FACE_FLAG_SBIX_OVERLAY
- *
* FT_HAS_HORIZONTAL
* FT_HAS_VERTICAL
* FT_HAS_KERNING
@@ -176,21 +140,59 @@
* FT_IS_NAMED_INSTANCE
* FT_IS_VARIATION
*
- * FT_STYLE_FLAG_BOLD
- * FT_STYLE_FLAG_ITALIC
+ */
+
+
+ /**************************************************************************
*
- * FT_SizeRec
- * FT_Size_Metrics
+ * @section:
+ * library_setup
*
- * FT_GlyphSlotRec
- * FT_Glyph_Metrics
- * FT_SubGlyph
+ * @title:
+ * Library Setup
*
- * FT_Bitmap_Size
+ * @abstract:
+ * Functions to start and end the usage of the FreeType library.
*
+ * @description:
+ * Functions to start and end the usage of the FreeType library.
+ *
+ * Note that @FT_Library_Version and @FREETYPE_XXX are of limited use
+ * because even a new release of FreeType with only documentation
+ * changes increases the version number.
+ *
+ * @order:
+ * FT_Library
* FT_Init_FreeType
* FT_Done_FreeType
*
+ * FT_Library_Version
+ * FREETYPE_XXX
+ *
+ */
+
+
+ /**************************************************************************
+ *
+ * @section:
+ * face_creation
+ *
+ * @title:
+ * Face Creation
+ *
+ * @abstract:
+ * Functions to manage fonts.
+ *
+ * @description:
+ * The functions and structures collected in this section operate on
+ * fonts globally.
+ *
+ * @order:
+ * FT_Face
+ * FT_FaceRec
+ * FT_FACE_FLAG_XXX
+ * FT_STYLE_FLAG_XXX
+ *
* FT_New_Face
* FT_Done_Face
* FT_Reference_Face
@@ -198,10 +200,36 @@
* FT_Face_Properties
* FT_Open_Face
* FT_Open_Args
+ * FT_OPEN_XXX
* FT_Parameter
* FT_Attach_File
* FT_Attach_Stream
*
+ */
+
+
+ /**************************************************************************
+ *
+ * @section:
+ * sizing_and_scaling
+ *
+ * @title:
+ * Sizing and Scaling
+ *
+ * @abstract:
+ * Functions to manage font sizes.
+ *
+ * @description:
+ * The functions and structures collected in this section are related to
+ * selecting and manipulating the size of a font globally.
+ *
+ * @order:
+ * FT_Size
+ * FT_SizeRec
+ * FT_Size_Metrics
+ *
+ * FT_Bitmap_Size
+ *
* FT_Set_Char_Size
* FT_Set_Pixel_Sizes
* FT_Request_Size
@@ -209,44 +237,37 @@
* FT_Size_Request_Type
* FT_Size_RequestRec
* FT_Size_Request
+ *
* FT_Set_Transform
* FT_Get_Transform
+ *
+ */
+
+
+ /**************************************************************************
+ *
+ * @section:
+ * glyph_retrieval
+ *
+ * @title:
+ * Glyph Retrieval
+ *
+ * @abstract:
+ * Functions to manage glyphs.
+ *
+ * @description:
+ * The functions and structures collected in this section operate on
+ * single glyphs, of which @FT_Load_Glyph is most important.
+ *
+ * @order:
+ * FT_GlyphSlot
+ * FT_GlyphSlotRec
+ * FT_Glyph_Metrics
+ *
* FT_Load_Glyph
- * FT_Get_Char_Index
- * FT_Get_First_Char
- * FT_Get_Next_Char
- * FT_Load_Char
- *
- * FT_OPEN_MEMORY
- * FT_OPEN_STREAM
- * FT_OPEN_PATHNAME
- * FT_OPEN_DRIVER
- * FT_OPEN_PARAMS
- *
- * FT_LOAD_DEFAULT
- * FT_LOAD_RENDER
- * FT_LOAD_MONOCHROME
- * FT_LOAD_LINEAR_DESIGN
- * FT_LOAD_NO_SCALE
- * FT_LOAD_NO_HINTING
- * FT_LOAD_NO_BITMAP
- * FT_LOAD_SBITS_ONLY
- * FT_LOAD_NO_AUTOHINT
- * FT_LOAD_COLOR
- *
- * FT_LOAD_VERTICAL_LAYOUT
- * FT_LOAD_IGNORE_TRANSFORM
- * FT_LOAD_FORCE_AUTOHINT
- * FT_LOAD_NO_RECURSE
- * FT_LOAD_PEDANTIC
- *
- * FT_LOAD_TARGET_NORMAL
- * FT_LOAD_TARGET_LIGHT
- * FT_LOAD_TARGET_MONO
- * FT_LOAD_TARGET_LCD
- * FT_LOAD_TARGET_LCD_V
- *
+ * FT_LOAD_XXX
* FT_LOAD_TARGET_MODE
+ * FT_LOAD_TARGET_XXX
*
* FT_Render_Glyph
* FT_Render_Mode
@@ -254,34 +275,121 @@
* FT_Kerning_Mode
* FT_Get_Track_Kerning
*
+ */
+
+
+ /**************************************************************************
+ *
+ * @section:
+ * character_mapping
+ *
+ * @title:
+ * Character Mapping
+ *
+ * @abstract:
+ * Functions to manage character-to-glyph maps.
+ *
+ * @description:
+ * This section holds functions and structures that are related to
+ * mapping character input codes to glyph indices.
+ *
+ * Note that for many scripts the simplistic approach used by FreeType
+ * of mapping a single character to a single glyph is not valid or
+ * possible! In general, a higher-level library like HarfBuzz or ICU
+ * should be used for handling text strings.
+ *
+ * @order:
+ * FT_CharMap
* FT_CharMapRec
+ * FT_Encoding
+ * FT_ENC_TAG
+ *
* FT_Select_Charmap
* FT_Set_Charmap
* FT_Get_Charmap_Index
*
+ * FT_Get_Char_Index
+ * FT_Get_First_Char
+ * FT_Get_Next_Char
+ * FT_Load_Char
+ *
+ */
+
+
+ /**************************************************************************
+ *
+ * @section:
+ * information_retrieval
+ *
+ * @title:
+ * Information Retrieval
+ *
+ * @abstract:
+ * Functions to retrieve font and glyph information.
+ *
+ * @description:
+ * Functions to retrieve font and glyph information. Only some very
+ * basic data is covered; see also the chapter on the format-specific
+ * API for more.
+ *
+ *
+ * @order:
* FT_Get_Name_Index
* FT_Get_Glyph_Name
* FT_Get_Postscript_Name
* FT_Get_FSType_Flags
+ * FT_FSTYPE_XXX
* FT_Get_SubGlyph_Info
+ * FT_SUBGLYPH_FLAG_XXX
*
+ */
+
+
+ /**************************************************************************
+ *
+ * @section:
+ * other_api_data
+ *
+ * @title:
+ * Other API Data
+ *
+ * @abstract:
+ * Other structures, enumerations, and macros.
+ *
+ * @description:
+ * Other structures, enumerations, and macros. Deprecated functions are
+ * also listed here.
+ *
+ * @order:
* FT_Face_Internal
* FT_Size_Internal
* FT_Slot_Internal
*
- * FT_FACE_FLAG_XXX
- * FT_STYLE_FLAG_XXX
- * FT_OPEN_XXX
- * FT_LOAD_XXX
- * FT_LOAD_TARGET_XXX
- * FT_SUBGLYPH_FLAG_XXX
- * FT_FSTYPE_XXX
+ * FT_SubGlyph
*
* FT_HAS_FAST_GLYPHS
+ * FT_Face_CheckTrueTypePatents
+ * FT_Face_SetUnpatentedHinting
*
*/
+ /*************************************************************************/
+ /*************************************************************************/
+ /* */
+ /* B A S I C T Y P E S */
+ /* */
+ /*************************************************************************/
+ /*************************************************************************/
+
+
+ /**************************************************************************
+ *
+ * @section:
+ * glyph_retrieval
+ *
+ */
+
/**************************************************************************
*
* @struct:
@@ -351,6 +459,13 @@
/**************************************************************************
*
+ * @section:
+ * sizing_and_scaling
+ *
+ */
+
+ /**************************************************************************
+ *
* @struct:
* FT_Bitmap_Size
*
@@ -411,6 +526,13 @@
/**************************************************************************
*
+ * @section:
+ * library_setup
+ *
+ */
+
+ /**************************************************************************
+ *
* @type:
* FT_Library
*
@@ -483,7 +605,7 @@
/**************************************************************************
*
* @section:
- * base_interface
+ * face_creation
*
*/
@@ -521,6 +643,13 @@
/**************************************************************************
*
+ * @section:
+ * sizing_and_scaling
+ *
+ */
+
+ /**************************************************************************
+ *
* @type:
* FT_Size
*
@@ -553,6 +682,13 @@
/**************************************************************************
*
+ * @section:
+ * glyph_retrieval
+ *
+ */
+
+ /**************************************************************************
+ *
* @type:
* FT_GlyphSlot
*
@@ -572,6 +708,13 @@
/**************************************************************************
*
+ * @section:
+ * character_mapping
+ *
+ */
+
+ /**************************************************************************
+ *
* @type:
* FT_CharMap
*
@@ -879,6 +1022,13 @@
/**************************************************************************
*
+ * @section:
+ * other_api_data
+ *
+ */
+
+ /**************************************************************************
+ *
* @type:
* FT_Face_Internal
*
@@ -894,6 +1044,13 @@
/**************************************************************************
*
+ * @section:
+ * face_creation
+ *
+ */
+
+ /**************************************************************************
+ *
* @struct:
* FT_FaceRec
*
@@ -1274,6 +1431,13 @@
/**************************************************************************
*
+ * @section:
+ * font_testing_macros
+ *
+ */
+
+ /**************************************************************************
+ *
* @macro:
* FT_HAS_HORIZONTAL
*
@@ -1383,6 +1547,13 @@
/**************************************************************************
*
+ * @section:
+ * other_api_data
+ *
+ */
+
+ /**************************************************************************
+ *
* @macro:
* FT_HAS_FAST_GLYPHS
*
@@ -1395,6 +1566,13 @@
/**************************************************************************
*
+ * @section:
+ * font_testing_macros
+ *
+ */
+
+ /**************************************************************************
+ *
* @macro:
* FT_HAS_GLYPH_NAMES
*
@@ -1630,6 +1808,13 @@
/**************************************************************************
*
+ * @section:
+ * face_creation
+ *
+ */
+
+ /**************************************************************************
+ *
* @enum:
* FT_STYLE_FLAG_XXX
*
@@ -1656,6 +1841,13 @@
/**************************************************************************
*
+ * @section:
+ * other_api_data
+ *
+ */
+
+ /**************************************************************************
+ *
* @type:
* FT_Size_Internal
*
@@ -1668,6 +1860,13 @@
/**************************************************************************
*
+ * @section:
+ * sizing_and_scaling
+ *
+ */
+
+ /**************************************************************************
+ *
* @struct:
* FT_Size_Metrics
*
@@ -1819,6 +2018,13 @@
/**************************************************************************
*
+ * @section:
+ * other_api_data
+ *
+ */
+
+ /**************************************************************************
+ *
* @struct:
* FT_SubGlyph
*
@@ -1850,6 +2056,13 @@
/**************************************************************************
*
+ * @section:
+ * glyph_retrieval
+ *
+ */
+
+ /**************************************************************************
+ *
* @struct:
* FT_GlyphSlotRec
*
@@ -2094,6 +2307,13 @@
/**************************************************************************
*
+ * @section:
+ * library_setup
+ *
+ */
+
+ /**************************************************************************
+ *
* @function:
* FT_Init_FreeType
*
@@ -2151,6 +2371,13 @@
/**************************************************************************
*
+ * @section:
+ * face_creation
+ *
+ */
+
+ /**************************************************************************
+ *
* @enum:
* FT_OPEN_XXX
*
@@ -2652,6 +2879,13 @@
/**************************************************************************
*
+ * @section:
+ * sizing_and_scaling
+ *
+ */
+
+ /**************************************************************************
+ *
* @function:
* FT_Select_Size
*
@@ -2944,6 +3178,13 @@
/**************************************************************************
*
+ * @section:
+ * glyph_retrieval
+ *
+ */
+
+ /**************************************************************************
+ *
* @function:
* FT_Load_Glyph
*
@@ -2992,6 +3233,13 @@
/**************************************************************************
*
+ * @section:
+ * character_mapping
+ *
+ */
+
+ /**************************************************************************
+ *
* @function:
* FT_Load_Char
*
@@ -3035,6 +3283,13 @@
/**************************************************************************
*
+ * @section:
+ * glyph_retrieval
+ *
+ */
+
+ /**************************************************************************
+ *
* @enum:
* FT_LOAD_XXX
*
@@ -3374,6 +3629,13 @@
/**************************************************************************
*
+ * @section:
+ * sizing_and_scaling
+ *
+ */
+
+ /**************************************************************************
+ *
* @function:
* FT_Set_Transform
*
@@ -3449,6 +3711,13 @@
/**************************************************************************
*
+ * @section:
+ * glyph_retrieval
+ *
+ */
+
+ /**************************************************************************
+ *
* @enum:
* FT_Render_Mode
*
@@ -3843,6 +4112,13 @@
/**************************************************************************
*
+ * @section:
+ * character_mapping
+ *
+ */
+
+ /**************************************************************************
+ *
* @function:
* FT_Select_Charmap
*
@@ -4059,6 +4335,13 @@
/**************************************************************************
*
+ * @section:
+ * face_creation
+ *
+ */
+
+ /**************************************************************************
+ *
* @function:
* FT_Face_Properties
*
@@ -4157,6 +4440,13 @@
/**************************************************************************
*
+ * @section:
+ * information_retrieval
+ *
+ */
+
+ /**************************************************************************
+ *
* @function:
* FT_Get_Name_Index
*
@@ -4900,32 +5190,10 @@
/**************************************************************************
*
* @section:
- * version
- *
- * @title:
- * FreeType Version
- *
- * @abstract:
- * Functions and macros related to FreeType versions.
- *
- * @description:
- * Note that those functions and macros are of limited use because even a
- * new release of FreeType with only documentation changes increases the
- * version number.
- *
- * @order:
- * FT_Library_Version
- *
- * FREETYPE_MAJOR
- * FREETYPE_MINOR
- * FREETYPE_PATCH
- *
- * FT_Face_CheckTrueTypePatents
- * FT_Face_SetUnpatentedHinting
+ * library_setup
*
*/
-
/**************************************************************************
*
* @enum:
@@ -4994,6 +5262,13 @@
/**************************************************************************
*
+ * @section:
+ * other_api_data
+ *
+ */
+
+ /**************************************************************************
+ *
* @function:
* FT_Face_CheckTrueTypePatents
*
diff --git a/include/freetype/ftchapters.h b/include/freetype/ftchapters.h
index 6a9733a..7566fbd 100644
--- a/include/freetype/ftchapters.h
+++ b/include/freetype/ftchapters.h
@@ -31,9 +31,28 @@
* Core API
*
* @sections:
- * version
* basic_types
- * base_interface
+ * library_setup
+ * face_creation
+ * font_testing_macros
+ * sizing_and_scaling
+ * glyph_retrieval
+ * character_mapping
+ * information_retrieval
+ * other_api_data
+ *
+ */
+
+
+ /**************************************************************************
+ *
+ * @chapter:
+ * extended_api
+ *
+ * @title:
+ * Extended API
+ *
+ * @sections:
* glyph_variants
* color_management
* layer_management
