Patch: couple of doc updates

[Alexandre Duret-Lutz]

Hi,

Here are some documentation updates.  I've introduced a few FIXME:s
at places I'd like to see improved but for which I need comments.
(Comments about the rest of the changes are welcome too, of course.)

I've also discovered that Automake would tell users to move
linker flags from LDADD to LDFLAGS although the latter is a user
variable.  I've included a fix for this too.

2002-02-09  Alexandre Duret-Lutz  <address@hidden>

        * automake.in (handle_lib_objects_cond): Tell the user to put
        global linker flags in AM_LDFLAGS, not LDFLAGS.

        * automake.texi (General Operation): AC_SUBST'ed variables
        override Automake's variables.
        (Uniform): More words and @refs.
        (Auxiliary Programs) <config.sub, config.guess>: Add URL.
        (etags): More explanations about the first example.
        (Invoking Automake): Mention autoreconf.  More @refs.
        (Requirements): Mention AC_CONFIG_FILES.
        (Optional): AC_CHECK_TOOL will no longer install config.sub and
        config.guess.  Mention AC_LIBOBJ, AC_LIBSOURCE, and AC_LIBSOURCES.
        (Invoking aclocal): aclocal no longer warn about duplicates.
        (Macros) <AM_INIT_AUTOMAKE>: More explanations.
        (Extending aclocal): Suggest using the output of
        `aclocal --print-ac-dir` to install third-party macros.
        (Alternative): Specify ordering of dist_, nodist_, and nobase_
        prefixes.
        (A Program): Mention scripts.  The global LDADD variable is not
        meant to hold link flags, suggest using AM_LDFLAGS instead.
        (Program and Library Variables) <maude_LIBADD, maude_LDADD>:
        _LIBADD and _LDADD are subject to the same restriction wrt to
        link flags.
        (Program and Library Variables) <maude_DEPENDECIES>: Is also
        derived from maude_LIBADD.
        (Program variables): Define AM_LDFLAGS.
        (Dependencies): Passing the no-dependencies option to
        AM_INIT_AUTOMAKE is prefered.
        (Scripts): Explain why automake is magically cleaned.
        Mention noinst_SCRIPTS and check_SCRIPTS.
        (Data): Use dist_ in Automake's example.
        (Dist): Reference AM_INIT_AUTOMAKE for PACKAGE and VERSION.
        Mention AC_CONFIG_FILES instead of AC_OUTPUT.

Index: NEWS
===================================================================
RCS file: /cvs/automake/automake/NEWS,v
retrieving revision 1.171
diff -u -r1.171 NEWS
--- NEWS        2002/01/28 01:09:29     1.171
+++ NEWS        2002/02/09 15:13:22
@@ -20,8 +20,9 @@
 * Fixed support of implicit rules leading to .lo objects.
 * Fixed late inclusion of --add-missing files (e.g. depcomp) in DIST_COMMON
 * Added uninstall-hook target
-* `AC_INIT AM_INIT_AUTOMAKE(package,version)' is an obsolete construct.
-  You can now use `AC_INIT(package,version) AM_INIT_AUTOMAKE' instead.
+* `AC_INIT AM_INIT_AUTOMAKE(tarname,version)' is an obsolete construct.
+  You can now use `AC_INIT(pkgname,version) AM_INIT_AUTOMAKE' instead.
+  (Note that "pkgname" is not "tarname", see the manual for details.)
   It is also possible to pass a list of global Automake options as
   first argument to this new form of AM_INIT_AUTOMAKE.
 * Compiler-based assembler is now called `CCAS'; people expected `AS'
