* builds/freetype.mk (DOC_DIR): New variable.

(refdoc): Use *_DIR variables.
(distclean): Remove documentation files.

* builds/detect.mk (std_setup, dos_setup): Mention `make refdoc'.

* configure: Set DOC_DIR variable.

* builds/freetype.mk (refdoc): New target to build the
documentation.
(.PHONY): Updated.

* include/freetype/freetype.h: Improve documentation of FT_CharMap.
* include/freetype/ftimage,h: Fix documentation of FT_OUTLINE_FLAGS.
* include/freetype/tttables.h: Document FT_Sfnt_Tag.

8 files changed, 70 insertions, 16 deletions

diff --git a/ChangeLog b/ChangeLog
index b4c1c16f0..56e393a8d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,23 @@
+2003-07-07  Werner Lemberg  <wl@gnu.org>
+
+	* builds/freetype.mk (DOC_DIR): New variable.
+	(refdoc): Use *_DIR variables.
+	(distclean): Remove documentation files.
+
+	* builds/detect.mk (std_setup, dos_setup): Mention `make refdoc'.
+
+	* configure: Set DOC_DIR variable.
+
+2003-07-07  Patrik Hägglund  <patrik.hagglund@bredband.net>
+
+	* builds/freetype.mk (refdoc): New target to build the
+	documentation.
+	(.PHONY): Updated.
+
+	* include/freetype/freetype.h: Improve documentation of FT_CharMap.
+	* include/freetype/ftimage,h: Fix documentation of FT_OUTLINE_FLAGS.
+	* include/freetype/tttables.h: Document FT_Sfnt_Tag.
+
 2003-07-06  Werner Lemberg  <wl@gnu.org>
 
 	* src/bdf/bdfdrivr.c (BDF_Face_Init), src/pcf/pcfread.c
diff --git a/builds/detect.mk b/builds/detect.mk
index 13525c47d..eeb1300bc 100644
--- a/builds/detect.mk
+++ b/builds/detect.mk
@@ -128,7 +128,8 @@ std_setup:
 	@echo "If this does not correspond to your system or settings please remove the file"
 	@echo "\`$(CONFIG_MK)' from this directory then read the INSTALL file for help."
 	@echo ""
-	@echo "Otherwise, simply type \`$(MAKE)' again to build the library."
+	@echo "Otherwise, simply type \`$(MAKE)' again to build the library,"
+	@echo "or \`$(MAKE) refdoc' to build the API reference (the latter needs python)."
 	@echo ""
 	@$(COPY) $(CONFIG_RULES) $(CONFIG_MK)
 
@@ -150,6 +151,7 @@ dos_setup:
 	@echo '$(CONFIG_MK)' from this directory then read the INSTALL file for help.
 	@type builds\newline
 	@echo Otherwise, simply type 'make' again to build the library.
+	@echo or 'make refdoc' to build the API reference (the latter needs python).
 	@type builds\newline
 	@$(COPY) $(subst /,\,$(CONFIG_RULES) $(CONFIG_MK)) > nul
 
diff --git a/builds/freetype.mk b/builds/freetype.mk
index 6948ab82d..991e3c220 100644
--- a/builds/freetype.mk
+++ b/builds/freetype.mk
@@ -27,6 +27,8 @@
 #
 #   LIB_DIR        The directory in which the library is created.
 #
+#   DOC_DIR        The directory in which the API reference is created.
+#
 #   INCLUDES       A list of directories to be included additionally.
 #                  Usually empty.
 #
@@ -71,7 +73,7 @@
 # The targets `objects' and `library' are defined at the end of this
 # Makefile after all other rules have been included.
 #
-.PHONY: single multi objects library
+.PHONY: single multi objects library refdoc
 
 # default target -- build single objects and library
 #
@@ -98,6 +100,11 @@ INTERNAL_DIR := $(PUBLIC_DIR)/internal
 CONFIG_DIR   := $(PUBLIC_DIR)/config
 CACHE_DIR    := $(PUBLIC_DIR)/cache
 
+# The documentation directory.
+#
+ifndef DOC_DIR
+  DOC_DIR := $(TOP_DIR)/docs/reference
+endif
 
 # The final name of the library file.
 #
@@ -242,6 +249,16 @@ library: $(PROJECT_LIBRARY)
 	$(FT_COMPILE) $T$(subst /,$(COMPILER_SEP),$@ $<)
 
 
