* Jamfile, docs/reference/README: fix it so that "jam refdoc" works

correctly to generate the API reference in 'docs/reference'

	* src/tools/docmaker/tohtml.py: update to output nicer fields lists
	in the API reference

	* src/base/ftobjs.c (FT_Load_Glyph): FT_LOAD_TARGET_LIGHT now
	forces auto-hinting

	* freetype/freetype.h: updating the documentation for
	FT_LOAD_TARGET_XXX and FT_Render_Mode values

ChangeLog

@@ -1,3 +1,18 @@
+2005-12-23  David Turner  <david@freetype.org>
+
+	* Jamfile, docs/reference/README: fix it so that "jam refdoc" works
+	correctly to generate the API reference in 'docs/reference'
+
+	* src/tools/docmaker/tohtml.py: update to output nicer fields lists
+	in the API reference
+
+	* src/base/ftobjs.c (FT_Load_Glyph): FT_LOAD_TARGET_LIGHT now
+	forces auto-hinting
+
+	* freetype/freetype.h: updating the documentation for
+	FT_LOAD_TARGET_XXX and FT_Render_Mode values
+
+
 2005-12-23  suzuki toshiya <mpsuzuki@hiroshima-u.ac.jp>
 
 	* src/base/ftmac.c (FT_New_Face_From_Suitcase): Counts scalable

Jamfile

@@ -181,6 +181,13 @@ if $(DEBUG_HINTER)
   SubInclude FT2_TOP tests ;
 }
 
