[automake-commit] branch master updated: doc: tweak Yacc/Lex text; subnode for the yacc linking hack.

[Karl Berry]

This is an automated email from the git hooks/post-receive script.

karl pushed a commit to branch master
in repository automake.

View the commit online:
https://git.savannah.gnu.org/gitweb/?p=automake.git;a=commitdiff;h=80ad99a6a90632d74a6f75136309956ffaddc732

The following commit(s) were added to refs/heads/master by this push:
     new 80ad99a  doc: tweak Yacc/Lex text; subnode for the yacc linking hack.
80ad99a is described below

commit 80ad99a6a90632d74a6f75136309956ffaddc732
Author: Karl Berry <karl@freefriends.org>
AuthorDate: Tue Sep 28 14:59:22 2021 -0700

    doc: tweak Yacc/Lex text; subnode for the yacc linking hack.
    
    * doc/automake.texi (Alternative): remove obsolete footnote.
    (Yacc and Lex): tweak wording, more consistent capitalization.
    (Linking Multiple Yacc Parsers): new subsection.
    
    Also add @shortcontents.
    Also update texinfo-master-menu (for the first time in ages).
---
 doc/automake.texi | 126 ++++++++++++++++++++++++++++++------------------------
 1 file changed, 71 insertions(+), 55 deletions(-)

diff --git a/doc/automake.texi b/doc/automake.texi
index 59bc2f8..37c8580 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -62,6 +62,7 @@ section entitled ``GNU Free Documentation License.''
 @insertcopying
 @end titlepage
 
+@shortcontents
 @contents
 
 @c We use the following macros to define indices:
@@ -192,6 +193,7 @@ Auto-generating aclocal.m4
 Autoconf macros supplied with Automake
 
 * Public Macros::               Macros that you can use.
+* Obsolete Macros::             Macros that will soon be removed.
 * Private Macros::              Macros that you should not use.
 
 Directories
@@ -256,6 +258,10 @@ Common Issues Related to Libtool's Use
 * Error required file ltmain.sh not found::  The need to run libtoolize
 * Objects created both with libtool and without::  Avoid a specific build race
 
+Yacc and Lex support
+
+* Linking Multiple Yacc Parsers::
+
 Fortran 77 Support
 
 * Preprocessing Fortran 77::    Preprocessing Fortran 77 sources
@@ -312,7 +318,7 @@ What Goes in a Distribution
 
 Support for test suites
 
-* Generalities about Testing::  Generic concepts and terminology about testing
+* Generalities about Testing::  Concepts and terminology about testing
 * Simple Tests::                Listing test scripts in @code{TESTS}
 * Custom Test Drivers::         Writing and using custom test drivers
 * Using the TAP test protocol:: Integrating test scripts that use the TAP 
protocol
@@ -325,13 +331,6 @@ Simple Tests
 * Serial Test Harness::         Older (and discouraged) serial test harness
 * Parallel Test Harness::       Generic concurrent test harness
 
-Using the TAP test protocol
-
-* Introduction to TAP::
-* Use TAP with the Automake test harness::
-* Incompatibilities with other TAP parsers and drivers::
-* Links and external resources on TAP::
-
 Custom Test Drivers
 
 * Overview of Custom Test Drivers Support::
@@ -344,6 +343,13 @@ API for Custom Test Drivers
 * Log files generation and test results recording::
 * Testsuite progress output::
 
+Using the TAP test protocol
+
+* Introduction to TAP::
+* Use TAP with the Automake test harness::
+* Incompatibilities with other TAP parsers and drivers::
+* Links and external resources on TAP::
+
 Changing Automake's Behavior
 
 * Options generalities::        Semantics of Automake option
@@ -359,7 +365,7 @@ Conditionals
 * Usage of Conditionals::       Declaring conditional content
 * Limits of Conditionals::      Enclosing complete statements
 
-Silencing Make
+Silencing @command{make}
 
 * Make verbosity::              Make is verbose by default
 * Tricks For Silencing Make::   Standard and generic ways to silence make