+refdoc:
+	python $(SRC_DIR)/tools/docmaker/docmaker.py \
+               --prefix=ft2                          \
+               --title=FreeType-2.x.x                \
+               --output=$(DOC_DIR)                   \
+               $(PUBLIC_DIR)/*.h                     \
+               $(PUBLIC_DIR)/config/*.h              \
+               $(PUBLIC_DIR)/cache/*.h
+
+
 .PHONY: clean_project_std distclean_project_std
 
 # Standard cleaning and distclean rules.  These are not accepted
@@ -287,6 +304,7 @@ remove_config_mk:
 #
 clean: clean_project
 distclean: distclean_project remove_config_mk
+	-$(DELETE) $(subst /,$(SEP),$(DOC_DIR)/*.html $(NO_OUTPUT))
 
 
 # EOF
diff --git a/configure b/configure
index 1198380df..c8a56577d 100644
--- a/configure
+++ b/configure
@@ -46,11 +46,13 @@ abs_ft2_dir=`cd "$ft2_dir" && pwd`
 # build a dummy Makefile if we are not building in the source tree
 
 if test "$abs_curr_dir" != "$abs_ft2_dir"; then
-  echo "OBJ_DIR=$abs_curr_dir"          > Makefile
-  echo "TOP_DIR=$abs_ft2_dir"          >> Makefile
-  echo "OBJ_BUILD=$abs_curr_dir"       >> Makefile
-  echo "LIBTOOL=$abs_curr_dir/libtool" >> Makefile
-  echo "include $abs_ft2_dir/Makefile" >> Makefile
+  mkdir reference
+  echo "TOP_DIR=$abs_ft2_dir"             > Makefile
+  echo "OBJ_DIR=$abs_curr_dir"           >> Makefile
+  echo "OBJ_BUILD=$abs_curr_dir"         >> Makefile
+  echo "DOC_DIR=$abs_curr_dir/reference" >> Makefile
+  echo "LIBTOOL=$abs_curr_dir/libtool"   >> Makefile
+  echo "include $abs_ft2_dir/Makefile"   >> Makefile
 fi
 
 # call make
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index f69475584..6c17c7154 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -433,6 +433,10 @@ FT_BEGIN_HEADER
   /*    @FT_Open_Face), the library looks for a Unicode charmap within     */
   /*    the list and automatically activates it.                           */
   /*                                                                       */
+  /* <Also>                                                                */
+  /*    The @FT_CharMapRec details the publicly accessible fields of a     */
+  /*    given character map.                                               */
+  /*                                                                       */
   typedef struct FT_CharMapRec_*  FT_CharMap;
 
 
diff --git a/include/freetype/ftimage.h b/include/freetype/ftimage.h
index b2a0a6871..e2e8025b7 100644
--- a/include/freetype/ftimage.h
+++ b/include/freetype/ftimage.h
@@ -358,11 +358,11 @@ FT_BEGIN_HEADER
   /*************************************************************************/
   /*                                                                       */
   /* <Enum>                                                                */
-  /*   FT_OUTLINE_XXX                                                      */
+  /*   FT_OUTLINE_FLAGS                                                    */
   /*                                                                       */
   /* <Description>                                                         */
   /*    A list of bit-field constants use for the flags in an outline's    */
-  /*    `outline_flags' field.                                             */
+  /*    `flags' field.                                                     */
   /*                                                                       */
   /* <Values>                                                              */
   /*    FT_OUTLINE_NONE           :: Value 0 is reserved.                  */
@@ -428,11 +428,11 @@ FT_BEGIN_HEADER
  /*************************************************************************
   *
   * @enum:
-  *   ft_outline_xxx
+  *   ft_outline_flags
   *
   * @description:
   *   These constants are deprecated.  Please use the corresponding
-  *   @FT_OUTLINE_XXX values.
+  *   @FT_OUTLINE_FLAGS values.
   *
   * @values:
   *   ft_outline_none            :: See @FT_OUTLINE_NONE.
diff --git a/include/freetype/ftoutln.h b/include/freetype/ftoutln.h
index fdf7ed298..19b5724a5 100644
--- a/include/freetype/ftoutln.h
+++ b/include/freetype/ftoutln.h
@@ -46,7 +46,7 @@ FT_BEGIN_HEADER
   /*                                                                       */
   /* <Order>                                                               */
   /*    FT_Outline                                                         */
-  /*    FT_Outline_Flags                                                   */
+  /*    FT_OUTLINE_FLAGS                                                   */
   /*    FT_Outline_New                                                     */
   /*    FT_Outline_Done                                                    */
   /*    FT_Outline_Copy                                                    */
diff --git a/include/freetype/tttables.h b/include/freetype/tttables.h
index 0a78ef968..2d2e63c90 100644
--- a/include/freetype/tttables.h
+++ b/include/freetype/tttables.h
@@ -541,8 +541,15 @@ FT_BEGIN_HEADER
   } TT_MaxProfile;
 
 
-  /* */
-
+  /*************************************************************************/
+  /*                                                                       */
+  /* <Enum>                                                                */
+  /*    FT_Sfnt_Tag                                                        */
+  /*                                                                       */
+  /* <Description>                                                         */
+  /*    An enumeration used to specify the index of an SFNT table.         */
+  /*    Used in the @FT_Get_Sfnt_Table API function.                       */
+  /*                                                                       */
   typedef enum
   {
     ft_sfnt_head = 0,
@@ -553,10 +560,11 @@ FT_BEGIN_HEADER
     ft_sfnt_post = 5,
     ft_sfnt_pclt = 6,
 
-    sfnt_max   /* don't remove */
+    sfnt_max   /* internal end mark */
 
   } FT_Sfnt_Tag;
 
+  /* */
 
   /* internal use only */
   typedef void*
@@ -586,7 +594,7 @@ FT_BEGIN_HEADER
   /*    The table is owned by the face object and disappears with it.      */
   /*                                                                       */
   /*    This function is only useful to access SFNT tables that are loaded */
-  /*    by the sfnt/truetype/opentype drivers.  See FT_Sfnt_Tag for a      */
+  /*    by the sfnt/truetype/opentype drivers.  See @FT_Sfnt_Tag for a     */
   /*    list.                                                              */
   /*                                                                       */
   FT_EXPORT( void* )