+rule RefDoc
+{
+  Depends  $1 : all ;
+  NotFile  $1 ;
+  Always   $1 ;
+}
+
 actions RefDoc
 {
   python $(FT2_SRC)/tools/docmaker/docmaker.py --prefix=ft2 --title=FreeType-2.1.10 --output=$(DOC_DIR)  $(FT2_INCLUDE)/freetype/*.h  $(FT2_INCLUDE)/freetype/config/*.h  $(FT2_INCLUDE)/freetype/cache/*.h

docs/CHANGES

@@ -14,6 +14,10 @@ LATEST CHANGES BETWEEN 2.2.0 and 2.1.10
 
   II. IMPORTANT CHANGES
 
+    - the LIGHT hinting algorithm produces more pleasant results. Also,
+      using the FT_LOAD_TARGET_LIGHT flags within FT_Load_Glyph will always
+      force auto-hinting, as a special exception.
+
     - Face  metrics  (face->size->metrics)  and glyph  metrics are  no
       longer rounded.   If you do not round  in your applications too,
       you may find glyphs become blurry.
@@ -43,6 +47,11 @@ LATEST CHANGES BETWEEN 2.2.0 and 2.1.10
 
   III. MISCELLANEOUS
 
+    - the documentation for FT_LOAD_TARGET_XXX and FT_RENDER_MODE_XXX
+      values have been updated to better reflect their uses and differences
+      (one set is used to specify hinting algorithm, the other to specify
+      pixel rendering mode).
+    
     - FT_New_Face() & FT_New_Face_From_FSSpec() in ftmac.c are changed
       to count supported scalable faces (sfnt, LWFN) only, and returns
       the number of available faces via face->num_faces.   Unsupported
@@ -96,15 +105,15 @@ LATEST CHANGES BETWEEN 2.1.10 and 2.1.9
       highly recommended to upgrade.
 
     - FreeType didn't properly parse empty Type 1 glyphs.
-    
+
     - An unbound dynamic buffer growth was fixed in the PFR loader.
-    
+
     - Several bugs have been fixed in the cache sub-system.
 
     - FreeType behaved incorrectly when resizing two distinct but very
       close character pixel sizes through `FT_Set_Char_Size' (Savannah
       bug #12263).
-      
+
     - The auto-hinter didn't work properly for fonts without a Unicode
       charmap -- it even refused to load the glyphs.
 
@@ -184,7 +193,7 @@ LATEST CHANGES BETWEEN 2.1.10 and 2.1.9
       PIC mode (i.e.,  when generating a  Unix shared object/dll)  put
       the array  into the non-shared  writable section of  the library
       since absolute pointers are not relocatable by nature.
-      
+
       This reduces the memory consumption by approximately 16KByte per
       process linked  to FreeType.   We now also store  the array in a
       compressed form (as a trie) which saves about 20KByte of code as

docs/reference/README

@@ -1,2 +1,5 @@
 After saying `make refdoc' this directory contains the FreeType API
 reference.  You need python to make this target.
+
+This also works with Jam, just type 'jam refdoc' in the main directory.
+

include/freetype/freetype.h

@@ -2356,7 +2356,7 @@ FT_BEGIN_HEADER
   *   FT_LOAD_IGNORE_TRANSFORM ::
   *     Indicates that the glyph loader should not try to transform the
   *     loaded glyph image.  This doesn't prevent scaling, hinting, or
-  *     rendering.
+  *     rendering. See @FT_Set_Transform
   *
   *   FT_LOAD_MONOCHROME ::
   *     This flag is used with @FT_LOAD_RENDER to indicate that you want
@@ -2379,34 +2379,9 @@ FT_BEGIN_HEADER
   *     See also FT_FACE_FLAG_HINTER (@FT_FACE_FLAG_XXX), FT_LOAD_FORCE_AUTO,
   *     and FT_LOAD_NO_HINTING above.
   *
-  *   FT_LOAD_TARGET_NORMAL ::
-  *     Use hinting for @FT_RENDER_MODE_NORMAL.
-  *
-  *   FT_LOAD_TARGET_LIGHT ::
-  *     Use hinting for @FT_RENDER_MODE_LIGHT.
-  *
-  *   FT_LOAD_TARGET_MONO ::
-  *     Use hinting for @FT_RENDER_MODE_MONO.
-  *
-  *   FT_LOAD_TARGET_LCD ::
-  *     Use hinting for @FT_RENDER_MODE_LCD.
-  *
-  *   FT_LOAD_TARGET_LCD_V ::
-  *     Use hinting for @FT_RENDER_MODE_LCD_V.
-  *
   * @note:
-  *   You should use only _one_ of the FT_LOAD_TARGET_XXX values; they
+  *   see also @FT_LOAD_TARGET_XXX which relate to hinting algorithm
-  *   can't be ORed.
+  *   selection.
-  *
-  *   However, FreeType makes a distinction between the hinting algorithm
-  *   being used, and the pixel mode of the target bitmaps.  For example,
-  *   it is possible to use the `light' hinting algorithm and have the
-  *   results rendered in horizontal LCD pixel mode, with code like this:
-  *
-  *     FT_Load_Glyph( face, glyph_index,
-  *                    load_flags | FT_LOAD_TARGET_LIGHT );
-  *     FT_Render_Glyph( face->glyph, FT_RENDER_MODE_LCD );
-  *
   */
 #define FT_LOAD_DEFAULT                      0x0
 #define FT_LOAD_NO_SCALE                     0x1
@@ -2429,8 +2404,72 @@ FT_BEGIN_HEADER
 
   /* */
 
+ /**************************************************************************
+  *
+  * @enum: FT_LOAD_TARGET_XXX
+  *
+  * @description:
+  *   a list of values that are used to select a specific hinting
+  *   algorithm to the glyph loader. You should OR one of these values
+  *   to your 'load_flags' when calling @FT_Load_Glyph.
+  *
+  *   note that these values are only used by the auto-hinter, and ignored
+  *   by the native ones (e.g. the TrueType bytecode interpreter). You
+  *   must use @FT_LOAD_FORCE_AUTOHINT to ensure that they're always used.
+  *
+  *   @FT_LOAD_TARGET_LIGHT being an exception, that always forces the
+  *   auto-hinter.
+  *
+  * @values:
+  *   FT_LOAD_TARGET_NORMAL ::
+  *     correspond to the default hinting algorithm, optimized for standard
+  *     gray-level rendering. for monochrome output, use @FT_RENDER_MODE_MONO
+  *     instead.
+  *
+  *   FT_LOAD_TARGET_LIGHT ::
+  *     correspond to a lighter hinting algorithm for non-monochrome modes.
+  *     This will generate more glyphs that are more fuzzy but more faithful
+  *     to their original shape. A bit like Mac OS X.
+  *
+  *     As a special exception, this values *always* forces auto-hinting,
+  *     whatever the native hinter is.
+  *
+  *   FT_LOAD_TARGET_MONO ::
+  *     strong hinting algorithm that should only be used for monochrome
+  *     output. The result will probably be unpleasant for other rendering
+  *     modes.
+  *
+  *   FT_LOAD_TARGET_LCD ::
+  *     a variant of @FT_LOAD_TARGET_NORMAL optimized for horizontally
+  *     decimated LCD displays.
+  *
+  *   FT_LOAD_TARGET_LCD_V ::
+  *     a variant of @FT_LOAD_TARGET_NORMAL optimized for vertically decimated
+  *     LCD displays.
+  *
+  * @note:
+  *   You should use only _one_ of the FT_LOAD_TARGET_XXX values in your
+  *   'load_flags'. They can't be ORed.
+  *
+  *   If you also use the @FT_LOAD_RENDER flag, then the output will be
+  *   determined by the corresponding @FT_Render_Mode value. E.g.
+  *   @FT_LOAD_TARGET_NORMAL will generate a gray-level pixmap
+  *   (see @FT_RENDER_MODE_NORMAL)
+  *
+  *   You can use a hinting algorithm that doesn't correspond to the same
+  *   rendering mode. For example, it is possible to use the `light' hinting
+  *   algorithm and have the results rendered in horizontal LCD pixel mode,
+  *   with code like this:
+  *
+  *   {
+  *     FT_Load_Glyph( face, glyph_index,
+  *                    load_flags | FT_LOAD_TARGET_LIGHT );
+  *
+  *     FT_Render_Glyph( face->glyph, FT_RENDER_MODE_LCD );
+  *   }
+  */
+
 #define FT_LOAD_TARGET_( x )      ( (FT_Int32)( (x) & 15 ) << 16 )
-#define FT_LOAD_TARGET_MODE( x )  ( (FT_Render_Mode)( ( (x) >> 16 ) & 15 ) )
 
 #define FT_LOAD_TARGET_NORMAL     FT_LOAD_TARGET_( FT_RENDER_MODE_NORMAL )
 #define FT_LOAD_TARGET_LIGHT      FT_LOAD_TARGET_( FT_RENDER_MODE_LIGHT  )
@@ -2438,6 +2477,15 @@ FT_BEGIN_HEADER
 #define FT_LOAD_TARGET_LCD        FT_LOAD_TARGET_( FT_RENDER_MODE_LCD    )
 #define FT_LOAD_TARGET_LCD_V      FT_LOAD_TARGET_( FT_RENDER_MODE_LCD_V  )
 
+/**
+ * @macro: FT_LOAD_TARGET_MODE
+ *
+ * @description:
+ *   return the @FT_Render_Mode corresponding to a given @FT_LOAD_TARGET_XXX
+ *   value.
+ */
+#define FT_LOAD_TARGET_MODE( x )  ( (FT_Render_Mode)( ( (x) >> 16 ) & 15 ) )
+
   /* */
 
 
@@ -2480,8 +2528,7 @@ FT_BEGIN_HEADER
   /* <Description>                                                         */
   /*    An enumeration type that lists the render modes supported by       */
   /*    FreeType 2.  Each mode corresponds to a specific type of scanline  */
-  /*    conversion performed on the outline, as well as specific           */
+  /*    conversion performed on the outline.                               */
-  /*    hinting optimizations.                                             */
   /*                                                                       */
   /*    For bitmap fonts the `bitmap->pixel_mode' field in the             */
   /*    @FT_GlyphSlotRec structure gives the format of the returned        */
@@ -2493,14 +2540,10 @@ FT_BEGIN_HEADER
   /*      anti-aliased bitmaps, using 256 levels of opacity.               */
   /*                                                                       */
   /*    FT_RENDER_MODE_LIGHT ::                                            */
-  /*      This is similar to @FT_RENDER_MODE_NORMAL -- you have to use     */
+  /*      This is equivalent to @FT_RENDER_MODE_NORMAL. It is only defined */
-  /*      @FT_LOAD_TARGET_LIGHT in calls to @FT_Load_Glyph to get any      */
+  /*      as a separate value because render modes are also used           */
-  /*      effect since the rendering process no longer influences the      */
+  /*      indirectly to define hinting algorithm selectors. See            */
-  /*      positioning of glyph outlines.                                   */
+  /*      @FT_LOAD_TARGET_XXX for details.                                 */
-  /*                                                                       */
-  /*      The resulting glyph shapes are more similar to the original,     */
-  /*      while being a bit more fuzzy (`better shapes' instead of `better */
-  /*      contrast', so to say.                                            */
   /*                                                                       */
   /*    FT_RENDER_MODE_MONO ::                                             */
   /*      This mode corresponds to 1-bit bitmaps.                          */
@@ -2691,7 +2734,8 @@ FT_BEGIN_HEADER
   /*                                                                       */
   /* <Description>                                                         */
   /*    Retrieves the ASCII name of a given glyph in a face.  This only    */
-  /*    works for those faces where FT_HAS_GLYPH_NAME(face) returns true.  */
+  /*    works for those faces where @FT_HAS_GLYPH_NAMES(face) returns      */
+  /*    TRUE.                                                              */
   /*                                                                       */
   /* <Input>                                                               */
   /*    face        :: A handle to a source face object.                   */

src/base/ftobjs.c

@@ -523,6 +523,11 @@
                                  FT_LOAD_NO_AUTOHINT ) )   &&
                FT_DRIVER_IS_SCALABLE( driver )             &&
                FT_DRIVER_USES_OUTLINES( driver )           );
