10 files changed, 247 insertions, 5 deletions
diff --git a/build-aux/Makefile.once.head/00-gitfiles.mk b/build-aux/Makefile.once.head/00-gitfiles.mk
index b17b63aa09..faae91dcd1 100644
--- a/build-aux/Makefile.once.head/00-gitfiles.mk
+++ b/build-aux/Makefile.once.head/00-gitfiles.mk
@@ -15,6 +15,47 @@
 
 mod.gitfiles.description = Automatically populate files.src.src from git
 mod.gitfiles.depends += files nested write-ifchanged quote
+mod.gitfiles.files += $(topsrcdir)/$(gitfiles.file)
+define mod.gitfiles.doc
+# Inputs:
+#   - Global variable    : `gitfiles.file` (Default: gitfiles.mk)
+#   - Directory variable : `nested.subdirs`
+#   - External           : git
+# Outputs:
+#   - File               : `$(topsrcdir)/$(gitfiles.file)`
+#   - Directory variable : `files.src.src`
+#   - Directory variable : `files.src.gen` (only in top dir)
+#
+# The `files` module has a variable (`files.src.src`) that you (the
+# developer) set to list "pure" source files; the type of files that you
+# would check into a version control system.  Since you are a
+# responsible developer, you use a version control system.  Since the
+# computer is already maintaining a list of these files *in the VCS*,
+# why should you--a filthy human--need to also maintain the list?  Enter
+# gitfiles, which will talk to git to maintain `files.src.src`, but
+# won't require that the git repository be distributed to
+# installing-users.
+#
+# If `$(topsrcdir)/.git` exists, then it will generate
+# `$(topsrcdir)/$(gitfiles.file)`.  Otherwise, it will assume that
+# `$(topsrcdir)/$(gitfiles.file)` already exists.
+#
+# It will use the information in `$(topsrcdir)/$(gitfiles.file)` to
+# append to `files.src.src` in each directory
+#
+# Finally, since the generated `$(topsrcdir)/$(gitfiles.file)` must be
+# distributed to users, it is added to $(topsrcdirs)'s `files.src.gen`.
+#
+# When setting `files.src.src`, it needs to know which files "belong" to
+# the current directory directly, and which "belong" to a further
+# subdirectory.  To do this, it uses an expression involving
+# `$(nested.subdirs)`.
+#
+# While gitfiles sets `files.src.src` very early
+# in `each.head`, because `nested.subdirs` might not be set yet, it may
+# or may not be safe to use the value of `$(files.src.src)` in your
+# Makefile, depending on how you set `nested.subdirs`.
+endef
 
 gitfiles.file ?= gitfiles.mk
 
diff --git a/build-aux/Makefile.once.head/00-quote.mk b/build-aux/Makefile.once.head/00-quote.mk
index 9fce401b94..4c954b1040 100644
--- a/build-aux/Makefile.once.head/00-quote.mk
+++ b/build-aux/Makefile.once.head/00-quote.mk
@@ -14,6 +14,24 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 mod.quote.description = Macros to quote tricky strings
+define mod.quote.doc
+# Inputs:
+#   (none)
+# Outputs:
+#   - Global variable: `quote.var`       : GNU Make variables
+#   - Global variable: `quote.pattern`   : GNU Make patterns
+#   - Global variable: `quote.ere`       : POSIX Extended Regular Expressions
+#   - Global variable: `quote.bre`       : POSIX Basic Regular Expressions
+#   - Global variable: `quote.shell`     : POSIX sh(1) strings
+#   - Global variable: `quote.shell-each`: POSIX sh(1) strings
+#
+# Escaping/quoting things is hard!  This module provides a number of
+# functions to escape/quote strings for various contexts.
+#
+# `quote.shell-each` quotes each list-item separately (munging
+# whitespace), while `quote.shell` keeps them as one string (preserving
+# whitespace).
+endef
 
 _quote.backslash = $(if $1,$(call _quote.backslash,$(wordlist 2,$(words $1),$1),$(subst $(firstword $1),\$(firstword $1),$2)),$2)
 
