diff --git a/ChangeLog b/ChangeLog
index af8a078e4..0270d98ad 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2017-12-07  Werner Lemberg  <wl@gnu.org>
+
+	* include/freetype/config/ftheader.h: Some clean-up.
+
+	This commit removes documentation of deprecated macros and does some
+	minor streamlining.
+
 2017-12-06  Werner Lemberg  <wl@gnu.org>
 
 	* builds/symbian/bld.inf: Updated.
diff --git a/include/freetype/config/ftheader.h b/include/freetype/config/ftheader.h
index 2c2258f1e..acf6b744d 100644
--- a/include/freetype/config/ftheader.h
+++ b/include/freetype/config/ftheader.h
@@ -567,63 +567,6 @@
 #define FT_CACHE_H  <freetype/ftcache.h>
 
 
-  /*************************************************************************
-   *
-   * @macro:
-   *   FT_CACHE_IMAGE_H
-   *
-   * @description:
-   *   A macro used in #include statements to name the file containing the
-   *   `glyph image' API of the FreeType~2 cache sub-system.
-   *
-   *   It is used to define a cache for @FT_Glyph elements.  You can also
-   *   use the API defined in @FT_CACHE_SMALL_BITMAPS_H if you only need to
-   *   store small glyph bitmaps, as it will use less memory.
-   *
-   *   This macro is deprecated.  Simply include @FT_CACHE_H to have all
-   *   glyph image-related cache declarations.
-   *
-   */
-#define FT_CACHE_IMAGE_H  FT_CACHE_H
-
-
-  /*************************************************************************
-   *
-   * @macro:
-   *   FT_CACHE_SMALL_BITMAPS_H
-   *
-   * @description:
-   *   A macro used in #include statements to name the file containing the
-   *   `small bitmaps' API of the FreeType~2 cache sub-system.
-   *
-   *   It is used to define a cache for small glyph bitmaps in a relatively
-   *   memory-efficient way.  You can also use the API defined in
-   *   @FT_CACHE_IMAGE_H if you want to cache arbitrary glyph images,
-   *   including scalable outlines.
-   *
-   *   This macro is deprecated.  Simply include @FT_CACHE_H to have all
-   *   small bitmaps-related cache declarations.
-   *
-   */
-#define FT_CACHE_SMALL_BITMAPS_H  FT_CACHE_H
-
-
-  /*************************************************************************
-   *
-   * @macro:
-   *   FT_CACHE_CHARMAP_H
-   *
-   * @description:
-   *   A macro used in #include statements to name the file containing the
-   *   `charmap' API of the FreeType~2 cache sub-system.
-   *
-   *   This macro is deprecated.  Simply include @FT_CACHE_H to have all
-   *   charmap-based cache declarations.
-   *
-   */
-#define FT_CACHE_CHARMAP_H  FT_CACHE_H
-
-
   /*************************************************************************
    *
    * @macro:
@@ -773,17 +716,6 @@
 #define FT_LCD_FILTER_H  <freetype/ftlcdfil.h>
 
 
-  /*************************************************************************
-   *
-   * @macro:
-   *   FT_UNPATENTED_HINTING_H
-   *
-   * @description:
-   *   Deprecated.
-   */
-#define FT_UNPATENTED_HINTING_H  <freetype/ftparams.h>
-
-
   /*************************************************************************
    *
    * @macro:
@@ -822,26 +754,30 @@
 
   /* */
 
+  /* These header files don't need to be included by the user. */
 #define FT_ERROR_DEFINITIONS_H  <freetype/fterrdef.h>
 #define FT_PARAMETER_TAGS_H     <freetype/ftparams.h>
 
+  /* Deprecated macros. */
+#define FT_UNPATENTED_HINTING_H   <freetype/ftparams.h>
+#define FT_TRUETYPE_UNPATENTED_H  <freetype/ftparams.h>
+
+  /* FT_CACHE_H is the only header file needed for the cache subsystem. */
+#define FT_CACHE_IMAGE_H          FT_CACHE_H
+#define FT_CACHE_SMALL_BITMAPS_H  FT_CACHE_H
+#define FT_CACHE_CHARMAP_H        FT_CACHE_H
 
   /* The internals of the cache sub-system are no longer exposed.  We */
   /* default to FT_CACHE_H at the moment just in case, but we know of */
   /* no rogue client that uses them.                                  */
   /*                                                                  */
-#define FT_CACHE_MANAGER_H           <freetype/ftcache.h>
-#define FT_CACHE_INTERNAL_MRU_H      <freetype/ftcache.h>
-#define FT_CACHE_INTERNAL_MANAGER_H  <freetype/ftcache.h>
-#define FT_CACHE_INTERNAL_CACHE_H    <freetype/ftcache.h>
-#define FT_CACHE_INTERNAL_GLYPH_H    <freetype/ftcache.h>
-#define FT_CACHE_INTERNAL_IMAGE_H    <freetype/ftcache.h>
-#define FT_CACHE_INTERNAL_SBITS_H    <freetype/ftcache.h>
-
-
-#define FT_INCREMENTAL_H          <freetype/ftincrem.h>
-
-#define FT_TRUETYPE_UNPATENTED_H  <freetype/ftparams.h>
+#define FT_CACHE_MANAGER_H           FT_CACHE_H
+#define FT_CACHE_INTERNAL_MRU_H      FT_CACHE_H
+#define FT_CACHE_INTERNAL_MANAGER_H  FT_CACHE_H
+#define FT_CACHE_INTERNAL_CACHE_H    FT_CACHE_H
+#define FT_CACHE_INTERNAL_GLYPH_H    FT_CACHE_H
+#define FT_CACHE_INTERNAL_IMAGE_H    FT_CACHE_H
+#define FT_CACHE_INTERNAL_SBITS_H    FT_CACHE_H
 
 
   /*