gbuild: document what CFLAGS/CXXFLAGS etc. *actually* do

Looks like following GNU build system standards isn't necessarily the
best idea, if even the documentation gets it wrong.
Also document the ENVCFLAGS/ENVCFLAGSCXX variables.

see also: i#116959 and:
http://www.gnu.org/software/autoconf/manual/standards.html#Command-Variables

Change-Id: I56d8623cbbc800ef80da1610f6fd104ac29beaf9
(cherry picked from commit d3171eb7)

solenv/gbuild/gbuild.help.txt

@@ -108,14 +108,19 @@ INTERACTIVE VARIABLES:
        PARALLELISM     If not empty, pass argument on as the -j switch
                        to recursive make invocations. Useful to
                        lower/increase build parallelism individually.
-       LEXFLAGS        Add as flags for LEX scanner generator invocation.
-       YACCFLAGS       Add as flags for YACC parser generator invocation.
-       CPPFLAGS        Add as preprocessor flags for C/C++/ObjC/ObjC++ compilation.
-       CFLAGS          Add as compiler flags for plain C compilation.
-       CXXFLAGS        Add as compiler flags for C++ compilation.
-       OBJCFLAGS       Add as compiler flags for Objective C compilation.
-       OBJCXXFLAGS     Add as compiler flags for Objective C++ compilation.
-       LDFLAGS         Add as linker flags.
+       LEXFLAGS        Append flags for LEX scanner generator invocation.
+       YACCFLAGS       Append flags for YACC parser generator invocation.
+       CPPFLAGS        Append preprocessor flags for C/C++/ObjC/ObjC++ compilation.
+       CFLAGS          Override compiler flags for plain C compilation.
+       ENVCFLAGS       Append compiler flags for plain C compilation.
+       CXXFLAGS        Override compiler flags for C++ compilation.
+                       Note: this overrides default optimization and debug
+                       flags; to append flags without overriding, use:
+                       CXXFLAGS='$(call gb_LinkTarget__get_debugcxxflags,$(1)) -Wfoo'
+       ENVCFLAGSCXX    Append compiler flags for C++ compilation.
+       OBJCFLAGS       Override compiler flags for Objective C compilation.
+       OBJCXXFLAGS     Override compiler flags for Objective C++ compilation.
+       LDFLAGS         Override linker flags.
        gb_FULLDEPS     Generate and use dependencies (on by default, handle with care).
        gb_COLOR        Use ASCII color output.
        gb_TITLES       Show progress in terminal title.