From: Mark Wooding <mdw@distorted.org.uk>
Date: Fri, 10 Jan 2014 11:26:27 +0000 (+0000)
Subject: Makefile: Improve commentary.
X-Git-Url: https://git.distorted.org.uk/~mdw/exim-config/commitdiff_plain/c376fbe7c35f1efc79810fc12a0cfe3ca5d0d7e2

Makefile: Improve commentary.
---

diff --git a/Makefile b/Makefile
index 60a8279..fca5165 100644
--- 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 --------------------------------------------------