+
+    /* force auto-hinting for the LIGHT hinting mode */
+    if ( autohint && FT_LOAD_TARGET_MODE(load_flags) == FT_RENDER_MODE_LIGHT )
+      load_flags |= FT_LOAD_FORCE_AUTOHINT;
+
     if ( autohint )
     {
       if ( FT_DRIVER_HAS_HINTER( driver ) &&

src/tools/docmaker/tohtml.py

@@ -192,6 +192,7 @@ class HtmlFormatter(Formatter):
                 url   = self.make_block_url( block )
                 return '<a href="' + url + '">' + name + '</a>' + rest
             except:
+                # we detected a cross-reference to an unknown item
                 return '?' + name + '?' + rest
 
         # look for italics and bolds
@@ -246,7 +247,7 @@ class HtmlFormatter(Formatter):
 
     def print_html_field( self, field ):
         if field.name:
-            print "<table><tr valign=top><td><b>"+field.name+"</b></td><td>"
+            print "<table><tr valign=top><td><p><b>"+field.name+"</b></p></td><td>"
 
         print self.make_html_items( field.items )
 
@@ -288,9 +289,14 @@ class HtmlFormatter(Formatter):
 
 
     def print_html_field_list( self, fields ):
-        print "<table cellpadding=3>"
+        print "<table cellpadding=3 border=0>"
         for field in fields:
-            print "<tr valign=top><td><b>" + field.name + "</b></td><td>"
+            if len(field.name) > 22:
+              print "<tr valign=top><td colspan=0><b>"+field.name+"</b></td></tr>"
+              print "<tr valign=top><td></td><td>"
+            else:
+              print "<tr valign=top><td><b>" + field.name + "</b></td><td>"
+
             self.print_html_items( field.items )
             print "</td></tr>"
         print "</table>"
@@ -488,4 +494,4 @@ class HtmlFormatter(Formatter):
     def section_dump_all( self ):
         for section in self.sections:
             self.section_dump( section, self.file_prefix + section.name + '.html' )
-        
+