Incorporate rmustacc's review feedback.

*** 8,23 ****
  # 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>
  #
  
  #
  # Compilation environments.
  #
  
  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
--- 8,43 ----
  # source.  A copy of the CDDL is also available via the Internet at
  # http://www.illumos.org/license/CDDL.
  #
  
  #
! # 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