Revise documentation for AC_PROG_LEX.

 - Better explanation of the additional tests performed by this macro,
   once the tool has been located.

 - Update advice re using Flex to generate a bundled lex.yy.c.

 - Remove text describing a bug in Automake that has long since been
   corrected.

3 files changed, 46 insertions, 38 deletions

diff --git a/NEWS b/NEWS
index dd3b2896..438f074b 100644
--- a/NEWS
+++ b/NEWS
@@ -104,9 +104,12 @@ GNU Autoconf NEWS - User visible changes.
 - AC_PROG_CC_STDC, AC_PROG_CC_C89, AC_PROG_CC_C99 have been marked as obsolete.
   Applications should use AC_PROG_CC.
 
-- AC_PROG_LEX no longer sets LEXLIB to be nonempty merely to define
-  the yywrap function.  Packages should define yywrap themselves, or
-  use %noyywrap.
+- AC_PROG_LEX no longer looks for a library providing the function
+  ‘yywrap’.  LEXLIB will only be set to ‘-lfl’ or ‘-ll’ if a
+  scanner that defines both ‘main’ and ‘yywrap’ itself still needs
+  something else from that library.
+
+  Packages should define yywrap themselves, or use %noyywrap.
 
 - AC_USE_SYSTEM_EXTENSIONS now enables more extensions on HP-UX,
   macOS, and MINIX, as well as on systems conforming to recent
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index b8f889cc..b7b9e4a5 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -4179,33 +4179,49 @@ The result of the test can be overridden by setting the variable
 @caindex prog_LEX
 If @code{flex} is found, set output variable @code{LEX} to @samp{flex}.
 Otherwise set @code{LEX} to @samp{lex}, if found.
-If neither variant is available, set @code{LEX}
-to @samp{:}; for packages that ship the generated @file{file.yy.c}
+If neither variant is available, set @code{LEX} to @samp{:};
+for packages that ship the generated @file{file.yy.c}
 alongside the source @file{file.l}, this default allows users without a
 lexer generator to still build the package even if the timestamp for
 @file{file.l} is inadvertently changed.
 
-If generated lexers need a library to work, set output variable
-@code{LEXLIB} to an option for that library (e.g., @option{-ll});
-otherwise define @code{LEXLIB} to empty.  A library that merely defines
-@code{main} and @code{yywrap} placeholder functions is not considered
-to be needed.
-
-Define @code{YYTEXT_POINTER} if @code{yytext} defaults to @samp{char *} instead
-of to @samp{char []}.  Also set output variable @code{LEX_OUTPUT_ROOT} to
-the base of the file name that the lexer generates; usually
-@file{lex.yy}, but sometimes something else.  These results vary
-according to whether @code{lex} or @code{flex} is being used.
-
-You are encouraged to use Flex in your sources, since it is both more
-pleasant to use than plain Lex and the C source it produces is portable.
-In order to ensure portability, however, you must either provide a
-function @code{yywrap} or, if you don't use it (e.g., your scanner has
-no @samp{#include}-like feature), simply include a @samp{%noyywrap}
-statement in the scanner's source.  Once this done, the scanner is
-portable (unless @emph{you} felt free to use nonportable constructs) and
-does not depend on any library.  In this case, and in this case only, it
-is suggested that you use this Autoconf snippet:
+The result of this test can be influenced by setting the variable
+@code{LEX} or the cache variable @code{ac_cv_prog_LEX}.
+
+If either @code{flex} or @code{lex} is found, this macro performs
+additional checks for common portability pitfalls.  If these additional
+checks fail, @code{LEX} is also set to @samp{:}.
+
+Output variable @code{LEX_OUTPUT_ROOT} is set to the base of the file
+name that the lexer generates; this is usually either @file{lex.yy} or
+@file{lexyy}.  Preprocessor macro @code{YYTEXT_POINTER} is defined if
+the lexer skeleton, by default, declares @code{yytext} as a @samp{char
+*} rather than a @samp{char []}.  Finally, if generated lexers need a
+library to work, set output variable @code{LEXLIB} to an option for that
+library (e.g., @option{-ll}); otherwise define @code{LEXLIB} to empty.
+A library that merely defines @code{main} and @code{yywrap} placeholder
+functions is not considered to be needed.
+
+@strong{Caution:} As a side-effect of the test, this macro may delete
+any file in the configure script's current working directory named
+@file{lex.yy.c} or @file{lexyy.c}.
+
+@strong{Caution:} Packages that ship a generated @file{lex.yy.c}
+cannot assume that the definition of @code{YYTEXT_POINTER} matches
+the code in that file.  They also cannot assume that @code{LEXLIB}
+provides the library routines required by the code in that file.
+
+If you use Flex to generate @file{lex.yy.c}, you can work around these
+limitations by defining @code{yywrap} and @code{main} yourself
+(rendering @code{-lfl} unnecessary), and by using either the
+@option{--array} or @option{--pointer} options to control how
+@code{yytext} is declared.  The code generated by Flex is also more
+portable than the code generated by historical versions of Lex.
+
+If you have used Flex to generate @file{lex.yy.c}, and especially if
+your scanner depends on Flex features, we recommend you use this
+Autoconf snippet to prevent the scanner being regenerated with
+historical Lex:
 
 @example
 AC_PROG_LEX
@@ -4223,17 +4239,6 @@ Remember that the user may have supplied an alternate location in
 @env{LEX}, so if Flex is required, it is better to check that the user
 provided something sufficient by parsing the output of @samp{$LEX
 --version} than by simply relying on @code{test "x$LEX" = xflex}.
-
-To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
-(indirectly) this macro twice, which causes an annoying but benign
-``@code{AC_PROG_LEX} invoked multiple times'' warning.  Future versions
-of Automake will fix this issue; meanwhile, just ignore this message.
-
-As part of running the test, this macro may delete any file in the
-configuration directory named @file{lex.yy.c} or @file{lexyy.c}.
-
-The result of this test can be influenced by setting the variable
-@code{LEX} or the cache variable @code{ac_cv_prog_LEX}.
 @end defmac
 
 @anchor{AC_PROG_LN_S}
diff --git a/lib/autoconf/programs.m4 b/lib/autoconf/programs.m4
index 6fd44a3b..087c913a 100644
--- a/lib/autoconf/programs.m4
+++ b/lib/autoconf/programs.m4
@@ -742,7 +742,7 @@ yywrap (void)
 int
 main (void)
 {
-  return ! yylex () + ! yywrap ();
+  return ! yylex ();
 }
 ]_ACEOF
 AC_CACHE_CHECK([for lex output file root], [ac_cv_prog_lex_root], [