@@ -4599,11 +4605,10 @@ recursion will probably come as unwelcome advice.  For 
those who
 haven't read the paper, Miller's main thesis is that recursive
 @command{make} invocations are both slow and error-prone.
 
-Automake provides sufficient cross-directory support @footnote{We
-believe.  This work is new and there are probably warts.
-@xref{Introduction}, for information on reporting bugs.} to enable you
-to write a single @file{Makefile.am} for a complex multi-directory
-package.
+Automake is intended to have sufficient cross-directory support to
+enable you to write a single @file{Makefile.am} for a complex
+multi-directory package.  (If it seems to be lacking, please report
+the issue as usual.)
 
 By default an installable file specified in a subdirectory will have its
 directory name stripped before installation.  For instance, in this
@@ -6293,14 +6298,14 @@ variable.
 Automake has somewhat idiosyncratic support for Yacc and Lex.
 
 Automake assumes that the @file{.c} file generated by @command{yacc}
-(or @command{lex}) should be named using the basename of the input
-file.  That is, for a yacc source file @file{foo.y}, Automake will
+or @command{lex} should be named using the basename of the input
+file.  That is, for a Yacc source file @file{foo.y}, Automake will
 cause the intermediate file to be named @file{foo.c} (as opposed to
 @file{y.tab.c}, which is more traditional).
 
-The extension of a yacc source file is used to determine the extension
-of the resulting C or C++ source and header files.  Note that header
-files are generated only when the @option{-d} Yacc option is used; see
+The extension of a Yacc source file is used to determine the extension
+of the resulting C or C++ source and header files.  Be aware that header
+files are generated only when the option @option{-d} is given to Yacc; see
 below for more information about this flag, and how to specify it.
 Files with the extension @file{.y} will thus be turned into @file{.c}
 sources and @file{.h} headers; likewise, @file{.yy} will become
@@ -6308,7 +6313,7 @@ sources and @file{.h} headers; likewise, @file{.yy} will 
become
 @file{h++}, @file{.yxx} will become @file{.cxx} and @file{.hxx},
 and @file{.ypp} will become @file{.cpp} and @file{.hpp}.
 
-Similarly, lex source files can be used to generate C or C++; the
+Similarly, Lex source files can be used to generate C or C++; the
 extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
 @file{.lpp} are recognized.
 
@@ -6319,10 +6324,10 @@ The intermediate files generated by @command{yacc} (or 
@command{lex})
 will be included in any distribution that is made.  That way the user
 doesn't need to have @command{yacc} or @command{lex}.
 
-If a @command{yacc} source file is seen, then your @file{configure.ac} must
+If a Yacc source file is seen, then your @file{configure.ac} must
 define the variable @code{YACC}.  This is most easily done by invoking
-the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
-Program Checks, autoconf, The Autoconf Manual}).
+the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, ,
+Particular Program Checks, autoconf, The Autoconf Manual}).
 
 @vindex YFLAGS
 @vindex AM_YFLAGS
@@ -6333,17 +6338,18 @@ intended for the @file{Makefile.am} author.
 @code{AM_YFLAGS} is usually used to pass the @option{-d} option to
 @command{yacc}.  Automake knows what this means and will automatically
 adjust its rules to update and distribute the header file built by
-@samp{yacc -d}@footnote{Please note that @command{automake} recognizes
-@option{-d} in @code{AM_YFLAGS} only if it is not clustered with other
-options; for example, it won't be recognized if @code{AM_YFLAGS} is
-@option{-dt}, but it will be if @code{AM_YFLAGS} is @option{-d -t} or
-@option{-t -d}.}.
-What Automake cannot guess, though, is where this
-header will be used: it is up to you to ensure the header gets built
-before it is first used.  Typically this is necessary in order for
-dependency tracking to work when the header is included by another
-file.  The common solution is listing the header file in
-@code{BUILT_SOURCES} (@pxref{Sources}) as follows.
+@samp{yacc -d}.  Caveat: @command{automake} recognizes @option{-d} in
+@code{AM_YFLAGS} only if it is not clustered with other options; for
+example, it won't be recognized if @code{AM_YFLAGS} is @option{-dt},
+but it will be if @code{AM_YFLAGS} is @option{-d -t} or @option{-t
+-d}.
+
+What Automake cannot guess, though, is where this header will be used:
+it is up to you to ensure the header gets built before it is first
+used.  Typically this is necessary in order for dependency tracking to
+work when the header is included by another file.  The common solution
+is listing the header file in @code{BUILT_SOURCES} (@pxref{Sources})
+as follows.
 
 @example
 BUILT_SOURCES = parser.h