Index: automake.in
===================================================================
RCS file: /cvs/automake/automake/automake.in,v
retrieving revision 1.1276
diff -u -r1.1276 automake.in
--- automake.in 2002/02/01 20:40:48     1.1276
+++ automake.in 2002/02/09 15:13:45
@@ -2394,11 +2394,13 @@
            {
                # Skip -dlopen and -dlpreopen; these are explicitly allowed.
                next if $lsearch =~ /^-dl(pre)?open$/;
+               my $prefix = $1 || 'AM_';
                macro_error ($var,
-                            "linker flags such as `$lsearch' belong in 
`${1}LDFLAGS");
+                            "linker flags such as `$lsearch' belong in 
`${prefix}LDFLAGS");
            }
            else
            {
+               $var =~ /^(.*)LIBADD$/;
                # Only get this error once.
                $flagvar = 1;
                macro_error ($var,
Index: automake.texi
===================================================================
RCS file: /cvs/automake/automake/automake.texi,v
retrieving revision 1.264
diff -u -r1.264 automake.texi
--- automake.texi       2002/02/02 07:18:47     1.264
+++ automake.texi       2002/02/09 15:14:01
@@ -234,6 +234,7 @@
 
 Automake tries to group comments with adjoining targets and macro
 definitions in an intelligent way.
address@hidden FIXME: What does this imply practically?
 
 @cindex Make targets, overriding
 @cindex Overriding make targets
@@ -247,12 +248,12 @@
 @cindex Macros, overriding
 @cindex Overriding make macros
 
-Similarly, a macro defined in @file{Makefile.am} will override any
-definition of the macro that @code{automake} would ordinarily create.
-This feature is more often useful than the ability to override a target
-definition.  Be warned that many of the macros generated by
address@hidden are considered to be for internal use only, and their
-names might change in future releases.
+Similarly, a macro defined in @file{Makefile.am} or @code{AC_SUBST}'ed
+from @file{configure.in} will override any definition of the macro that
address@hidden would ordinarily create.  This feature is more often
+useful than the ability to override a target definition.  Be warned that
+many of the macros generated by @code{automake} are considered to be for
+internal use only, and their names might change in future releases.
 
 @cindex Recursive operation of Automake
 @cindex Automake, recursive operation
@@ -306,7 +307,7 @@
 @cindex Strictness, foreign
 @cindex foreign strictness
 @cindex Strictness, gnu
address@hidden gnits strictness
address@hidden gnu strictness
 @cindex Strictness, gnits
 @cindex gnits strictness
 
@@ -360,7 +361,6 @@
 @cindex _PROGRAMS primary variable
 @cindex PROGRAMS primary variable
 @cindex Primary variable, PROGRAMS
-
 @cindex Primary variable, defined
 
 At @code{make} time, certain variables are used to determine which
@@ -389,7 +389,7 @@
 and @code{pkgdatadir}; these are the same as the address@hidden
 versions, but with @samp{@@PACKAGE@@} appended.  For instance,
 @code{pkglibdir} is defined as @code{$(libdir)/@@PACKAGE@@}.
address@hidden PACKAGE
address@hidden PACKAGE, directory
 
 @cindex EXTRA_, prepending
 
@@ -422,8 +422,13 @@
 @samp{bindir_PROGRAMS}.
 
 Not every sort of object can be installed in every directory.  Automake
-will flag those attempts it finds in error.  Automake will also diagnose
-obvious misspellings in directory names.
+will flag those attempts it finds in error.
address@hidden FIXME: This is broken today: &am_primary_prefix will allow 
data_PROGRAMS
address@hidden because $datadir is defined before Makefile.am is parsed.  This
address@hidden means that passing the list of allowed directory suffix to
address@hidden &am_install_var or &am_primary_prefix is absolutely useless 
(except
address@hidden for 'noinst', 'check' and friends).
+Automake will also diagnose obvious misspellings in directory names.
 
 @cindex Extending list of installation directories
 @cindex Installation directories, extending list
@@ -448,12 +453,15 @@
 @cindex noinst primary prefix, definition
 
 The special prefix @samp{noinst} indicates that the objects in question
-should not be installed at all.
+should be built but not installed at all.  This is usually used for
+objects required to build the rest of your package, for instance static
+libraries (@pxref{A Library}), or helper scripts.
 
 @cindex check primary prefix, definition
 
 The special prefix @samp{check} indicates that the objects in question
-should not be built until the @code{make check} command is run.
+should not be built until the @code{make check} command is run.  Those
+objects are not installed either.
 
 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
 @samp{LISP}, @samp{PYTHON}, @samp{JAVA}, @samp{SCRIPTS}, @samp{DATA},
@@ -472,7 +480,7 @@
 Some primaries also allow additional prefixes which control other
 aspects of @code{automake}'s behavior.  The currently defined prefixes
 are @samp{dist_}, @samp{nodist_}, and @samp{nobase_}.  These prefixes
-are explained later.
+are explained later (@pxref{Program and Library Variables}).
 
 
 @node Canonicalization, User Variables, Uniform, Generalities
@@ -516,6 +524,8 @@
 compilation of the package.  Since these variables are documented as
 being for the package builder, that person rightfully expects to be able
 to override any of these variables at build time.
address@hidden FIXME: maybe Automake could bark if a developer forces a user 
variable
address@hidden from Makefile.am.
 
 To get around this problem, automake introduces an automake-specific
 shadow variable for each user flag variable.  (Shadow variables are not
@@ -549,7 +559,10 @@
 @item config.guess
 @itemx config.sub
 These programs compute the canonical triplets for the given build, host,
-or target architecture.
+or target architecture.  These programs are updated regulary to support
+new architectures and fix probes broken by changes in new kernel
+versions.  You are encouraged to fetch the latest versions of these
+files from @url{ftp://ftp.gnu.org/gnu/config/} before making a release.
 
 @item depcomp
 This program understands how to run a compiler so that it will generate
@@ -634,7 +647,7 @@
 Now you must regenerate @file{configure}.  But to do that, you'll need
 to tell @code{autoconf} how to find the new macro you've used.  The
 easiest way to do this is to use the @code{aclocal} program to generate
-your @file{aclocal.m4} for you.  But wait... you already have an
+your @file{aclocal.m4} for you.  But wait... maybe you already have an
 @file{aclocal.m4}, because you had to write some hairy macros for your
 program.  The @code{aclocal} program lets you put your own macros into
 @file{acinclude.m4}, so simply rename and then run:
@@ -649,10 +662,10 @@
 
 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
 Since @code{zardoz} is a user program, you want to install it where the
-rest of the user programs go.  Additionally, @code{zardoz} has some
-Texinfo documentation.  Your @file{configure.in} script uses
address@hidden, so you need to link against @samp{@@LIBOBJS@@}.
-So here's what you'd write:
+rest of the user programs go: @code{bindir}.  Additionally,
address@hidden has some Texinfo documentation.  Your @file{configure.in}
+script uses @code{AC_REPLACE_FUNCS}, so you need to link against
address@hidden@@LIBOBJS@@}.  So here's what you'd write:
 
 @example
 bin_PROGRAMS = zardoz
@@ -768,6 +781,8 @@
 @cindex INCLUDES, example usage
 
 Last we have @file{src/Makefile.am}, where all the real work is done:
address@hidden FIXME: As all the Hello World excerpts in this manual, this
address@hidden shows deprecated features (here: $(INCLUDES)).
 
 @example
 bin_PROGRAMS = hello
@@ -802,13 +817,20 @@
         $(COMPILE) -DCTAGS -o ctags.o -c etags.c
 @end example
 
-Note that @code{ctags_SOURCES} is defined to be empty---that way no
-implicit value is substituted.  The implicit value, however, is used to
-generate @code{etags} from @file{etags.o}.
+Note that there is no @code{etags_SOURCES} definition.  Automake will
+implicitly assume that there is a source file named @file{etags.c}, and
+define rules to compile @file{etags.o} and link @file{etags}.  The
address@hidden: etags.c} rule supplied by the above @file{Makefile.am},
+will override the Automake generated rule to build @file{etags.o}.
+
address@hidden is defined to be empty---that way no implicit value
+is substituted.  Because we have not listed the source of
address@hidden, we have to tell Automake how to link the program.  This is
+the purpose of the @code{ctags_LDADD} line.  A @code{ctags_DEPENDENCIES}
+variable, holding the dependencies of the @file{ctags} target will be
+automatically generated by Automake from the contant of
address@hidden
 
address@hidden is used to get @file{ctags.o} into the link line.
address@hidden is generated by Automake.
-
 The above rules won't work if your compiler doesn't accept both
 @samp{-c} and @samp{-o}.  The simplest fix for this is to introduce a
 bogus dependency (to avoid problems with a parallel @code{make}):
@@ -872,7 +894,9 @@
 package; it assumes that a package has only one @file{configure.in}, at
 the top.  If your package has multiple @file{configure.in}s, then you
 must run @code{automake} in each directory holding a
address@hidden
address@hidden  (Alteratively, you may rely on Autoconf's
address@hidden, which is able to recurse your package tree and run
address@hidden where appropriate.)
 
 You can optionally give @code{automake} an argument; @file{.am} is
 appended to the argument and the result is used as the name of the input
@@ -886,6 +910,7 @@
 
 @cindex Automake options
 @cindex Options, Automake
address@hidden Strictness, command line
 
 @code{automake} accepts the following options:
 
@@ -901,11 +926,11 @@
 Automake requires certain common files to exist in certain situations;
 for instance @file{config.guess} is required if @file{configure.in} runs
 @code{AC_CANONICAL_HOST}.  Automake is distributed with several of these
-files; this option will cause the missing ones to be automatically added
-to the package, whenever possible.  In general if Automake tells you a
-file is missing, try using this option.  By default Automake tries to
-make a symbolic link pointing to its own copy of the missing file; this
-can be changed with @code{--copy}.
+files (@pxref{Auxiliary Programs}); this option will cause the missing
+ones to be automatically added to the package, whenever possible.  In
+general if Automake tells you a file is missing, try using this option.
+By default Automake tries to make a symbolic link pointing to its own
+copy of the missing file; this can be changed with @code{--copy}.
 
 @item address@hidden
 @opindex --libdir
@@ -928,7 +953,7 @@
 @opindex -f
 @itemx --force-missing
 @opindex --force-missing
-When used with @code{--add-missing}, causes standard files to be rebuilt
+When used with @code{--add-missing}, causes standard files to be reinstalled
 even if they already exist in the source tree.  This involves removing
 the file from the source tree before creating the new symlink (or, with
 @code{--copy}, copying the new file).
@@ -955,7 +980,8 @@
 @item -i
 @itemx --ignore-deps
 @opindex -i
-This disables the dependency tracking feature; see @ref{Dependencies}.
+This disables the dependency tracking feature in generated
address@hidden; see @ref{Dependencies}.
 
 @item --include-deps
 @opindex --include-deps
@@ -974,6 +1000,7 @@
 @itemx address@hidden
 @opindex -o
 @opindex --output-dir
address@hidden FIXME: This seems to be a left-over from Automake 1.4, unused 
today.
 Put the generated @file{Makefile.in} in the directory @var{dir}.
 Ordinarily each @file{Makefile.in} is created in the directory of the
 corresponding @file{Makefile.am}.  This option is used when making
@@ -1034,7 +1061,7 @@
 
 The one real requirement of Automake is that your @file{configure.in}
 call @code{AM_INIT_AUTOMAKE}.  This macro does several things which are
-required for proper Automake operation.
+required for proper Automake operation (@pxref{Macros}).
 @cvindex AM_INIT_AUTOMAKE
 
 Here are the other macros which Automake requires but which are not run
@@ -1043,13 +1070,18 @@
 @cindex AC_OUTPUT, scanning
 
 @table @code
address@hidden AC_OUTPUT
-Automake uses this to determine which files to create (@pxref{Output, ,
-Creating Output Files, autoconf, The Autoconf Manual}).  Listed files
-named @code{Makefile} are treated as @file{Makefile}s.  Other listed
-files are treated differently.  Currently the only difference is that a
address@hidden is removed by @code{make distclean}, while other files
-are removed by @code{make clean}.
address@hidden AC_CONFIG_FILES
address@hidden AC_OUTPUT
+Automake uses these to determine which files to create (@pxref{Output, ,
+Creating Output Files, autoconf, The Autoconf Manual}).  A listed file
+is considered to be an Automake generated @file{Makefile} if there
+exists a file with the same name and the @file{.am} extension appended.
+Typically, @code{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
+generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
+
+Other listed files are treated differently.  Currently the only
+difference is that an Automake @file{Makefile} is removed by @code{make
+distclean}, while other files are removed by @code{make clean}.
 @c FIXME: this is in violation of standards!
 @cvindex AC_OUTPUT
 @end table
@@ -1067,10 +1099,10 @@
 
 @table @code
 @item AC_CONFIG_HEADER
-Automake requires the use of @code{AM_CONFIG_HEADER}, which is similar
-to @code{AC_CONFIG_HEADER} (@pxref{Configuration Headers, ,
-Configuration Header Files, autoconf, The Autoconf Manual}), but does
-some useful Automake-specific work.
+Automake requires the use of @code{AM_CONFIG_HEADER} (@pxref{Macros}),
+which is similar to @code{AC_CONFIG_HEADER} (@pxref{Configuration
+Headers, , Configuration Header Files, autoconf, The Autoconf Manual}),
+but does some useful Automake-specific work.
 @cvindex AC_CONFIG_HEADER
 
 @item AC_CONFIG_AUX_DIR
@@ -1092,16 +1124,11 @@
 @cvindex AC_PATH_XTRA
 
 @item AC_CANONICAL_HOST
address@hidden AC_CHECK_TOOL
 Automake will ensure that @file{config.guess} and @file{config.sub}
 exist.  Also, the @file{Makefile} variables @samp{host_alias} and
address@hidden are introduced.  See both @ref{Canonicalizing, ,
-Getting the Canonical System Type, autoconf, The Autoconf Manual}, and
address@hidden Programs, , Generic Program Checks, autoconf, The Autoconf
-Manual}.
address@hidden fixme xref autoconf docs.
address@hidden are introduced.  See @ref{Canonicalizing, ,
+Getting the Canonical System Type, autoconf, The Autoconf Manual}.
 @cvindex AC_CANONICAL_HOST
address@hidden AC_CHECK_TOOL
 @vindex host_alias
 @vindex host_triplet
 
@@ -1146,11 +1173,24 @@
 @cvindex AC_STRUCT_ST_BLOCKS
 @cvindex AM_WITH_REGEX
 
address@hidden LIBOBJS
address@hidden AC_LIBOBJ
address@hidden LIBOBJS
address@hidden AC_LIBSOURCE
address@hidden AC_LIBSOURCES
 Automake will detect statements which put @file{.o} files into
address@hidden, and will treat these additional files as if they were
-discovered via @code{AC_REPLACE_FUNCS}.  @xref{Generic Functions, ,
-Generic Function Checks, autoconf, The Autoconf Manual}.
address@hidden, or pass @file{.o} files to @code{AC_LIBOBJ}, and will
+treat these additional files as if they were discovered via
address@hidden  Similarly, Automake will also distribute file
+listed in @code{AC_LIBSOURCE} and @code{AC_LIBSOURCES}.
+
+Note that assignments to @code{LIBOBJS} is a construct which is being
+phased out; they will be ignored in a future release of Automake.  You
+should call the @code{AC_LIBOBJ} macro instead.  @xref{Generic
+Functions, , Generic Function Checks, autoconf, The Autoconf Manual}.
+
address@hidden AC_LIBOBJ
address@hidden AC_LIBSOURCE
address@hidden AC_LIBSOURCES
 @cvindex LIBOBJS
 
 @item AC_PROG_RANLIB
@@ -1251,8 +1291,8 @@
 The @code{aclocal} program will automatically generate @file{aclocal.m4}
 files based on the contents of @file{configure.in}.  This provides a
 convenient way to get Automake-provided macros, without having to
-search around.  Also, the @code{aclocal} mechanism is extensible for use
-by other packages.
+search around.  Also, the @code{aclocal} mechanism allows other packages
+to supply their own macros.
 
 At startup, @code{aclocal} scans all the @file{.m4} files it can find,
 looking for macro definitions.  Then it scans @file{configure.in}.  Any
@@ -1264,7 +1304,7 @@
 incorporating local macros into @file{configure}.
 
 @code{aclocal} tries to be smart about looking for new @code{AC_DEFUN}s
-in the files it scans.  It will warn if it finds duplicates.  It also
+in the files it scans.  It also
 tries to copy the full text of the scanned file into @file{aclocal.m4},
 including both @samp{#} and @samp{dnl} comments.  If you want to make a
 comment which will be completely ignored by @code{aclocal}, use
@@ -1294,9 +1334,9 @@
 @item --print-ac-dir
 @opindex --print-ac-dir
 Prints the name of the directory which @code{aclocal} will search to
-find the @file{.m4} files.  When this option is given, normal processing
-is suppressed.  This option can be used by a package to determine where
-to install a macro file.
+find third-party @file{.m4} files.  When this option is given, normal
+processing is suppressed.  This option can be used by a package to
+determine where to install a macro file.
 
 @item --verbose
 @opindex --verbose
@@ -1331,6 +1371,7 @@
 @itemx AM_SET_DEPDIR
 @itemx AM_DEP_TRACK
 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
address@hidden FIXME: Consider not documenting these internal macros.
 These macros are used to implement automake's automatic dependency
 tracking scheme.  They are called automatically by automake when
 required, and there should be no need to invoke them manually.
@@ -1351,12 +1392,14 @@
 
 @item AM_INIT_AUTOMAKE([OPTIONS])
 @itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
-Runs many macros that most @file{configure.in}'s need.  This macro has
-two forms, the second of which has two required arguments: the package
-and the version number.  This latter form is obsolete because the
address@hidden and @var{version} are now arguments of the @samp{AC_INIT}
-Autoconf macro, and Automake can get this information from there.
+Runs many macros required for proper operation of the generated Makefiles.
 
+This macro has two forms, the second of which has two required
+arguments: the package and the version number.  This latter form is
+obsolete because the @var{package} and @var{version} can be obtained
+from Autoconf's @code{AC_INIT} macro (which itself has an old and a new
+form).
+
 If your @file{configure.in} has:
 @example
 AC_INIT(src/foo.c)
@@ -1369,10 +1412,22 @@
 AM_INIT_AUTOMAKE
 @end example
 
-If this macro is called with a single argument, it is interpreted as a
-space-separated list of Automake options which should be applied to
-every @file{Makefile.am} in the tree.  The effect is as if each option
-were listed in @code{AUTOMAKE_OPTIONS}.
+Note that if you're upgrading your @file{configure.in} from an earlier
+version of Automake, it is not always correct to simply move the package
+and version arguments from @code{AM_INIT_AUTOMAKE} directly to
address@hidden, as in the example above.  The first argument of
address@hidden is the name of your package (e.g. @samp{GNU Automake}),
+not the tarball name (e.g. @samp{automake}) you used to pass to
address@hidden  Autoconf's rule to derive a tarball name from
+the package name should work for most but not all packages.  Especially,
+if your tarball name is not all lower case, you will have to use the
+four-argument form of @code{AC_INIT} (supported in Autoconf versions
+greater than 2.52g).
+
+When @code{AM_INIT_AUTOMAKE} is called with a single argument, it is
+interpreted as a space-separated list of Automake options which should
+be applied to every @file{Makefile.am} in the tree.  The effect is as if
+each option were listed in @code{AUTOMAKE_OPTIONS}.
 
 By default this macro @code{AC_DEFINE}'s @samp{PACKAGE} and
 @samp{VERSION}.  This can be avoided by passing the @samp{no-define}
@@ -1385,14 +1440,9 @@
 @cvindex PACKAGE, prevent definition
 @cvindex VERSION, prevent definition
 
-Note that if you're upgrading your @file{configure.in} from an earlier
-version of Automake, it is not always correct to simply move the package
-and version arguments from @code{AM_INIT_AUTOMAKE} directly to
address@hidden  If your package name is not all lower case, you will
-have to use the four-argument form of @code{AC_INIT}.
-
 
 @item AM_MAKE_INCLUDE
address@hidden FIXME: Consider not documenting this internal macro.
 This macro is used to discover how the user's @code{make} handles
 @code{include} statements.  This macro is automatically invoked when
 needed; there should be no need to invoke it manually.
@@ -1444,6 +1494,7 @@
 automatically included when required.
 
 @item AM_SANITY_CHECK
address@hidden FIXME: Consider not documenting this internal macro.
 This checks to make sure that a file created in the build directory is
 newer than a file in the source directory.  This can fail on systems
 where the clock is set incorrectly.  This macro is automatically run
@@ -1503,7 +1554,8 @@
 autoconf, The Autoconf Manual}.
 
 A macro file's name should end in @file{.m4}.  Such files should be
-installed in @file{$(datadir)/aclocal}.
+installed in @code{`aclocal --print-ac-dir`} (which usually happens to
+be @file{$(datadir)/aclocal}).
 
 
 @node Top level, Alternative, configure, Top
@@ -1633,6 +1685,16 @@
 nobase_include_HEADERS = sys/types.h
 @end example
 
address@hidden nobase_ and dist_ or nodist_
address@hidden dist_ and nobase_
address@hidden nodist_ and nobase_
+
address@hidden should be specified first when used in conjonction with
+either @samp{dist_} or @samp{nodist_} (@pxref{Dist}).  For instance:
+
address@hidden
+nobase_dist_pkgdata_DATA = images/vortex.pgm
address@hidden example
 
 @node Rebuilding, Programs, Alternative, Top
 @chapter Rebuilding Makefiles
@@ -1689,12 +1751,14 @@
 @vindex libexec_PROGRAMS
 @vindex pkglib_PROGRAMS
 @vindex noinst_PROGRAMS
address@hidden check_PROGRAMS
 
 In a directory containing source that gets built into a program (as
-opposed to a library), the @samp{PROGRAMS} primary is used.  Programs
-can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir},
address@hidden, or not at all (@samp{noinst}).  They can also be built
-only for @code{make check}, in which case the prefix is @samp{check}.
+opposed to a library or a script), the @samp{PROGRAMS} primary is used.
+Programs can be installed in @code{bindir}, @code{sbindir},
address@hidden, @code{pkglibdir}, or not at all (@samp{noinst}).
+They can also be built only for @code{make check}, in which case the
+prefix is @samp{check}.
 
 For instance:
 
@@ -1806,9 +1870,12 @@
 @subsection Linking the program
 
 If you need to link against libraries that are not found by
address@hidden, you can use @code{LDADD} to do so.  This variable
-actually can be used to add any options to the linker command line.
address@hidden, you can use @code{LDADD} to do so.  This variable is
+used to specify additional objects or libraries to link with; it is
+inappropriate for specifying specific linker flags, you should use
address@hidden for this purpose.
 @vindex LDADD
address@hidden AM_LDFLAGS
 
 @cindex prog_LDADD, defined
 
@@ -2083,9 +2150,10 @@
 them in the @samp{_LDADD} variable.  This should be used for objects
 determined by @code{configure}.
 
address@hidden is inappropriate for passing program-specific linker flags
-(except for @samp{-l}, @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen}).
-Use the @samp{_LDFLAGS} variable for this purpose.
address@hidden and @samp{_LIBADD} are inappropriate for passing
+program-specific linker flags (except for @samp{-l}, @samp{-L},
address@hidden and @samp{-dlpreopen}).  Use the @samp{_LDFLAGS} variable
+for this purpose.
 
 For instance, if your @file{configure.in} uses @code{AC_PATH_XTRA}, you
 could link your program against the X libraries like so:
@@ -2143,12 +2211,12 @@
 contents of such a variable, but no further interpretation is done.
 
 If @samp{_DEPENDENCIES} is not supplied, it is computed by Automake.
-The automatically-assigned value is the contents of @samp{_LDADD}, with
-most configure substitutions, @samp{-l}, @samp{-L}, @samp{-dlopen} and
address@hidden options removed.  The configure substitutions that are
-left in are only @samp{@@LIBOBJS@@} and @samp{@@ALLOCA@@}; these are
-left because it is known that they will not cause an invalid value for
address@hidden to be generated.
+The automatically-assigned value is the contents of @samp{_LDADD} or
address@hidden, with most configure substitutions, @samp{-l}, @samp{-L},
address@hidden and @samp{-dlpreopen} options removed.  The configure
+substitutions that are left in are only @samp{@@LIBOBJS@@} and
address@hidden@@ALLOCA@@}; these are left because it is known that they will not
+cause an invalid value for @samp{_DEPENDENCIES} to be generated.
 
 @item maude_SHORTNAME
 On some platforms the allowable file names are very short.  In order to
@@ -2190,7 +2258,12 @@
 Some variables are inherited from Autoconf; these are @code{CC},
 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
 @code{LIBS}.
address@hidden CC
address@hidden CFLAGS
address@hidden CPPFLAGS
address@hidden DEFS
 @vindex LDFLAGS
address@hidden LIBS
 
 There are some additional variables which Automake itself defines:
 
@@ -2215,12 +2288,17 @@
 This is the variable which the @file{Makefile.am} author can use to pass
 in additional C compiler flags.  It is more fully documented elsewhere.
 In some situations, this is not used, in preference to the
-per-executable (or per-library) @code{CFLAGS}.
+per-executable (or per-library) @code{_CFLAGS}.
 
 @item COMPILE
 This is the command used to actually compile a C source file.  The
 filename is appended to form the complete command line.
 
address@hidden AM_LDFLAGS
+This is the variable which the @file{Makefile.am} author can use to pass
+in additional linker flags.  In some situations, this is not used, in
+preference to the per-executable (or per-library) @code{_LDFLAGS}.
+
 @item LINK
 This is the command used to actually link a C program.  It already
 includes @samp{-o $@@} and the usual variable references (for instance,
@@ -2769,6 +2847,7 @@
 # the ANSI2KNR-filtering rules.
 LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
 @end example
address@hidden FIXME: Ask Akim how this should be handled in the upcoming 
Autoconf.
 
 Note that automatic de-ANSI-fication will not work when the package is
 being built for a different host architecture.  That is because automake
@@ -2807,9 +2886,10 @@
 much.  So instead Automake implements dependency tracking at build time.
 
 Automatic dependency tracking can be suppressed by putting
address@hidden in the variable @code{AUTOMAKE_OPTIONS}.  Or, you
-can invoke @code{automake} with the @code{-i} option.  Dependency
-tracking is enabled by default.
address@hidden in the variable @code{AUTOMAKE_OPTIONS}, or
+passing @code{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
+(this should be the prefered way).  Or, you can invoke @code{automake}
+with the @code{-i} option.  Dependency tracking is enabled by default.
 
 @vindex AUTOMAKE_OPTIONS
 @opindex no-dependencies
@@ -2834,8 +2914,9 @@
 generate @file{foo}.
 
 Automake provides mostly-transparent support for this.  Unfortunately
-the support isn't completely transparent; if you want your package to
-support these platforms then you must assist.
address@hidden doesn't yet mean @emph{fully}.  Until the English
+dictionary is revised, you will have to assist Automake if your package
+must support those platforms.
 
 One thing you must be aware of is that, internally, Automake rewrites
 something like this:
@@ -2920,7 +3001,8 @@
 @end example
 
 Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target
-for it is automatically generated.
+for it is automatically generated, and it is also automatically cleaned
+(despite the fact it's a script).
 
 @cindex SCRIPTS, installation directories
 @cindex Installing scripts
@@ -2930,11 +3012,16 @@
 @vindex libexec_SCRIPTS
 @vindex pkgdata_SCRIPTS
 @vindex noinst_SCRIPTS
address@hidden check_SCRIPTS
 
 Script objects can be installed in @code{bindir}, @code{sbindir},
 @code{libexecdir}, or @code{pkgdatadir}.
 
+Scripts that need not being installed can be listed in
address@hidden, and among them, those which are needed only by
address@hidden check} should go in @code{check_SCRIPTS}.
 
+
 @node Headers, Data, Scripts, Other objects
 @section Header files
 
@@ -2994,10 +3081,10 @@
 course, you can use the @samp{dist_} prefix to change this on a
 per-variable basis.
 
-Here is how Automake installs its auxiliary data files:
+Here is how Automake declares its auxiliary data files:
 
 @example
-pkgdata_DATA = clean-kr.am clean.am @dots{}
+dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
 @end example
 
 
@@ -3564,7 +3651,9 @@
 @cindex make clean support
 
 The GNU Makefile Standards specify a number of different clean rules.
address@hidden FIXME xref
+See @xref{Standard Targets, , Standard Targets for Users, standards,
+The GNU Coding Standards}.
+
 Generally the files that can be cleaned are determined automatically by
 Automake.  Of course, Automake also recognizes some variables that can
 be defined to specify additional files to clean.  These variables are
@@ -3610,8 +3699,9 @@
 The @code{dist} target in the generated @file{Makefile.in} can be used
 to generate a gzip'd @code{tar} file and other flavors of archive for
 distribution.  The files is named based on the @samp{PACKAGE} and
address@hidden variables; more precisely the gzip'd @code{tar} file is
-named @address@hidden@var{version}.tar.gz}.
address@hidden variables defined by @code{AM_INIT_AUTOMAKE}
+(@pxref{Macros}); more precisely the gzip'd @code{tar} file is named
address@hidden@address@hidden
 @cvindex PACKAGE
 @cvindex VERSION
 @trindex dist
@@ -3625,8 +3715,9 @@
 included if they are found in the current directory (either physically,
 or as the target of a @file{Makefile.am} rule).  This list is printed by
 @samp{automake --help}.  Also, files which are read by @code{configure}
-(i.e. the source files corresponding to the files specified in the
address@hidden invocation) are automatically distributed.
+(i.e. the source files corresponding to the files specified in various
+Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
+automatically distributed.
 
 Still, sometimes there are files which must be distributed, but which
 are not covered in the automatic rules.  These files should be listed in
-- 
Alexandre Duret-Lutz