Improve navigation in API reference.

* src/tools/docmaker/tohtml.py (html_header_3): Renamed to...
(html_header_6): This.
(html_header_3, html_header_3i, html_header_4, html_header_5,
html_header_5t): New strings.
(toc_footer_start, toc_footer_end): New strings.
(HtmlFormatter::html_header): Updated.
(HtmlFormatter::html_index_header, HtmlFormatter::html_toc_header):
New strings.
(HtmlFormatter::index_enter): Use `html_index_header'.
(HtmlFormatter::index_exit): Print `html_footer'.
(HtmlFormatter::toc_enter): Use `html_toc_header'.
(HtmlFormatter::toc_exit): Print proper footer.

Convert ~ to non-breakable space.

* src/tools/docmaker/tohtml.py (make_html_para): Implement it.
Update header files accordingly.

Many other minor documentation fixes.

1 files changed, 35 insertions, 35 deletions

diff --git a/include/freetype/ftcache.h b/include/freetype/ftcache.h
index 805df78dc..bb03b3117 100644
--- a/include/freetype/ftcache.h
+++ b/include/freetype/ftcache.h
@@ -36,10 +36,10 @@ FT_BEGIN_HEADER
    *    Cache Sub-System
    *
    * <Abstract>
-   *    How to cache face, size, and glyph data with FreeType 2.
+   *    How to cache face, size, and glyph data with FreeType~2.
    *
    * <Description>
-   *   This section describes the FreeType 2 cache sub-system, which is used
+   *   This section describes the FreeType~2 cache sub-system, which is used
    *   to limit the number of concurrently opened @FT_Face and @FT_Size
    *   objects, as well as caching information like character maps and glyph
    *   images while limiting their maximum memory usage.
@@ -193,7 +193,7 @@ FT_BEGIN_HEADER
    *     A new @FT_Face handle.
    *
    * <Return>
-   *   FreeType error code.  0 means success.
+   *   FreeType error code.  0~means success.
    *
    * <Note>
    *   The third parameter `req_data' is the same as the one passed by the
@@ -260,7 +260,7 @@ FT_BEGIN_HEADER
   /*                                                                       */
   /* <Description>                                                         */
   /*    An opaque handle to a cache node object.  Each cache node is       */
-  /*    reference-counted.  A node with a count of 0 might be flushed      */
+  /*    reference-counted.  A node with a count of~0 might be flushed      */
   /*    out of a full cache whenever a lookup request is performed.        */
   /*                                                                       */
   /*    If you lookup nodes, you have the ability to `acquire' them, i.e., */
@@ -279,19 +279,19 @@ FT_BEGIN_HEADER
   /*    FTC_Manager_New                                                    */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    Creates a new cache manager.                                       */
+  /*    Create a new cache manager.                                        */
   /*                                                                       */
   /* <Input>                                                               */
   /*    library   :: The parent FreeType library handle to use.            */
   /*                                                                       */
   /*    max_faces :: Maximum number of opened @FT_Face objects managed by  */
-  /*                 this cache instance.  Use 0 for defaults.             */
+  /*                 this cache instance.  Use~0 for defaults.             */
   /*                                                                       */
   /*    max_sizes :: Maximum number of opened @FT_Size objects managed by  */
-  /*                 this cache instance.  Use 0 for defaults.             */
+  /*                 this cache instance.  Use~0 for defaults.             */
   /*                                                                       */
   /*    max_bytes :: Maximum number of bytes to use for cached data nodes. */
-  /*                 Use 0 for defaults.  Note that this value does not    */
+  /*                 Use~0 for defaults.  Note that this value does not    */
   /*                 account for managed @FT_Face and @FT_Size objects.    */
   /*                                                                       */
   /*    requester :: An application-provided callback used to translate    */
@@ -301,11 +301,11 @@ FT_BEGIN_HEADER
   /*                 each time it is called (see @FTC_Face_Requester).     */
   /*                                                                       */
   /* <Output>                                                              */
-  /*    amanager  :: A handle to a new manager object.  0 in case of       */
+  /*    amanager  :: A handle to a new manager object.  0~in case of       */
   /*                 failure.                                              */
   /*                                                                       */
   /* <Return>                                                              */
