Added some rules of the road.

1 files changed, 32 insertions, 0 deletions

diff --git a/Makefile.common b/Makefile.common
index 3223389..675b39c 100644
--- a/Makefile.common
+++ b/Makefile.common
@@ -12,6 +12,38 @@
 #########################################################################
 
 #########################################################################
+# STYLE GUIDE (Or, How To Keep Tommy From Raising A Single Eyebrow At You)
+# 1) Lines are 80 characters, max.
+# 2) Tabs are 8 characters, exactly.
+# 3) All targets must use the "::" form to allow multiple instances of
+#    the target.
+# 4) Keep a modular Makefile.  For example, do NOT group all the "clean:"
+#    rules into one place.  Using the "::" form lets us keep all the 
+#    targets and rules for one object (file, template, whatever) close
+#    together.  This makes maintenance much, much easier.
+#########################################################################
+# One key to writing good rules (the commands run to build a target) is
+# to write the shell commands so they could be cut'n pasted into a real
+# shell window.  To do this, we have to find a common pidgen syntax that
+# works for both make(1) and the Bourne-type shells.
+#
+# Compared to even the most basic shell, the make(1) parser is very 
+# limited.  This is most visible when referencing shell variables or
+# make(1) macros.  While a shell only needs delimiters to disambiguate
+# $FOObar from ${FOO}bar, make(1) needs the delimiters for any macro
+# name longer than one character.  Combining the two rules, we get:
+#
+# 1) In a shell script, use the form ${FOO} to reference *EVERY* variable
+#    instead of using $(FOO); most shells interpret the parens as a 
+#    directive to run the contents in a subshell.  All shells correctly
+#    handle the ${} braces form.
+# 2) In a make(1) rule, use the form ${FOO} instead of $(FOO) when
+#    referencing macros.
+# 3) Reserve the form $(FOO), with parens, for enclosing real shell
+#    commands such as $(shell /bin/pwd)
+#########################################################################
+
+#########################################################################
 # Note: all targets within this Makefile.common must be defined as 
 # double-colon (::) targets so that additional steps can be added by
 # providing additional rules, also marked with double-colons, in the