fontbuild: document post-processing directives

1 files changed, 13 insertions, 3 deletions

diff --git a/misc/fontbuild b/misc/fontbuild
index 3d3d70b76..a1fe3aa7b 100755
--- a/misc/fontbuild
+++ b/misc/fontbuild
@@ -30,7 +30,6 @@ from ufo2ft import CFFOptimization
 
 log = logging.getLogger(__name__)
 stripItalic_re = re.compile(r'(?:^|\b)italic(?:\b|$)', re.I | re.U)
-findPost_re = re.compile(r'\!post:([^ ]+)', re.I | re.U)
 
 
 def stripItalic(name):
@@ -80,15 +79,26 @@ def composedGlyphIsNonTrivial(g, yAxisIsNonTrivial=False):
   return False
 
 
+# Directives are glyph-specific post-processing directives for the compiler.
+# A directive is added to the "note" section of a glyph and takes the
+# following form:
+# 
+#   !post:DIRECTIVE
+# 
+# Where DIRECTIVE is the name of a known directive.
+# This string can appear anywhere in the glyph note.
+# 
 knownDirectives = set([
-  'removeoverlap',
+  'removeoverlap',  # applies overlap removal (boolean union)
 ])
 
 
+findDirectiveRegEx = re.compile(r'\!post:([^ ]+)', re.I | re.U)
+
 def findGlyphDirectives(g): # -> set<string> | None
   directives = set()
   if g.note and len(g.note) > 0:
-    for directive in findPost_re.findall(g.note):
+    for directive in findDirectiveRegEx.findall(g.note):
       directive = directive.lower()
       if directive in knownDirectives:
         directives.add(directive)