@@ -24,6 +42,7 @@ quote.bre     = $(call _quote.backslash, \ ^ . [ $$       *       ,$1)
 
 quote.shell-each = $(foreach _quote.tmp,$1,$(call quote.shell,$(_quote.tmp)))
 
-# I put this as the last line in the file because it confuses Emacs syntax
-# highlighting and makes the remainder of the file difficult to edit.
+# I put this as the last line in the file because it confuses Emacs
+# syntax highlighting and makes the remainder of the file difficult to
+# edit.
 quote.shell = $(subst $(at.nl),'$$'\n'','$(subst ','\'',$1)')
diff --git a/build-aux/Makefile.once.head/00-var.mk b/build-aux/Makefile.once.head/00-var.mk
index d1e537ef34..636bbb0108 100644
--- a/build-aux/Makefile.once.head/00-var.mk
+++ b/build-aux/Makefile.once.head/00-var.mk
@@ -14,5 +14,19 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 mod.var.description = Depend on the values of variables
+define mod.var.doc
+# Inputs:
+#   (user-defined)
+# Outputs:
+#   Target            : `$(outdir)/.var.%`
+#   Directory variable: `at.targets`
+#
+# It's a well-known secret that many files generated by a Makefile vary with
+# the values of particular variables, but that GNU Make can't track these
+# dependencies.  Well, with some cleverness, it actually can!
+#
+# With this module, to depend on the value of a variable, depend on
+# `$(outdir)/.var.VARNAME`.
+endef
 
 .PHONY: _var.FORCE
diff --git a/build-aux/Makefile.once.head/10-dist.mk b/build-aux/Makefile.once.head/10-dist.mk
index e139096576..8c68d041f3 100644
--- a/build-aux/Makefile.once.head/10-dist.mk
+++ b/build-aux/Makefile.once.head/10-dist.mk
@@ -14,6 +14,40 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 mod.dist.description = `dist` target for distribution tarballs
+define mod.dist.doc
+# User variables:
+#   - `CP      ?= cp`
+#   - `GZIP    ?= gzip`
+#   - `MKDIR   ?= mkdir`
+#   - `MKDIR_P ?= mkdir -p`
+#   - `MV      ?= mv`
+#   - `RM      ?= rm -f`
+#   - `TAR     ?= tar`
+#   - `GZIPFLAGS ?= $(GZIP_ENV)`
+#   - `GZIP_ENV ?= --best` (only used via `GZIPFLAGS`, not directly)
+# Inputs:
+#   - Global variable    : `dist.exts`    (Default: `.tar.gz`)
+#   - Global variable    : `dist.pkgname` (Default: first of PACKAGE_TARNAME PACKAGE PACKAGE_NAME)
+#   - Global variable    : `dist.version` (Default: first of PACKAGE_VERSION VERSION)
+#   - Directory variable : `files.src`
+# Outputs:
+#   - Directory variable : `files.out.int` (only in top dir)
+#   - .PHONY Target      : `$(outdir)/dist`
+#   - Target             : `$(topoutdir)/$(dist.pkgname)-$(dist.version)`
+#   - Target             : `$(topoutdir)/$(dist.pkgname)-$(dist.version).tar`
+#   - Target             : `$(topoutdir)/$(dist.pkgname)-$(dist.version).tar.gz`
+#
+# Provide the standard `dist` .PHONY target, based on the `files` module
+# information.
+#
+# You may change the default compression target easily via the
+# `dist.exts` variable, but you must define the rule for it manually.
+#
+# Bugs:
+#
+#   The tarball isn't reproducible.  It uses file-system ordering of
+#   files, and includes timestamps.
+endef
 
 # Developer configuration
 
diff --git a/build-aux/Makefile.once.head/10-files.mk b/build-aux/Makefile.once.head/10-files.mk
index 54417356ee..9d27ae9931 100644
--- a/build-aux/Makefile.once.head/10-files.mk
+++ b/build-aux/Makefile.once.head/10-files.mk
@@ -15,6 +15,45 @@
 
 mod.files.description = Keeping track of groups of files
 mod.files.depends += nested
+define mod.files.doc
+# User variables:
+#   - `DESTDIR ?=`
+#   - `RM      ?= rm -f`
+#   - `RMDIR_P ?= rmdir -p --ignore-fail-on-non-empty`
+#   - `TRUE    ?= true`
+# Inputs:
+#   - Global variable    : `files.groups   ?= all`
+#   - Global variable    : `files.default  ?= all`
+#   - Global variable    : `files.vcsclean ?= files.vcsclean`
+#   - Global variable    : `files.generate ?= files.generate`
+#   - Directory variable : `files.src.src`
+#   - Directory variable : `files.src.int`
+#   - Directory variable : `files.src.cfg`
+#   - Directory variable : `files.src.gen`
+#   - Directory variable : `files.out.slow`
+#   - Directory variable : `files.out.int`
+#   - Directory variable : `files.out.cfg`
+#   - Directory variable : `files.out.$(files.groups)` (well, $(addprefix...))
+#   - Directory variable : `files.sys.$(files.groups)` (well, $(addprefix...))
+# Outputs:
+#   - Global variable : `nested.targets`
+#   - Global variable : `at.targets`
+#   - Global variable : `.DEFAULT_GOAL = $(files.default)`
+#   - Creative .PHONY targets:
+#     - `$(outdir)/$(files.generate))`
+#     - `$(addprefix $(outdir)/,$(files.groups))`
+#     - `$(outdir)/installdirs`
+#     - `$(outdir)/install`
+#   - Destructive .PHONY targets:
+#     - `$(outdir)/uninstall`
+#     - `$(outdir)/mostlyclean`
+#     - `$(outdir)/clean`
+#     - `$(outdir)/distclean`
+#     - `$(outdir)/maintainer-clean`
+#     - `$(outdir)/$(files.vcsclean)`
+#
+# TODO: prose documentation
+endef
 
 files.groups ?= all
 files.default ?= all
diff --git a/build-aux/Makefile.once.head/10-gnuconf.mk b/build-aux/Makefile.once.head/10-gnuconf.mk
index c07cfb5cf3..6d641bba7c 100644
--- a/build-aux/Makefile.once.head/10-gnuconf.mk
+++ b/build-aux/Makefile.once.head/10-gnuconf.mk
@@ -13,10 +13,21 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-# This file is based on §7.2 "Makefile Conventions" of the release of
-# the GNU Coding Standards dated July 25, 2016.
-
 mod.gnuconf.description = GNU standard configuration variables
+define mod.gnuconf.doc
+# Inputs:
+#   - Global variable: `gnuconf.pkgname`
+#      (Default: `$(firstword $(PACKAGE_TARNAME) $(PACKAGE) $(PACKAGE_NAME))`)
+# Outputs:
+#   (see below)
+#
+# This module defines default values (using `?=`) a huge list of
+# variables specified in the GNU Coding Standards that installing-users
+# expect to be able to set.
+#
+# This is based on §7.2 "Makefile Conventions" of the July 25, 2016
+# release of the GNU Coding Standards.
+endef
 
 gnuconf.pkgname ?= $(firstword $(PACKAGE_TARNAME) $(PACKAGE) $(PACKAGE_NAME))
 ifeq ($(gnuconf.pkgname),)
diff --git a/build-aux/Makefile.once.head/10-nested.mk b/build-aux/Makefile.once.head/10-nested.mk
index af9fdf7d8a..72e15ab533 100644
--- a/build-aux/Makefile.once.head/10-nested.mk
+++ b/build-aux/Makefile.once.head/10-nested.mk
@@ -14,5 +14,31 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 mod.nested.description = Easy nested .PHONY targets
+define mod.nested.doc
+# Inputs:
+#   - Global variable    : `nested.targets`
+#   - Directory variable : `nested.subdirs`
+# Outputs:
+#   - .PHONY Targets     : `$(addprefix $(outdir)/,$(nested.targets))`
+#   - Variable           : `at.subdirs`
+#
+# The Autothing `at.subdirs` slates a subdirectory's Makefile for inclusion,
+# but doesn't help with recursive targets like `all`, `install`, or `clean`,
+# which one would expect to descend into subdirectories.  Enter `nested`:
+# Define a global list of targets that are recursive/nested, and then in each
+# directory define a list of subdirectries that one would expect them to
+# recurse into.
+#
+# Directories added to `nested.subdirs` are automatically added to `at.subdirs`
+# during the each.tail phase.
+#
+# It may help to think of at.subdirs and nested.subdirs in terms of their
+# Automake conterparts:
+#
+#      | Autothing      | GNU Automake |
+#      +----------------+--------------+
+#      | at.subdirs     | DIST_SUBDIRS |
+#      | nested.subdirs | SUBDIRS      |
+endef
 
 nested.targets ?=
diff --git a/build-aux/Makefile.once.head/10-write-atomic.mk b/build-aux/Makefile.once.head/10-write-atomic.mk
index f099ae285f..ce6acd8b7c 100644
--- a/build-aux/Makefile.once.head/10-write-atomic.mk
+++ b/build-aux/Makefile.once.head/10-write-atomic.mk
@@ -1,4 +1,22 @@
 mod.write-atomic.description = `write-atomic` auxiliary build script
 mod.write-atomic.files += $(topsrcdir)/build-aux/write-atomic
+define mod.write-atomic.doc
+# User variables:
+#   - `WRITE_ATOMIC ?= $(topsrcdir)/build-aux/write-atomic`
+# Inputs:
+#   (none)
+# Outputs:
+#   (none)
+#
+# The $(WRITE_ATOMIC) program reads a file from stdin, and writes it to
+# the file named in argv[1], but does so atomically.
+#
+# That is, the following lines are almost equivalient:
+#
+#     ... > $@
+#     ... | $(WRITE_ATOMIC) $@
+#
+# The are only different in that one is atomic, while the other is not.
+endef
 
 WRITE_ATOMIC ?= $(topsrcdir)/build-aux/write-atomic
diff --git a/build-aux/Makefile.once.head/10-write-ifchanged.mk b/build-aux/Makefile.once.head/10-write-ifchanged.mk
index b0a5ac478f..5abb3cee76 100644
--- a/build-aux/Makefile.once.head/10-write-ifchanged.mk
+++ b/build-aux/Makefile.once.head/10-write-ifchanged.mk
@@ -1,4 +1,22 @@
 mod.write-ifchanged.description = `write-ifchanged` auxiliary build script
 mod.write-ifchanged.files += $(topsrcdir)/build-aux/write-ifchanged
+define mod.write-ifchanged.doc
+# User variables:
+#   - `WRITE_IFCHANGED ?= $(topsrcdir)/build-aux/write-ifchanged`
+# Inputs:
+#   (none)
+# Outputs:
+#   (none)
+#
+# The $(WRITE_IFCHANGED) program reads a file from stdin, and writes it to the
+# file named in argv[1], but does so atomically, but more importantly, does so
+# in a way that does not bump the file's ctime if the new content is the same
+# as the old content.
+#
+# That is, the following lines are almost equivalient:
+#
+#     ... > $@
+#     ... | $(WRITE_ATOMIC) $@
+endef
 
 WRITE_IFCHANGED ?= $(topsrcdir)/build-aux/write-ifchanged
diff --git a/build-aux/Makefile.once.head/zz-mod.mk b/build-aux/Makefile.once.head/zz-mod.mk
index 732f1e169d..1b12a2fd33 100644
--- a/build-aux/Makefile.once.head/zz-mod.mk
+++ b/build-aux/Makefile.once.head/zz-mod.mk
@@ -15,6 +15,28 @@
 
 mod.mod.description = Display information about Autothing modules
 mod.mod.depends += quote
+define mod.mod.doc
+# Inputs:
+#   - Files           : `$(topsrcdir)/build-aux/Makefile.*/??-*.mk`
+#   - Global variable : `mod.*.name`
+#   - Global variable : `mod.*.description`
+#   - Global variable : `mod.*.depends`
+#   - Global variable : `mod.*.files`
+#   - Global variable : `mod.*.doc`
+# Outputs:
+#   - Directory variable : `at.targets`
+#   - .PHONY Target      : `$(outdir)/at-variables-local`
+#   - .PHONY Target      : `$(outdir)/at-variables-global`
+#   - .PHONY Target      : `$(outdir)/at-variables`
+#   - .PHONY Target      : `$(outdir)/at-variables/%`
+#   - .PHONY Target      : `$(outdir)/at-values`
+#   - .PHONY Target      : `$(outdir)/at-values/%`
+#   - .PHONY Target      : `$(outdir)/at-modules`
+#   - .PHONY Target      : `$(outdir)/at-modules/%`
+#   - .PHONY Target      : `$(outdir)/at-noop`
+#
+# TODO: prose documentation
+endef
 
 # The trickery that is _mod.empty/_mod.space is from §6.2 of the GNU Make
 # manual, "The Two Flavors of Variables".