+# DESIGN:
+#
+# - To each generated file bar corresponds a "genfile" bar.g that contains some
+# information about how bar was generated, including the command (for rebuild on
+# command change) and the warnings (for replay).
+#
+# - bar.g's mtime is the last time Mage verified that bar was up to date. bar
+# needs to be regenerated iff a prerequisite is newer than *bar.g* (not bar).
+# If a prerequisite changes but the command gives the same contents for bar,
+# bar.g is touched but bar itself is not touched because files that depend on it
+# need not be regenerated.
+#
+# - If bar is newer than bar.g, the user has overridden it, and we should leave
+# the override in place but warn the user about it.
+#
+# - The user's Makefile defines Mage rules by calling mg-define-rule. Each Mage
+# rule becomes one underlying make rule with the same target and a little extra
+# magic. This is important so that all implicit rule competition takes place at
+# the same target. Additionally, the prerequisites are passed to an obfuscated
+# target for bar.g to see if any are newer than bar.g. This is done by the
+# single obfuscated implicit rule, keeping the number of implicit rules low.
+# Then the command script for bar checks for overrides, command change,
+# prerequisite change, etc. and acts accordingly.
+#
+# Target metadata variables for bar: (* means stored in bar.g)
+#
+# bar@cmd:=cat foo >bar.tmp
+# Generation command as given to the shell.*
+#
+# bar@warnings:=$(empty)yikes!
+# Data that the command printed to stdout or stderr, presumably warnings.*
+#
+# bar@deps:=included@x oops@
+# If dependency-logging, list of filename@revision used. Revision is x for
+# exists and empty for doesn't exist. Later perhaps x will be the mtime.*
+#
+# bar@gloaded:=1
+# Set if Mage has loaded bar.g and hasn't changed it since then.
+#
+# bar@gdeps:=foo
+# Static dependencies of bar, for checking by bar.g.
+#
+# bar@gq:=foo $(mg-scout-oid)$(aname)bar
+# $? from the rule for bar.g; used by the rule for bar.
+#
+# bar@checked:=1
+# Set when Mage determines that a file is up to date or depends on it being
+# so determined. Used to decide which prerequisite to check next for a
+# dependency-logging command.
+#
+# bar@dlc-ran:=1
+# Indicates that Mage is in the middle of building bar using a dependency-
+# logging command. Means that bar.g.tmp, not bar.g, is the most current
+# genfile.
+#
+## If the rule for bar is overridden, we clear the information from bar.g so
+## that it is as if bar.g didn't exist. -- Not currently needed
+#
+# Some make features with which Mage's compatibility has not been investigated:
+# - Command-line options (especially --dry-run, --question, --touch,
+# --always-make, --keep-going, --jobs, --assume-old, and --assume-new)
+# - Static pattern rules
+# - Vpath