Incorporate rmustacc's review feedback.

@@ -8,16 +8,36 @@
 # source.  A copy of the CDDL is also available via the Internet at
 # http://www.illumos.org/license/CDDL.
 #
 
 #
-# Copyright 2014 Garrett D'Amore <garrett@damore.org>
+# Copyright 2015 Garrett D'Amore <garrett@damore.org>
 #
 
 #
 # Compilation environments.
 #
+# Each compilation environment is declared using the keyword "env", like
+# this:
+#
+# env | <name> | <std> | <defs>
+#
+# <name> is just a symbolic name for environment.
+# <std>  indicates either c89 or c99, i.e. which C standard to compile
+#        under.  This infuences choice of compiler and switches.
+# <defs> is a list of CPP style -D or -U flags to define C preprocessor
+#        symbols.
+#
+# Groups of compilation environments can be named, using the "env_group"
+# keyword (this can also be used to create aliases):
+#
+# env_group | <name> | <envs>
+#
+# <name> is a name for the group or alias
+# <envs> is a whitespace separated list of previously declared environments
+#        or environment groups (or aliases).
+#
 
 env | XPG3              | c89 | -D_XOPEN_SOURCE
 env | XPG4              | c89 | -D_XOPEN_SOURCE -D_XOPEN_VERSION=4
 env | SUSv1             | c89 | -D_XOPEN_SOURCE -D_XOPEN_SOURCE_EXTENDED=1
 env | SUSv2             | c89 | -D_XOPEN_SOURCE=500