Re: [PATCH 2/5] New FAQ node: Debugging.

[Ralf Wildenhues]

* Eric Blake wrote on Wed, Sep 16, 2009 at 06:13:35AM CEST:
> According to Jim Meyering on 9/13/2009 1:36 PM:
> > Ralf Wildenhues wrote:
> > ...
> >> address@hidden Debugging
> >> address@hidden Debugging @command{configure} scripts
> > 
> > Nice tips!
> > I've proposed an addition to one of your lists
> > and made a few very subjective style suggestions:
> 
> The ideas are nice, and I agree with Jim's feedback.  Once it's touched
> up, I'd like to see it go in.

Committed with this squashed in.  (git reflog is great even if you only
use it for 'rebase -i'ing a patch series and then, after you're done
amending patches, writing diff emails with 'git diff address@hidden 
address@hidden').

Thanks for the reviews,
Ralf

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 6053578..51bdef7 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -23958,12 +23958,12 @@ Debugging
 While in general, @command{configure} scripts generated by Autoconf
 strive to be fairly portable to various systems, compilers, shells, and
 other tools, it may still be necessary to debug a failing test, broken
-script or makefile, or fix or override an incomplete or wrong test,
-especially during macro development.  Failures can occur on all levels,
+script or makefile, or fix or override an incomplete, faulty, or erroneous
+test, especially during macro development.  Failures can occur at all levels,
 in M4 syntax or semantics, shell script issues, or due to bugs in the
 test or the tools invoked by @command{configure}.  Together with the
-rather arcane error message which @command{m4} and @command{make} may
-produce when their input has syntax errors, this can make debugging
+rather arcane error message that @command{m4} and @command{make} may
+produce when their input contains syntax errors, this can make debugging
 rather painful.
 
 Nevertheless, here is a list of hints and strategies that may help:
@@ -24002,8 +24002,8 @@ Debugging
 @var{log-file}.
 
 @item
-When @command{configure} tests produce wrong or insufficient results for
-your system, it may be necessary to override them:
+When @command{configure} tests produce invalid results for your system,
+it may be necessary to override them:
 
 @itemize
 @item
@@ -24023,7 +24023,7 @@ Debugging
 
 @item
 Many tests store their result in a cache variable (@pxref{Caching
-Results}).  This allows to override them either on the
+Results}).  This lets you override them either on the
 @command{configure} command line as above, or through a primed cache or
 site file (@pxref{Cache Files}, @pxref{Site Defaults}).  The name of a
 cache variable is documented with a test macro or may be inferred from
@@ -24047,7 +24047,12 @@ Debugging
 @item
 by honoring the @acronym{GNU} Coding Standards and not overriding flags
 reserved for the user except temporarily during @command{configure}
-tests.
+tests,
+
address@hidden
+by not requiring users of your macro to use the cache variables.
+Instead, expose the result of the test via @var{run-if-true} and
address@hidden parameters.
 @end itemize