More doc fixes

diff --git a/TODO b/TODO
index d18e09b..1cccfe3 100644 (file)
--- a/TODO
+++ b/TODO
@@ -308,18 +308,10 @@ autosystem...
 
 Document:
 
-go through handle_configure and make sure each macro is documented in
-the appropriate place.  Clean up ordering in document.  Add info about
-AM_ macros.
-
-should write more complete explanation of implicit copying semantics
-
 finish yacc, lex
 
 Document customary ordering of Makefile.am.  From François.
 
-must document that @ALLOCA@ works in _LDADD
-
 Should include extended version of diagram from Autoconf (suggested by
 Greg Woods)
 
@@ -342,16 +334,6 @@ This is insufficiently clear
 must document the targets required for integration with
 non-automake-using subdirs
 
-document actual uses of PACKAGE and VERSION
-
-Must document aclocal program
-
-document *not* putting config.h into _SOURCES
-
-document variable scanning: $() and ${} interpolation
-
-mention libit when talking about LIBOBJS
-
 ================================================================
 
 Libraries:

diff --git a/automake.texi b/automake.texi
index d7cd63b..41bc58a 100644 (file)
--- a/automake.texi
+++ b/automake.texi
@@ -105,7 +105,7 @@ documents version @value{VERSION}.
 * Top level::                   The top-level Makefile.am
 * Programs::                    Building programs and libraries
 * Other objects::               Other derived objects
-* Emacs Lisp::                  Emacs Lisp support
+* Other GNU Tools::             Other GNU Tools
 * Documentation::               Building documentation
 * Install::                     What gets installed
 * Clean::                       What gets cleaned
@@ -263,9 +263,20 @@ works.
 
 @node General Operation
 @section General Operation
+
 Automake essentially works by reading a @file{Makefile.am} and
-generating a @file{Makefile.in}.  The macro definitions and targets in
-the @file{Makefile.am} are copied into the generated file.
+generating a @file{Makefile.in}.
+
+The macro definitions and targets in the @file{Makefile.am} are copied
+into the generated file.  This allows you to add essentially arbitrary
+code into the generated @file{Makefile.in}.  For instance the Automake
+distribution includes a non-standard @code{cvs-dist} target, which the
+Automake maintainer uses to make distributions from his source control
+system.
+
+Note that GNU make extensions are not recognized by Automake.  Using
+such extensions in a @file{Makefile.am} will lead to errors or confusing
+behavior.
 
 Automake tries to group comments with adjoining targets (or variable
 definitions) in an intelligent way.
@@ -276,6 +287,18 @@ target of a similar name that would be automatically generated by
 best to avoid making use of it, as sometimes the generated rules are
 very particular.
 
