doc: user flags last does not always allow overriding.

This change addresses https://bugs.gnu.org/35526.

* doc/automake.texi (Flag Variables Ordering): recognize that
user flags last does not always allow overriding.

1 files changed, 17 insertions, 12 deletions

diff --git a/doc/automake.texi b/doc/automake.texi
index 68b015151..c8501aaaf 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -12480,8 +12480,8 @@ and this flag would be propagated to the compile rules of all
 
 It is also not uncommon to override a user variable at
 @command{make}-time.  Many installers do this with @code{prefix}, but
-this can be useful with compiler flags too.  For instance, if, while
-debugging a C++ project, you need to disable optimization in one
+this can be useful with compiler flags too.  For instance, while
+debugging a C++ project, if you need to disable optimization in one
 specific object file, you can run something like
 
 @example
@@ -12491,16 +12491,21 @@ make
 @end example
 
 The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
-@samp{$(mumble_CPPFLAGS)} in the compile command is that users
-should always have the last say.  It probably makes more sense if you
-think about it while looking at the @samp{CXXFLAGS=-O0} above, which
-should supersede any other switch from @code{AM_CXXFLAGS} or
-@code{mumble_CXXFLAGS} (and this of course replaces the previous value
-of @code{CXXFLAGS}).
-
-You should never redefine a user variable such as @code{CPPFLAGS} in
-@file{Makefile.am}.  Use @samp{automake -Woverride} to diagnose such
-mistakes.  Even something like
+@samp{$(mumble_CPPFLAGS)} in the compile command is that users should
+have the last say.  In the example above, the desire is for the
+@samp{CXXFLAGS=-O0} to supersede any other switch from
+@code{AM_CXXFLAGS} or @code{mumble_CXXFLAGS}.
+
+@c https://bugs.gnu.org/35526
+It's true that not all options to all programs can be overridden.  So
+in general, users could conceivably want to place options at arbitrary
+places in the command line, but Automake does not support this.  It
+would be difficult to make such generality comprehensible.  Being able
+to specify the final options commonly suffices.
+
+Thus, you should never redefine a user variable such as
+@code{CPPFLAGS} in @file{Makefile.am}.  Use @samp{automake -Woverride}
+to diagnose such mistakes.  Even something like
 
 @example
 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@