Patch: manual updates

[Tom Tromey]

I'm checking this in.  It is more updates for the manual.

There is still a lot more to do, but at least it is moving along a
bit.

Tom

Index: ChangeLog
from  Tom Tromey  <address@hidden>
        * automake.texi (Program and Library Variables): Document
        subdir-objects.  Document fact that per-object flags override AM_
        flags.
        (Options): Likewise.
        (Yacc and Lex): Document YFLAGS, AM_YFLAGS, LFLAGS, AM_LFLAGS.
        (Multilibs): New node.
        (Macros): Documented missing macros.
        (Auxiliary Programs): New node.

Index: automake.texi
===================================================================
RCS file: /cvs/automake/automake/automake.texi,v
retrieving revision 1.217
diff -u -r1.217 automake.texi
--- automake.texi 2001/07/01 23:17:37 1.217
+++ automake.texi 2001/07/02 00:48:45
@@ -200,6 +200,7 @@
 * Uniform::                     The Uniform Naming Scheme
 * Canonicalization::            How derived variables are named
 * User Variables::             Variables reserved for the user
+* Auxiliary Programs::          Programs automake might require
 @end menu
 
 
@@ -482,7 +483,7 @@
 substitutions in macro names less obfuscating.
 
 
address@hidden User Variables, , Canonicalization, Generalities
address@hidden User Variables, Auxiliary Programs, Canonicalization, 
Generalities
 @section Variables reserved for the user
 
 @cindex variables, reserved for the user
@@ -510,7 +511,72 @@
 @code{YFLAGS} is @code{AM_YFLAGS}.
 
 
address@hidden Auxiliary Programs, , User Variables, Generalities
address@hidden Programs automake might require
 
address@hidden Programs, auxiliary
address@hidden Auxiliary programs
+
+Automake sometimes requires helper programs so that the generated
address@hidden can do its work properly.  There are a fairly large
+number of them, and we list them here.
+
address@hidden @code
address@hidden ansi2knr.c
address@hidden ansi2knr.1
+These two files are used by the automatic de-ANSI-fication support
+(@pxref{ANSI}).
+
address@hidden compile
+This is a wrapper for compilers which don't accept both @samp{-c} and
address@hidden at the same time.  It is only used when absolutely required.
+Such compilers are rare.
+
address@hidden config.guess
address@hidden config.sub
+These programs compute the canonical triplets for the given build, host,
+or target architecture.
+
address@hidden depcomp
+This program understands how to run a compiler so that it will generate
+not only the desired output but also dependency information which is
+then used by the automatic dependency tracking feature.
+
address@hidden elisp-comp
+This program is used to byte-compile Emacs Lisp code.
+
address@hidden install-sh
+This is a replacement for the @code{install} program which works on
+platforms where @code{install} is unavailable or unusable.
+
address@hidden mdate-sh
+This script is used to generate a @file{version.texi} file.  It examines
+a file and prints some date information about it.
+
address@hidden missing
+This wraps a number of programs which are typically only required by
+maintainers.  If the program in question doesn't exist, @code{missing}
+prints an informative warning and attempts to fix things so that the
+build can continue.
+
address@hidden mkinstalldirs
+This works around the fact that @code{mkdir -p} is not portable.
+
address@hidden py-compile
+This is used to byte-compile Python scripts.
+
address@hidden texinfo.tex
+Not a program, this file is required for @code{make dvi} to work when
+Texinfo sources are in the package.
+
address@hidden ylwrap
+This program wraps @code{lex} and @code{yacc} and ensures that, for
+instance, multiple @code{yacc} instances can be invoked in a single
+directory in parallel.
+
address@hidden table
+
+
 @node Examples, Invoking Automake, Generalities, Top
 @chapter Some example packages
 
@@ -1258,14 +1324,20 @@
 @cvindex AM_CONFIG_HEADER
 
 @item AM_ENABLE_MULTILIB
-This is used when a ``multilib'' library is being built.  A
address@hidden library is one that is built multiple times, once per
-target flag combination.  This is only useful when the library is
-intended to be cross-compiled.  The first optional argument is the name
-of the @file{Makefile} being generated; it defaults to @samp{Makefile}.
-The second option argument is used to find the top source directory; it
-defaults to the empty string (generally this should not be used unless
-you are familiar with the internals).
+This is used when a ``multilib'' library is being built.  The first
+optional argument is the name of the @file{Makefile} being generated; it
+defaults to @samp{Makefile}.  The second option argument is used to find
+the top source directory; it defaults to the empty string (generally
+this should not be used unless you are familiar with the internals).
address@hidden
+
address@hidden AM_DEPENDENCIES
address@hidden AM_SET_DEPDIR
address@hidden AM_DEP_TRACK
address@hidden AM_OUTPUT_DEPENDENCY_COMMANDS
+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_FUNC_STRTOD
 If the @code{strtod} function is not available, or does not work
@@ -1303,11 +1375,21 @@
 this macro @code{AC_DEFINE}'s @samp{PACKAGE} and @samp{VERSION}.  This
 can be avoided by passing in a non-empty third argument.
 
