docs-common Makefile.common,1.121,1.122

[Tommy Reynolds (jtr)]

Author: jtr

Update of /cvs/docs/docs-common
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv26600

Modified Files:
	Makefile.common 
Log Message:
Added some rules of the road.



Index: Makefile.common
===================================================================
RCS file: /cvs/docs/docs-common/Makefile.common,v
retrieving revision 1.121
retrieving revision 1.122
diff -u -r1.121 -r1.122
--- Makefile.common	14 Jul 2006 22:10:39 -0000	1.121
+++ Makefile.common	15 Jul 2006 09:30:28 -0000	1.122
@@ -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