+When examining a variable definition, Automake will recursively examine
+variables referenced in the definition.  Eg if Automake is looking at
+the content of @samp{foo_SOURCES} in this snippet
+
+@example
+xs = a.c b.c
+foo_SOURCES = c.c $(xs)
+@end example
+
+it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
+contents of @samp{foo_SOURCES}.
+
 Automake also allows a form of comment which is @emph{not} copied into
 the output; all lines beginning with @samp{##} are completely ignored by
 Automake.
@@ -641,9 +664,9 @@ This is required when using automatic de-ANSI-fication, see @ref{ANSI}.
 @cvindex AM_C_PROTOTYPES
 
 @item ud_GNU_GETTEXT
-This macro is required for packages which use GNU gettext (FIXME xref).
-It is distributed with gettext.  Automake uses this macro to ensure that
-the package meets some of gettext's requirements.
+This macro is required for packages which use GNU gettext
+(@pxref{gettext}).  It is distributed with gettext.  Automake uses this
+macro to ensure that the package meets some of gettext's requirements.
 @cvindex ud_GNU_GETTEXT
 
 @item AM_MAINTAINER_MODE
@@ -769,6 +792,7 @@ to build C programs and libraries.
 @menu
 * A Program::                   Building a program
 * A Library::                   Building a library
+* LIBOBJS::                     Special handling for LIBOBJS and ALLOCA
 * Program variables::           Variables used when building a program
 * Yacc and Lex::                Yacc and Lex support
 * C++::                         C++ and other languages
@@ -814,7 +838,9 @@ can share a single source file.  The source file must be listed in each
 @samp{_SOURCES} definition.
 
 Header files listed in a @samp{_SOURCES} definition will be included in
-the distribution but otherwise ignored.
+the distribution but otherwise ignored.  In case it isn't obvious, you
+should not include the header file generated by @file{configure} in an
+@samp{_SOURCES} variable; this file should not be distributed.
 Lex (@samp{.l}) and yacc (@samp{.y}) files can also be listed; support
 for these should work but is still preliminary.
 @c lex & yacc should have a separate section
@@ -870,6 +896,12 @@ target which is not actually part of that program.  This can be done
 using the @samp{prog_DEPENDENCIES} variable.  Each program depends on
 the contents of such a variable, but no further interpretation is done.
 
+If @samp{prog_DEPENDENCIES} is not supplied, it is computed by Automake.
+The automatically-assigned value is the contents of @samp{prog_LDADD}
+with all the @samp{-l} and @samp{-L} options removed.  Be warned that
+@file{configure} substitutions are preserved; this can lead to bad
+dependencies if you are not careful.
+
 
 @node A Library
 @section Building a library
@@ -901,12 +933,19 @@ variable.  This should be used for objects determined by
 cpio_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
 @end example
 
-Note that Automake explicitly recognizes the use of @code{@@LIBOBJS@@}
-and @code{@@ALLOCA@@} in the above example, and uses this information,
-plus the list of @code{LIBOBJS} files derived from @file{configure.in}
-to automatically include the appropriate source files in the
-distribution (@pxref{Dist}).  These source files are also automatically
-handled in the dependency-tracking scheme, see @xref{Dependencies}.
+
+@node LIBOBJS
+@section Special handling for LIBOBJS and ALLOCA
+
+Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
+@code{@@ALLOCA@@}, and uses this information, plus the list of
+@code{LIBOBJS} files derived from @file{configure.in} to automatically
+include the appropriate source files in the distribution (@pxref{Dist}).
+These source files are also automatically handled in the
+dependency-tracking scheme, see @xref{Dependencies}.
+
+@code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
+@samp{_LDADD} or @samp{_LIBADD} variable.
 
 
 @node Program variables
@@ -1147,8 +1186,20 @@ dependency tracking is done.  Built sources are included in a
 distribution.
 
 
+@node Other GNU Tools
+@chapter Other GNU Tools
+
+Since Automake is primarily intended to generate @file{Makefile.in}s for
+use in GNU programs, it tries hard to interoperatoe with other GNU
+tools.
+
+@menu
+* Emacs Lisp::                  Emacs Lisp
+* gettext::                     Gettext
+@end menu
+
 @node Emacs Lisp
-@chapter Emacs Lisp
+@section Emacs Lisp
 
 Automake provides some support for Emacs Lisp.  The @samp{LISP} primary
 is used to hold a list of @samp{.el} files.  Possible prefixes for this
@@ -1164,6 +1215,23 @@ the Emacs found by @code{AM_PATH_LISPDIR}.  If you wish to avoid
 byte-compiling, simply define the variable @samp{ELCFILES} to be empty.
 @vindex ELCFILES
 
+@node gettext
+@section Gettext
+
+If @code{ud_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
+turns on support for GNU gettext, a message catalog system for
+internationalization
+(@pxref{GNU Gettext, , , gettext.info, GNU gettext utilities}).
+
+The @code{gettext} support in Automake requires the addition of two
+subdirectories to the package, @file{intl} and @file{po}.  Automake
+ensure that these directories exist and are mentioned in @code{SUBDIRS}.
+
+Furthermore, Automake checks that the definition of @samp{ALL_LINGUAS}
+in @file{configure.in} corresponds to all the valid @samp{.po} files,
+and nothing more.
+
+
 @node Documentation
 @chapter Building documentation
 
@@ -1304,7 +1372,8 @@ be defined to specify additional files to clean.  These variables are
 
 The @code{dist} target in the generated @file{Makefile.in} can be used
 to generate a gzip'd @code{tar} file for distribution.  The tar file is
-named based on the @var{PACKAGE} and @var{VERSION} variables.
+named based on the @var{PACKAGE} and @var{VERSION} variables; more
+precisely it is named @samp{@var{PACKAGE}-@var{VERSION}.tar.gz}.
 @cvindex PACKAGE
 @cvindex VERSION
 @trindex dist