Commit 6af024231b65f8a10b9d1f5f08b5774cf3edbe0a

Werner Lemberg 2011-02-22T10:29:30

[autofit] Add ASCII drawing for better explanation.

diff --git a/src/autofit/afhints.h b/src/autofit/afhints.h
index d63b979..649d4a9 100644
--- a/src/autofit/afhints.h
+++ b/src/autofit/afhints.h
@@ -91,6 +91,20 @@ FT_BEGIN_HEADER
    *    edges; they are specific to a script.
    *
    *
+   *                      A          H
+   *                       |        |
+   *                       |        |
+   *                       |        |
+   *                       |        |
+   *         C             |        |             F
+   *          +------<-----+        +-----<------+
+   *          |             B      G             |
+   *          |                                  |
+   *          |                                  |
+   *          +--------------->------------------+
+   *         D                                    E
+   *
+   *
    *  Stems
    *
    *    Segments need to be `linked' to other ones in order to detect stems.
@@ -99,6 +113,9 @@ FT_BEGIN_HEADER
    *    vocabulary from the TrueType specification, stem segments form a
    *    `black distance'.
    *
+   *    In the above ASCII drawing, the horizontal segments are BC, DE, and
+   *    FG; the vertical segments are AB, CD, EF, and GH.
+   *
    *    Each segment has at most one `best' candidate to form a black
    *    distance, or no candidate at all.  Notice that two distinct segments
    *    can have the same candidate, which frequently means a serif.
@@ -112,6 +129,11 @@ FT_BEGIN_HEADER
    *
    *    Stems are detected by `af_{cjk,latin,...}_hint_edges'.
    *
+   *    In the above ASCII drawing, the best candidate for both AB and CD is
+   *    GH, while the best candidate for GH is AB.  Similarly, the best
+   *    candidate for EF and GH is AB, while the best candidate for AB is
+   *    GH.
+   *
    *
    *  Serifs
    *
@@ -119,7 +141,8 @@ FT_BEGIN_HEADER
    *
    *      best segment_1 = segment_2 && best segment_2 != segment_1
    *
-   *    where segment_1 corresponds to the serif segment.
+   *    where segment_1 corresponds to the serif segment (CD and EF in the
+   *    above ASCII drawing).
    *
    *    The best candidate is stored in field `serif' in structure
    *    `AF_Segment' (and `link' is set to NULL).