Commit e9d95aa06bfd96a6e182b1e9cc9f27e4a4ca09fc

Werner Lemberg 2013-12-11T07:48:51

[documentation] Add section how to include FreeType header files. Problem reported by David Kastrup <dak@gnu.org>. Surprisingly, a description how to do that was completely missing in the API reference. * include/freetype.h, include/ftchapters.h: New documentation section `header_inclusion'.

diff --git a/ChangeLog b/ChangeLog
index c79257f..a53d7dc 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2013-12-11  Werner Lemberg  <wl@gnu.org>
+
+	[documentation] Add section how to include FreeType header files.
+	Problem reported by David Kastrup <dak@gnu.org>.
+
+	Surprisingly, a description how to do that was completely missing in
+	the API reference.
+
+	* include/freetype.h, include/ftchapters.h: New documentation
+	section `header_inclusion'.
+
 2013-12-10  Werner Lemberg  <wl@gnu.org>
 
 	[autofit] s/DFLT/NONE/, s/dflt/none/.
diff --git a/include/freetype.h b/include/freetype.h
index 39a18af..372319a 100644
--- a/include/freetype.h
+++ b/include/freetype.h
@@ -42,6 +42,38 @@ FT_BEGIN_HEADER
   /*************************************************************************/
   /*                                                                       */
   /* <Section>                                                             */
+  /*    header_inclusion                                                   */
+  /*                                                                       */
+  /* <Title>                                                               */
+  /*    FreeType's header inclusion scheme                                 */
+  /*                                                                       */
+  /* <Abstract>                                                            */
+  /*    How client applications should include FreeType header files.      */
+  /*                                                                       */
+  /* <Description>                                                         */
+  /*    To be as flexible as possible (and for historical reasons),        */
+  /*    FreeType uses a very special inclusion scheme to load header       */
+  /*    files, for example                                                 */
+  /*                                                                       */
+  /*    {                                                                  */
+  /*      #include <ft2build.h>                                            */
+  /*                                                                       */
+  /*      #include FT_FREETYPE_H                                           */
+  /*      #include FT_OUTLINE_H                                            */
+  /*    }                                                                  */
+  /*                                                                       */
+  /*    A compiler and its preprocessor only needs an include path to find */
+  /*    the file `ft2build.h'; the exact locations and names of the other  */
+  /*    FreeType header files are hidden by preprocessor macro names,      */
+  /*    loaded by `ft2build.h'.  The API documentation always gives the    */
+  /*    header macro name needed for a particular function.                */
+  /*                                                                       */
+  /*************************************************************************/
+
+
+  /*************************************************************************/
+  /*                                                                       */
+  /* <Section>                                                             */
   /*    user_allocation                                                    */
   /*                                                                       */
   /* <Title>                                                               */
diff --git a/include/ftchapters.h b/include/ftchapters.h
index 4b1059a..d333761 100644
--- a/include/ftchapters.h
+++ b/include/ftchapters.h
@@ -15,6 +15,7 @@
 /*    General Remarks                                                      */
 /*                                                                         */
 /* <Sections>                                                              */
+/*    header_inclusion                                                     */
 /*    user_allocation                                                      */
 /*                                                                         */
 /***************************************************************************/