@@ -6352,11 +6358,11 @@ bin_PROGRAMS = foo
 foo_SOURCES = @dots{} parser.y @dots{}
 @end example
 
-If a @command{lex} source file is seen, then your @file{configure.ac}
-must define the variable @code{LEX}.  You can use @code{AC_PROG_LEX}
-to do this (@pxref{Particular Programs, , Particular Program Checks,
-autoconf, The Autoconf Manual}), but using the @code{AM_PROG_LEX} macro
-(@pxref{Macros}) is recommended.
+If a Lex source file is seen, then your @file{configure.ac} must
+define the variable @code{LEX}.  You can use @code{AC_PROG_LEX} to do
+this (@pxref{Particular Programs, , Particular Program Checks,
+autoconf, The Autoconf Manual}), but using the @code{AM_PROG_LEX}
+macro (@pxref{Macros}) is recommended.
 
 @vindex LFLAGS
 @vindex AM_LFLAGS
@@ -6364,9 +6370,10 @@ When @command{lex} is invoked, it is passed 
@code{AM_LFLAGS} and
 @code{LFLAGS}.  The latter is a user variable and the former is
 intended for the @file{Makefile.am} author.
 
-When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
-rebuild rule for distributed Yacc and Lex sources are only used when
-@code{maintainer-mode} is enabled, or when the files have been erased.
+When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is in effect,
+the rebuild rules for distributed Yacc and Lex sources are only used
+when @code{maintainer-mode} is enabled, or when the files have been
+erased.
 
 @cindex @command{ylwrap}
 @cindex @command{yacc}, multiple parsers
@@ -6374,19 +6381,28 @@ rebuild rule for distributed Yacc and Lex sources are 
only used when
 @cindex Multiple @command{lex} lexers
 @cindex @command{lex}, multiple lexers
 
-When @command{lex} or @command{yacc} sources are used, @code{automake -a}
-automatically installs an auxiliary program called @command{ylwrap} in
-your package (@pxref{Auxiliary Programs}).
-This program is used by the build rules to rename the output of these
-tools, and makes it possible to include multiple @command{yacc} (or
-@command{lex}) source files in a single directory.  (This is necessary
-because yacc's output file name is fixed, and a parallel make could
-conceivably invoke more than one instance of @command{yacc}
-simultaneously.)
-
-For @command{yacc}, simply managing locking is insufficient.  The output of
-@command{yacc} always uses the same symbol names internally, so it isn't
-possible to link two @command{yacc} parsers into the same executable.
+When Yacc or Lex sources are used, @code{automake -a} automatically
+installs an auxiliary program called @command{ylwrap} in your package
+(@pxref{Auxiliary Programs}).  This program is used by the build rules
+to rename the output of these tools, and makes it possible to include
+multiple @command{yacc} (or @command{lex}) source files in a single
+directory.  This is necessary because Yacc's output file name is
+fixed, and a parallel make could invoke more than one instance of
+@command{yacc} simultaneously.
+
+@menu
+* Linking Multiple Yacc Parsers::
+@end menu
+
+@subsection Linking Multiple Yacc Parsers
+@node Linking Multiple Yacc Parsers
+
+@cindex Linking multiple @command{yacc} parsers
+
+For @command{yacc}, simply managing locking as with @code{ylwrap} is
+insufficient.  The output of @command{yacc} always uses the same
+symbol names internally, so it isn't possible to link two
+@command{yacc} parsers into the same executable.
 
 We recommend using the following renaming hack used in @command{gdb}:
 @example