Makefile: Improve commentary.

diff --git a/Makefile b/Makefile
index 60a827937e490f0570a5c464db74dfd8ebbe6ebe..fca5165e5cd0921e60c7d2ac009ec85426970151 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -21,6 +21,10 @@
 ### along with this program; if not, write to the Free Software Foundation,
 ### Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 
+###--------------------------------------------------------------------------
+### Utility macros.
+
+## Silent-rules machinery.
 V = 0
 v_tag = $(call v_tag_$V,$1)
 v_tag_0 = @printf "  %-6s %s\n" $1 $@;
@@ -29,13 +33,24 @@ V_GEN = $(call v_tag,GEN)
 V_AT = $(V_AT_$V)
 V_AT_0 = @
 
+## Splitting things at slashes -- don't leave the slash.
 dir-nosl = $(patsubst %/,%,$(dir $1))
 
+###--------------------------------------------------------------------------
+### Introductory machinery.
+
 all:
 .SECONDEXPANSION: # sorry
 
 CLEANFILES             += $(TARGETS)
 
+###--------------------------------------------------------------------------
+### Main source files.
+
+## There's a base set of files, and a number of optional modules.  A
+## collection of modules is called a `mode', and we generate an output file
+## for each required mode.
+
 EARLY                   = defs.m4 divmap.m4 config.m4
 MAIN                    = lists.m4 base.m4
 
@@ -52,6 +67,9 @@ OPTIONS_usersat                = auth.m4 local.m4 satellite.m4
 
 -include local.mk
 
+###--------------------------------------------------------------------------
+### Resolving what needs to be built.
+
 HOST_MODES             += $(foreach m, $(MODES), \
                                $(foreach h, $(HOSTS_$m), $h/$m))
 
@@ -67,6 +85,10 @@ all: $(TARGETS)
 host-mode               = $(notdir $(filter $1/%, $(HOST_MODES)))
 
 HOSTS                   = $(sort $(call dir-nosl, $(HOST_MODES)))
+
+###--------------------------------------------------------------------------
+### Propagating configuration to remote hosts.
+
 THISHOST                = $(shell hostname)
 OTHERHOSTS              = $(filter-out $(THISHOST), $(HOSTS))
 
@@ -88,3 +110,5 @@ install: $(addprefix install/, $(HOSTS))
 
 clean:; rm -f $(CLEANFILES)
 .PHONY: clean
+
+###----- That's all, folks --------------------------------------------------