diff -r 3a6b9e3809f7 -r 34cc580c62c2 doc/makefile-variables.txt
--- a/doc/makefile-variables.txt	Mon Nov 16 06:14:40 2015 -0800
+++ b/doc/makefile-variables.txt	Mon Nov 23 15:33:43 2015 -0800
@@ -94,7 +94,8 @@
   yielding the wrong results.
 * COMPONENT_BUILD_ENV is for when you just need to override things in the
   calling environment, like PATH.
-* COMPONENT_INSTALL_ARGS is mainly used for altering target directories.
+* COMPONENT_INSTALL_ARGS is mainly used for altering target directories;
+  there are also COMPONENT_INSTALL_ARGS.$(BITS) versions.
 * COMPONENT_INSTALL_ENV is mainly used for altering target directories.
 * COMPONENT_PUBLISH_ENV is so far only used to work around Python issues when
   used by "pkgdepend generate", though the variable may be extended in the
@@ -126,13 +127,37 @@
 * COMPONENT_PREP_ACTION is used to make alterations to the unpacked and patched
   source.  It should be used with care.
 
+For components that have a configure target, the following macros are used to
+control the options and arguments passed:
+
+* If BITS is set before shared-macros.mk is included, the default directories
+  used for various configure options as documented below will change.  For
+  example:
+
+  if BITS=64 explicitly:
+  	32-bit binaries -> $(CONFIGURE_PREFIX)/bin/$(MACH32)
+	32-bit libraries -> $(CONFIGURE_PREFIX)/lib
+  	64-bit binaries -> $(CONFIGURE_PREFIX)/bin
+	64-bit libraries -> $(CONFIGURE_PREFIX)/lib/$(MACH64)
+
+  if BITS=32 explicitly or BITS is unspecified:
+  	32-bit binaries -> $(CONFIGURE_PREFIX)/bin
+	32-bit libraries -> $(CONFIGURE_PREFIX)/lib
+  	64-bit binaries -> $(CONFIGURE_PREFIX)/bin/$(MACH64)
+	64-bit libraries -> $(CONFIGURE_PREFIX)/lib/$(MACH64)
+* CC_FOR_BUILD is included in CONFIGURE_ENV by default to ensure that 32-bit
+  and 64-bit host detection works as expected for autoconf-based components by
+  specifying the exact compiler and relevant $(CC_BITS) for the current build.
+  It can be set to "" to omit it from CONFIGURE_ENV.
+* CONFIGURE_CPPFLAGS contains the default set of CPPFLAGS to be included in
+  CONFIGURE_ENV.  It can be set to "" to omit it from CONFIGURE_ENV.
 * CONFIGURE_DEFAULT_DIRS should be "yes" or "no".  A value of "yes" (the
   default) will trigger the following being passed to CONFIGURE_OPTIONS as
   parameters to corresponding options.
-  * CONFIGURE_BINDIR is the value for the --bindir= option.
-  * CONFIGURE_LIBDIR is the value for the --libdir= option.
-  * CONFIGURE_MANDIR is the value for the --mandir= option.
-  * CONFIGURE_SBINDIR is the value for the --sbindir= option.
+  * CONFIGURE_BINDIR.$(BITS) is the value for the --bindir= option.
+  * CONFIGURE_LIBDIR.$(BITS) is the value for the --libdir= option.
+  * CONFIGURE_MANDIR.$(BITS) is the value for the --mandir= option.
+  * CONFIGURE_SBINDIR.$(BITS) is the value for the --sbindir= option.
 * CONFIGURE_ENV is mainly used for passing CFLAGS and other common Makefile
   variables to configure.  When should this be used as opposed to
   CONFIGURE_OPTIONS and COMPONENT_BUILD_{ARGS,ENV}?  In general, you want
@@ -151,10 +176,36 @@
 * CONFIGURE_SCRIPT should be set if the default "$(SOURCE_DIR)/configure" is
   unsuitable for whatever reason.
 
+To override or otherwise modify the default compilation flags used for
+components, the following macros are provided:
+
+* CFLAGS by default contains the preferred set of compilation flags for most
+  components, which usually includes optimization flags, language mode,
+  alignment flags, and multi-threading flags for the current COMPILER.
+  CFLAGS.$(COMPILER) and CFLAGS.$(COMPILERS).$(BITS) versions are also
+  available for specifying additional flags or overriding the default.
+* CXXFLAGS by default contains the preferred set of compilation flags for most
+  C++ components, which usually includes optimization flags, language mode,
+  alignment flags, and multi-threading flags for the current COMPILER.
+  CXXFLAGS.$(COMPILER) and CXXFLAGS.$(COMPILERS).$(BITS) versions are also
+  available for specifying additional flags or overriding the default.
+* gcc_OPT has a default value of "-O3".  Bugs in the optimizer have been found
+  which have required altering this to "-O2".
 * studio_OPT has a default value of "-xO4".  Occasional bugs in the optimizer
-  have been found which have required altering this to "-xO3".  There are also
-  studio_OPT.$(MACH).$(BITS) versions of this available if greater specificity
-  is needed.
+  have been found which have required altering this to "-xO3".
+* There are also gcc_OPT.$(MACH).$(BITS) and studio_OPT.$(MACH).$(BITS)
+  versions of the above available if greater specificity is needed.
+
+For components that use pkg-config, the following macros are provided:
+
+* PKG_CONFIG_PATH contains the default system paths to use when looking for
+  pkg-config configuration files.  To specify additional paths to be searched,
+  use PKG_CONFIG_PATHS as follows:
+
+  PKG_CONFIG_PATHS += /path/to/pc/files
+
+Finally, for control of packaging-related operations and values used during
+publication, the following macros are available:
 
 * TPNO is the Third Party number (i.e., a numeric value): the License
   Technology from the Product Lifecycle Suite tool.  This should be used