Re: Patch: couple of doc updates

[Alexandre Duret-Lutz]

| 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.

I'm committing this patch.  With all the FIXMEs.

I'm still hoping for comments about these:

|@@ -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
[...]
|@@ -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
[...]
|@@ -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
[...]
|@@ -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
[...]
|@@ -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 @@
[...]
|@@ -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.
[...]
| 
| @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
-- 
Alexandre Duret-Lutz