font-patcher: Add documentation on ScaleGroups

[why]
The old doc was a bit unclear and I always had to read the code when
changes / additions to ScaleRules were needed.

Signed-off-by: Fini Jastrow <ulf.fini.jastrow@desy.de>

font-patcher

@@ -6,7 +6,7 @@
 from __future__ import absolute_import, print_function, unicode_literals
 
 # Change the script version when you edit this script:
-script_version = "3.2.2"
+script_version = "3.3.0"
 
 version = "2.3.0-RC"
 projectName = "Nerd Fonts"
@@ -739,11 +739,46 @@ class font_patcher:
             'default': {'align': 'c', 'valign': '', 'stretch': '', 'params': {}}
         }
 
-        # Most glyphs we want to maximize during the scale.  However, there are some
-        # that need to be small or stay relative in size to each other.
-        # The following list are those glyphs.  A tuple represents a range.
-        # See prepareScaleRules() for an explanation how this needs to look like.
+        # Most glyphs we want to maximize (individually) during the scale
+        # However, there are some that need to be small or stay relative in
+        # size to each other.
+        # The glyph-specific behavior can be given as ScaleRules in the patch-set.
+        #
+        # ScaleRules can contain two different kind of rules (possibly in parallel):
+        #   - ScaleGlyph:
+        #       Here one specific glyph is used as 'scale blueprint'. Other glyphs are
+        #       scaled by the same factor as this glyph. This is useful if you have one
+        #       'biggest' glyph and all others should stay relatively in size.
+        #   - ScaleGroups:
+        #       Here you specify a group of glyphs that should be handled together
+        #       with the same scaling and shifting. The basis for it is a 'combined
+        #       bounding box' of all glyphs in that group. All glyphs are handled as
+        #       if they fill that combined bounding box.
+        #
+        # The ScaleGlyph method: You set 'ScaleGlyph' to the unicode of the reference glyph.
+        # Note that there can be only one per patch-set.
+        # Additionally you set 'GlyphsToScale' that contains all the glyphs that shall be
+        # handled like the reference glyph.
+        # It is a List of: ((glyph code) or (tuple of two glyph codes that form a closed range))
+        #    'GlyphsToScale': [
+        #        0x0100, 0x0300, 0x0400,  # The single glyphs 0x0100, 0x0300, and 0x0400
+        #        (0x0200, 0x0210),        # All glyphs 0x0200 to 0x0210 including both 0x0200 and 0x0210
+        #    ]}
+        #
+        # For the ScaleGroup method you define any number groups of glyphs and each group is
+        # handled separately. The combined bounding box of all glyphs in the group is determined
+        # and based on that the scale and shift for all the glyphs in the group.
+        # You define the groups as value of 'ScaleGroups'.
+        # It is a List of: ((lists of glyph codes) or (ranges of glyph codes))
+        #    'ScaleGroups': [
+        #        [0x0100, 0x0300, 0x0400],  # One group consists of glyphs 0x0100, 0x0300, and 0x0400
+        #        range(0x0200, 0x0210 + 1), # Another group contains glyphs 0x0200 to 0x0210 incl.
+        #
+        # Note the subtle differences: tuple vs. range; closed vs open range; etc
+        # See prepareScaleRules() for some more details.
+        # For historic reasons ScaleGroups is sometimes called 'new method' and ScaleGlyph 'old'.
         # The codepoints mentioned here are symbol-font-codepoints.
+
         DEVI_SCALE_LIST  = {'ScaleGlyph': 0xE60E, # Android logo
             'GlyphsToScale': [
                 (0xe6bd, 0xe6c3) # very small things
@@ -1203,11 +1238,11 @@ class font_patcher:
 
     def prepareScaleRules(self, scaleRules, symbolFont, destGlyph):
         """ Prepare raw ScaleRules data for use """
-        # The GlyphData is a dict with these (possible) entries:
+        # The scaleRules is/will be a dict with these (possible) entries:
         # 'ScaleGroups': List of ((lists of glyph codes) or (ranges of glyph codes)) that shall be scaled
         # 'scales': List of associated scale factors, one for each entry in 'ScaleGroups' (generated by this function)
         # 'bbdims': List of associated sym_dim dicts, one for each entry in 'ScaleGroups' (generated by this function)
-        #           Each sym_dim dict describes the combined bounding box of all glyphs in one ScaleGroups group
+        #           Each dim_dict describes the combined bounding box of all glyphs in one ScaleGroups group
         # Example:
         # { 'ScaleGroups': [ range(1, 3), [ 7, 10 ], ],
         #   'scales':      [ 1.23,        1.33,      ],
@@ -1219,10 +1254,12 @@ class font_patcher:
         #
         # Previously this structure has been used:
         #   'ScaleGlyph' Lead glyph, which scaling factor is taken
-        #   'GlyphsToScale': List of (glyph code) or (list of two glyph codes that form a closed range)) that shall be scaled
+        #   'GlyphsToScale': List of ((glyph code) or (tuple of two glyph codes that form a closed range)) that shall be scaled
         #   Note that this allows only one group for the whle symbol font, and that the scaling factor is defined by
         #   a specific character, which needs to be manually selected (on each symbol font update).
         #   Previous entries are automatically rewritten to the new style.
+        #
+        # Note that scaleRules is overwritten with the added data.
         if 'scales' in scaleRules:
             # Already prepared... must not happen, ignore call
             return
@@ -1238,7 +1275,7 @@ class font_patcher:
             scaleRules['bbdims'].append(sym_dim)
 
         if 'ScaleGlyph' in scaleRules:
-            # old method. Rewrite to new.
+            # Rewrite to equivalent ScaleGroup
             flat_list = []
             for i in scaleRules['GlyphsToScale']:
                 if isinstance(i, tuple):