-  /*    FreeType error code.  0 means success.                             */
+  /*    FreeType error code.  0~means success.                             */
   /*                                                                       */
   FT_EXPORT( FT_Error )
   FTC_Manager_New( FT_Library          library,
@@ -323,7 +323,7 @@ FT_BEGIN_HEADER
   /*    FTC_Manager_Reset                                                  */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    Empties a given cache manager.  This simply gets rid of all the    */
+  /*    Empty a given cache manager.  This simply gets rid of all the      */
   /*    currently cached @FT_Face and @FT_Size objects within the manager. */
   /*                                                                       */
   /* <InOut>                                                               */
@@ -339,7 +339,7 @@ FT_BEGIN_HEADER
   /*    FTC_Manager_Done                                                   */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    Destroys a given manager after emptying it.                        */
+  /*    Destroy a given manager after emptying it.                         */
   /*                                                                       */
   /* <Input>                                                               */
   /*    manager :: A handle to the target cache manager object.            */
@@ -354,7 +354,7 @@ FT_BEGIN_HEADER
   /*    FTC_Manager_LookupFace                                             */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    Retrieves the @FT_Face object that corresponds to a given face ID  */
+  /*    Retrieve the @FT_Face object that corresponds to a given face ID   */
   /*    through a cache manager.                                           */
   /*                                                                       */
   /* <Input>                                                               */
@@ -366,7 +366,7 @@ FT_BEGIN_HEADER
   /*    aface   :: A handle to the face object.                            */
   /*                                                                       */
   /* <Return>                                                              */
-  /*    FreeType error code.  0 means success.                             */
+  /*    FreeType error code.  0~means success.                             */
   /*                                                                       */
   /* <Note>                                                                */
   /*    The returned @FT_Face object is always owned by the manager.  You  */
@@ -415,10 +415,10 @@ FT_BEGIN_HEADER
   /*               interpreted as integer pixel character sizes.           */
   /*               Otherwise, they are expressed as 1/64th of points.      */
   /*                                                                       */
-  /*    x_res   :: Only used when `pixel' is value 0 to indicate the       */
+  /*    x_res   :: Only used when `pixel' is value~0 to indicate the       */
   /*               horizontal resolution in dpi.                           */
   /*                                                                       */
-  /*    y_res   :: Only used when `pixel' is value 0 to indicate the       */
+  /*    y_res   :: Only used when `pixel' is value~0 to indicate the       */
   /*               vertical resolution in dpi.                             */
   /*                                                                       */
   /* <Note>                                                                */
@@ -466,7 +466,7 @@ FT_BEGIN_HEADER
   /*    asize   :: A handle to the size object.                            */
   /*                                                                       */
   /* <Return>                                                              */
-  /*    FreeType error code.  0 means success.                             */
+  /*    FreeType error code.  0~means success.                             */
   /*                                                                       */
   /* <Note>                                                                */
   /*    The returned @FT_Size object is always owned by the manager.  You  */
@@ -580,7 +580,7 @@ FT_BEGIN_HEADER
    *     A new cache handle.  NULL in case of error.
    *
    * @return:
-   *   FreeType error code.  0 means success.
+   *   FreeType error code.  0~means success.
    *
    * @note:
    *   Like all other caches, this one will be destroyed with the cache
@@ -615,7 +615,7 @@ FT_BEGIN_HEADER
    *     The character code (in the corresponding charmap).
    *
    * @return:
-   *    Glyph index.  0 means `no glyph'.
+   *    Glyph index.  0~means `no glyph'.
    *
    */
   FT_EXPORT( FT_UInt )
@@ -721,7 +721,7 @@ FT_BEGIN_HEADER
   /*    FTC_ImageCache_New                                                 */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    Creates a new glyph image cache.                                   */
+  /*    Create a new glyph image cache.                                    */
   /*                                                                       */
   /* <Input>                                                               */
   /*    manager :: The parent manager for the image cache.                 */
@@ -730,7 +730,7 @@ FT_BEGIN_HEADER
   /*    acache  :: A handle to the new glyph image cache object.           */
   /*                                                                       */
   /* <Return>                                                              */
-  /*    FreeType error code.  0 means success.                             */
+  /*    FreeType error code.  0~means success.                             */
   /*                                                                       */
   FT_EXPORT( FT_Error )
   FTC_ImageCache_New( FTC_Manager      manager,
@@ -743,7 +743,7 @@ FT_BEGIN_HEADER
   /*    FTC_ImageCache_Lookup                                              */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    Retrieves a given glyph image from a glyph image cache.            */
+  /*    Retrieve a given glyph image from a glyph image cache.             */
   /*                                                                       */
   /* <Input>                                                               */
   /*    cache  :: A handle to the source glyph image cache.                */
@@ -753,7 +753,7 @@ FT_BEGIN_HEADER
   /*    gindex :: The glyph index to retrieve.                             */
   /*                                                                       */
   /* <Output>                                                              */
-  /*    aglyph :: The corresponding @FT_Glyph object.  0 in case of        */
+  /*    aglyph :: The corresponding @FT_Glyph object.  0~in case of        */
   /*              failure.                                                 */
   /*                                                                       */
   /*    anode  :: Used to return the address of of the corresponding cache */
@@ -761,7 +761,7 @@ FT_BEGIN_HEADER
   /*              below).                                                  */
   /*                                                                       */
   /* <Return>                                                              */
-  /*    FreeType error code.  0 means success.                             */
+  /*    FreeType error code.  0~means success.                             */
   /*                                                                       */
   /* <Note>                                                                */
   /*    The returned glyph is owned and managed by the glyph image cache.  */
@@ -806,7 +806,7 @@ FT_BEGIN_HEADER
   /*    gindex     :: The glyph index to retrieve.                         */
   /*                                                                       */
   /* <Output>                                                              */
-  /*    aglyph     :: The corresponding @FT_Glyph object.  0 in case of    */
+  /*    aglyph     :: The corresponding @FT_Glyph object.  0~in case of    */
   /*                  failure.                                             */
   /*                                                                       */
   /*    anode      :: Used to return the address of of the corresponding   */
@@ -814,7 +814,7 @@ FT_BEGIN_HEADER
   /*                  (see note below).                                    */
   /*                                                                       */
   /* <Return>                                                              */
-  /*    FreeType error code.  0 means success.                             */
+  /*    FreeType error code.  0~means success.                             */
   /*                                                                       */
   /* <Note>                                                                */
   /*    The returned glyph is owned and managed by the glyph image cache.  */
@@ -873,11 +873,11 @@ FT_BEGIN_HEADER
   /*    top       :: The vertical distance from the pen position (on the   */
   /*                 baseline) to the upper bitmap border (a.k.a. `top     */
   /*                 side bearing').  The distance is positive for upwards */
-  /*                 Y coordinates.                                        */
+  /*                 y~coordinates.                                        */
   /*                                                                       */
   /*    format    :: The format of the glyph bitmap (monochrome or gray).  */
   /*                                                                       */
-  /*    max_grays :: Maximum gray level value (in the range 1 to 255).     */
+  /*    max_grays :: Maximum gray level value (in the range 1 to~255).     */
   /*                                                                       */
   /*    pitch     :: The number of bytes per bitmap line.  May be positive */
   /*                 or negative.                                          */
@@ -926,7 +926,7 @@ FT_BEGIN_HEADER
   /*    FTC_SBitCache_New                                                  */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    Creates a new cache to store small glyph bitmaps.                  */
+  /*    Create a new cache to store small glyph bitmaps.                   */
   /*                                                                       */
   /* <Input>                                                               */
   /*    manager :: A handle to the source cache manager.                   */
@@ -935,7 +935,7 @@ FT_BEGIN_HEADER
   /*    acache  :: A handle to the new sbit cache.  NULL in case of error. */
   /*                                                                       */
   /* <Return>                                                              */
-  /*    FreeType error code.  0 means success.                             */
+  /*    FreeType error code.  0~means success.                             */
   /*                                                                       */
   FT_EXPORT( FT_Error )
   FTC_SBitCache_New( FTC_Manager     manager,
@@ -948,7 +948,7 @@ FT_BEGIN_HEADER
   /*    FTC_SBitCache_Lookup                                               */
   /*                                                                       */
   /* <Description>                                                         */
-  /*    Looks up a given small glyph bitmap in a given sbit cache and      */
+  /*    Look up a given small glyph bitmap in a given sbit cache and       */
   /*    `lock' it to prevent its flushing from the cache until needed.     */
   /*                                                                       */
   /* <Input>                                                               */
@@ -966,7 +966,7 @@ FT_BEGIN_HEADER
   /*              below).                                                  */
   /*                                                                       */
   /* <Return>                                                              */
-  /*    FreeType error code.  0 means success.                             */
+  /*    FreeType error code.  0~means success.                             */
   /*                                                                       */
   /* <Note>                                                                */
   /*    The small bitmap descriptor and its bit buffer are owned by the    */
@@ -974,7 +974,7 @@ FT_BEGIN_HEADER
   /*    as well disappear from memory on the next cache lookup, so don't   */
   /*    treat them as persistent data.                                     */
   /*                                                                       */
-  /*    The descriptor's `buffer' field is set to 0 to indicate a missing  */
+  /*    The descriptor's `buffer' field is set to~0 to indicate a missing  */
   /*    glyph bitmap.                                                      */
   /*                                                                       */
   /*    If `anode' is _not_ NULL, it receives the address of the cache     */
@@ -1021,7 +1021,7 @@ FT_BEGIN_HEADER
   /*                  (see note below).                                    */
   /*                                                                       */
   /* <Return>                                                              */
-  /*    FreeType error code.  0 means success.                             */
+  /*    FreeType error code.  0~means success.                             */
   /*                                                                       */
   /* <Note>                                                                */
   /*    The small bitmap descriptor and its bit buffer are owned by the    */
@@ -1029,7 +1029,7 @@ FT_BEGIN_HEADER
   /*    as well disappear from memory on the next cache lookup, so don't   */
   /*    treat them as persistent data.                                     */
   /*                                                                       */
-  /*    The descriptor's `buffer' field is set to 0 to indicate a missing  */
+  /*    The descriptor's `buffer' field is set to~0 to indicate a missing  */
   /*    glyph bitmap.                                                      */
   /*                                                                       */
   /*    If `anode' is _not_ NULL, it receives the address of the cache     */