Add guardspace description to manual

Author: mhosken

ChangeLog

@@ -8,7 +8,7 @@
     . Fonts no longer require a glyf/loca table. In such cases the bounding box is always 0.
     . Clang ASAN build support added for testing.
     . Handle out of memory sanely.
-    . Dcoumentation improvements
+    . Documentation improvements
     . Bug fixes:
         . Enforce fonts having to store glyph attributes by monotonically increasing attribute number
         . zeropadding was not getting called on feature tags

doc/font.txt

@@ -0,0 +1,78 @@
+== Font Topics ==
+
+=== Guard Space ===
+
+Graphite introduces guard space around diacritics. Sometimes a diacritic is
+wider than its base and the diacritic is in danger of crashing into clusters on
+either side of it. To stop that happening, graphite allows the font designer to
+signal that they want guard space to be ensured around a diacritic. For example,
+if a diacritic glyph is designed with a positive left side bearing and a
+positive right side bearing, the graphite engine will ensure that the cluster
+honours those side bearings for the diacritic. Of course, if the base character
+is wider than the diacritic, then no guard space is needed.
+
+The basic principle for cluster adjustment is that if a diacritic has a non-zero
+advance and after positioning, the advance of the diacritic is greater than the
+advance of the base then the advance of the base is increased to be the same as
+the positioned advance of the diacritic. Likewise if the origin of the diacritic
+is to the left of the origin of the base character, then the cluster is adjusted
+so that the origin of the diacritic is now where the origin of the base
+character was and the base character is moved to the right. Notice that this
+only happens if the origin of the diacritic is to the left of where it is
+attached or the advance is non-zero.
+
+In the following image, we use a dotless i with a combining tilde over it, which
+is wider than the dotless i. The four scenarios show how positioning the tilde
+and setting its advance controls the origin and advance of the attached cluster:
+
+image::guardspace.png[]
+
+Each line shows the two glyphs as they are designed with the origin and advance
+(if any). The third element on the line is the combined cluster. Again the
+origin and advance for the cluster is shown with solid lines and any subglyph
+origins and advances that don't coincide with a solid line, are shown dotted.
+Notice that we don't show the implied attachment point used to attach the tilde
+to the dotless i.
+
+The first line shows the diacritic as if it were a full base character, with
+positive left and right side bearings. When the glyphs attach the origin and the
+advance of the dotless i (shown as dotted lines) are pushed out to the origin
+and advance of the diacritic. Notice that graphite uses the wider advance and
+origin regardless of which component of the cluster they come from.
+
+The second line shows the other extreme. Here no guard space is inserted. The
+diacritic is to the left of the origin and the advance is zero. The cluster
+origin and advance are taken from the base glyph. The dotted line shows the
+origin and advance of the diacritic.
+
+These two lines are the most common cases that people want to use for rendering
+diacritics and whether space is automatically inserted to avoid collisions. The
+next two are rarely used but help to explain how the mechanism works.
+
+The third line has guard space on the left only. For this the diacritic is drawn
+to the right of the origin but the advance width is set to 0. The effect is that
+guard space is inserted on the left, because there is a positive left side
+bearing (or more precisely the origin of the diacritic is to the left of the
+origin of the base when the two glyphs combine). Thus the dotless i origin
+(shown as a dotted line) is pushed out. Actually the whole cluster is pushed to
+the right so that the origin of the diacritic is aligned with where the origin
+of the base glyph was.
+
+The fourth line gives guard space only after the diacritic. In this case, the
+diacritic is drawn to the left of the origin, and so no left guard space can
+occur, since the origin of the diacritic is to the right of the dotless i. The
+diacritic has also been drawn so that it finishes at the origin. This ensures
+that the guard space to the right is the same as the advance. It need not be.
+The cluster has the same origin as the base glyph. The base glyph advance is
+shown as a dotted line, which while not necessarily coinciding with the origin
+of the diacritic, will be close. Finally the advance for the cluster is the
+advance from the diacritic.
+
+Since it is possible to change the advance width of a glyph (or at least for a
+particular instance of a glyph or slot), it is possible to dynamically control
+some of the guard space mechanism within GDL. It is possible to use a rule to
+change from both to or from left only. Likewise it is possible to use a rule to
+change from none to or from right only. But, unfortunately, it is not possible
+to shift glyphs within their drawn space and so switch between both and none,
+purely from GDL.
+