address@hidden AM_MAKE_INCLUDE
+This macro is used to discover how the user's @code{make} handles
address@hidden statements.  This macro is automatically invoked when
+needed; there should be no need to invoke it manually.
+
 @item AM_PATH_LISPDIR
 Searches for the program @code{emacs}, and, if found, sets the output
 variable @code{lispdir} to the full path to Emacs' site-lisp directory.
 @cvindex AM_PATH_LISPDIR
 
address@hidden AM_PROG_CC_C_O
+This is like @code{AC_PROG_CC_C_O}, but it generates its results in the
+manner required by automake.  You must use this instead of
address@hidden when you need this functionality.
+
 @item AM_PROG_CC_STDC
 If the C compiler in not in ANSI C mode by default, try to add an option
 to output variable @code{CC} to make it so.  This macro tries various
@@ -1343,6 +1425,11 @@
 GNU Compiler Collection.
 @cvindex AM_PROG_GCJ
 
address@hidden AM_PROG_INSTALL_STRIP
+This is used to find a version of @code{install} which can be used to
address@hidden a program at installation time.  This macro is
+automatically included when required.
+
 @item AM_SANITY_CHECK
 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
@@ -1837,6 +1924,17 @@
 dist_maude_SOURCES = dist-me.c
 @end example
 
+By default the output file (on Unix systems, the @file{.o} file) will be
+put into the current build directory.  However, if the option
address@hidden is in effect in the current directory then the
address@hidden file will be put into the subdirectory named after the source
+file.  For instance, with @code{subdir-objects} enabled,
address@hidden/dir/file.c} will be compiled to @file{sub/dir/file.o}.  Some
+people prefer this mode of operation.  You can specify
address@hidden in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
address@hidden Subdirectory, objects in
address@hidden Objects in subdirectory
+
 
 @item EXTRA_maude_SOURCES
 Automake needs to know the list of files you intend to compile
@@ -1899,6 +1997,17 @@
 However, if the program's @samp{_CFLAGS} variable is set, then the
 object file will be named, for instance, @file{maude-sample.o}.
 
+In compilations with per-program flags, the ordinary @samp{AM_} form of
+the flags variable is @emph{not} automatically included in the
+compilation (however, the user form of the variable @emph{is}
+included).  So for instance, if you want the hypothetical @file{maude}
+compilation to also use the value of @samp{AM_CFLAGS}, you would need to
+write:
+
address@hidden
+maude_CFLAGS = ... your flags ... $(AM_CFLAGS)
address@hidden example
+
 @item maude_DEPENDENCIES
 It is also occasionally useful to have a program depend on some other
 target which is not actually part of that program.  This can be done
@@ -2088,6 +2197,10 @@
 the macro @samp{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
 Program Checks, autoconf, The Autoconf Manual}).
 
+When @code{yacc} is invoked, it is passed @samp{YFLAGS} and
address@hidden  The former is a user variable and the latter is
+intended for the @file{Makefile.am} author.
+
 Similarly, if a @code{lex} source file is seen, then your
 @file{configure.in} must define the variable @samp{LEX}.  You can use
 @samp{AC_PROG_LEX} to do this (@pxref{Particular Programs, , Particular
@@ -2097,6 +2210,12 @@
 This is all handled for you if you use the @code{AM_PROG_LEX} macro
 (@pxref{Macros}).
 
+When @code{yacc} is invoked, it is passed @samp{LFLAGS} and
address@hidden  The former is a user variable and the latter is
+intended for the @file{Makefile.am} author.
+
+
+
 @cindex ylwrap
 @cindex yacc, multiple parsers
 @cindex Multiple yacc parsers
@@ -3538,6 +3657,13 @@
 @address@hidden@address@hidden, where @var{ALPHA} is a
 letter; it should be omitted for non-alpha releases.
 
address@hidden @code{subdir-objects}
+If this option is specified, then objects are placed into the
+subdirectory of the build directory corresponding to the subdirectory of
+the source file.  For instance if the source file is
address@hidden/file.cxx}, then the output file would be
address@hidden/file.o}.
+
 @item @var{version}
 @cindex Option, version
 A version number (e.g. @samp{0.30}) can be specified.  If Automake is not
@@ -3556,6 +3682,7 @@
 @menu
 * Tags::                        Interfacing to etags and mkid
 * Suffixes::                    Handling new file extensions
+* Multilibs::                   Support for multilibbing.
 @end menu
 
 
@@ -3604,7 +3731,7 @@
 build directory.
 
 
address@hidden Suffixes,  , Tags, Miscellaneous
address@hidden Suffixes, Multilibs, Tags, Miscellaneous
 @section Handling new file extensions
 
 @cindex Adding new SUFFIXES
@@ -3634,6 +3761,20 @@
 
 Any given @code{SUFFIXES} go at the start of the generated suffixes
 list, followed by automake generated suffixes not already in the list.
+
+
address@hidden Multilibs, , Suffixes, Miscellaneous
address@hidden Support for Multilibs
+
+Automake has support for an obscure feature called multilibs.  A
address@hidden is a library which is built for multiple different ABIs
+at a single time; each time the library is built with a different target
+flag combination.  This is only useful when the library is intended to
+be cross-compiled, and it is almost exclusively used for compiler
+support libraries.
+
+The multilib support is still experimental.  Only use it if you are
+familiar with multilibs and can debug problems you might encounter.
 
 
 @node Include, Conditionals, Miscellaneous, Top