FYI: fix `make dvi' overflow/underflow warnings

[Alexandre Duret-Lutz]

I'm installing this on HEAD and branch-1-9.

2005-02-26  Alexandre Duret-Lutz  <address@hidden>

        * doc/automake.texi: Reword a few sentences to fix all underflow
        and overflow warnings during `make dvi'.
        (Auxiliary Programs) <configure.guess, config.sub>: Update URL.
        (Public macros) <AM_WITH_DMALLOC>: Likewise.

Index: doc/automake.texi
===================================================================
RCS file: /cvs/automake/automake/doc/automake.texi,v
retrieving revision 1.97
diff -u -r1.97 automake.texi
--- doc/automake.texi   12 Feb 2005 21:24:34 -0000      1.97
+++ doc/automake.texi   26 Feb 2005 01:01:58 -0000
@@ -706,11 +706,14 @@
 
 @item config.guess
 @itemx config.sub
-These programs compute the canonical triplets for the given build, host,
-or target architecture.  These programs are updated regularly 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.
+These two programs compute the canonical triplets for the given build,
+host, or target architecture.  These programs are updated regularly to
+support new architectures and fix probes broken by changes in new
+kernel versions.  Each new release of Automake comes with up-to-date
+copies of these programs.  If your copy of Automake is getting old,
+You are encouraged to fetch the latest versions of these files from
address@hidden://savannah.gnu.org/cvs/?group=config} before making a
+release.
 
 @item depcomp
 This program understands how to run a compiler so that it will generate
@@ -1070,14 +1073,14 @@
 
 @vindex AUTOCONF
 Automake will run @code{autoconf} to scan @file{configure.ac} and its
-dependencies (@file{aclocal.m4}), therefore @code{autoconf} must be in
-your @code{PATH}.  If there is an @code{AUTOCONF} variable in your
-environment it will be used instead of @code{autoconf}, this allows you
-to select a particular version of Autoconf.  By the way, don't
-misunderstand this paragraph: Automake runs @code{autoconf} to
address@hidden your @file{configure.ac}, this won't build
address@hidden and you still have to run @code{autoconf} yourself for
-this purpose.
+dependencies (i.e., @file{aclocal.m4} and any included file),
+therefore @code{autoconf} must be in your @code{PATH}.  If there is an
address@hidden variable in your environment it will be used instead
+of @code{autoconf}, this allows you to select a particular version of
+Autoconf.  By the way, don't misunderstand this paragraph: Automake
+runs @code{autoconf} to @strong{scan} your @file{configure.ac}, this
+won't build @file{configure} and you still have to run @code{autoconf}
+yourself for this purpose.
 
 @cindex @command{automake} options
 @cindex Options, @command{automake}
@@ -1371,11 +1374,13 @@
 @example
 AC_SUBST([APIVERSION], @dots{})
 @dots{}
-AC_CONFIG_FILES([tests/address@hidden@}:tests/aclocal.in],
-                [chmod +x tests/address@hidden@}],
-                [APIVERSION=$APIVERSION])
-AC_CONFIG_FILES([tests/address@hidden@}:tests/automake.in],
-                [chmod +x tests/address@hidden@}])
+AC_CONFIG_FILES(
+  [tests/address@hidden@}:tests/aclocal.in],
+  [chmod +x tests/address@hidden@}],
+  [APIVERSION=$APIVERSION])
+AC_CONFIG_FILES(
+  [tests/address@hidden@}:tests/automake.in],
+  [chmod +x tests/address@hidden@}])
 @end example
 
 @noindent
@@ -1776,8 +1781,8 @@
 (@pxref{aclocal options}).
 @end table
 
-As an example, suppose that automake-1.6.2 was configured with
address@hidden/usr/local}.  Then, the search path would be:
+As an example, suppose that @command{automake-1.6.2} was configured with
address@hidden@-/usr/local}.  Then, the search path would be:
 
 @enumerate
 @item @file{/usr/local/share/aclocal-1.6/}
@@ -2058,9 +2063,9 @@
 system-wide third-party macros in your local macro directory, solving
 the above problem.  Simply use:
 
address@hidden
address@hidden
 ACLOCAL_AMFLAGS = -I m4 --install
address@hidden smallexample
address@hidden example
 
 @noindent
 With this setup, system-wide macros will be copied to @file{m4/}
@@ -2076,9 +2081,9 @@
 automatically when new system-wide versions are installed.  A serial
 number should be a single line of the form
 
address@hidden
address@hidden
 #serial @var{NNN}
address@hidden smallexample
address@hidden example
 
 @noindent
 where @var{NNN} contains only digits and dots.  It should appear in
@@ -2102,9 +2107,9 @@
 
 A serial number should be a single line of the form
 
address@hidden
address@hidden
 # serial @var{version}
address@hidden smallexample
address@hidden example
 
 @noindent
 where @var{version} is a version number containing only digits and
@@ -2115,9 +2120,9 @@
 The @code{#} must be the first character on the line,
 and it is OK to have extra words after the version, as in
 
address@hidden
address@hidden
 #serial @var{version} @var{garbage}
address@hidden smallexample
address@hidden example
 
 Normally these serial numbers are completely ignored by
 @command{aclocal} and @command{autoconf}, like any genuine comment.
@@ -2138,17 +2143,17 @@
 @code{AX_THIRD_PARTY} defined in
 @file{/usr/share/aclocal/thirdparty.m4} as follows:
 
address@hidden
address@hidden
 # serial 1
 AC_DEFUN([AX_THIRD_PARTY], [...])
address@hidden smallexample
address@hidden example
 
 MyPackage uses an @file{m4/} directory to store local macros as
 explained in @ref{Local Macros}, and has
 
address@hidden
address@hidden
 ACLOCAL_AMFLAGS = -I m4 --install
address@hidden smallexample
address@hidden example
 
 @noindent
 in its top-level @file{Makefile.am}.
@@ -2217,10 +2222,11 @@
 @end itemize
 
 @noindent
-As soon as @command{aclocal} sees a greater serial number, it forgets
-anything it knows about smaller serial numbers for the same file.  So
-after it has found @file{/usr/share/aclocal/thirdparty.m4} with serial
-2, @command{aclocal} will proceed as if it had never seen
+When @command{aclocal} sees a greater serial number, it immediately
+forgets anything it knows from files that have the same basename and a
+smaller serial number.  So after it has found
address@hidden/usr/share/aclocal/thirdparty.m4} with serial 2,
address@hidden will proceed as if it had never seen
 @file{m4/thirdparty.m4}.  This brings us back to a situation similar
 to that at the beginning of our example, where no local file defined
 the macro.  @command{aclocal} will install the new version of the
@@ -2463,9 +2469,8 @@
 @cindex @command{dmalloc}, support for
 @vindex WITH_DMALLOC
 @opindex --with-dmalloc
-Add support for the
address@hidden://ftp.letters.com/src/dmalloc/dmalloc.tar.gz, dmalloc}
-package.  If the user configures with @samp{--with-dmalloc}, then define
+Add support for the @uref{http://dmalloc.com/, Dmalloc package}.
+If the user configures with @samp{--with-dmalloc}, then define
 @code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}.
 
 @item AM_WITH_REGEX
@@ -3199,10 +3204,10 @@
 @dots{}
 @end example
 
-In this case, @code{HELLO_SYSTEM} should be replaced by
address@hidden or @file{hello-generic.o}, and added to
address@hidden and @code{hello_LDADD} in order to be built
-and linked in.
+In this case, the variable @code{HELLO_SYSTEM} should be replaced by
+either @file{hello-linux.o} or @file{hello-generic.o}, and added to
+both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
+built and linked in.
 
 @subsubsection Conditional compilation using Automake conditionals
 
@@ -3219,7 +3224,7 @@
 endif
 @end example
 
-In this case, your @file{configure.ac} should setup the @code{LINUX}
+In this case, @file{configure.ac} should setup the @code{LINUX}
 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
 
 When using conditionals like this you don't need to use the
@@ -3480,7 +3485,7 @@
 
 The examples below illustrate the differences between these two methods.
 
-Here is an example where @code{$(WANTEDLIBS)} is an @code{AC_SUBST}ed
+Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
 variable set at @file{./configure}-time to either @file{libfoo.la},
 @file{libbar.la}, both, or none.  Although @code{$(WANTEDLIBS)}
 appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
@@ -3566,8 +3571,8 @@
 are typically used to encapsulate many sublibraries, later gathered
 into one big installed library.
 
-Libtool convenience libraries are declared by
address@hidden, @code{check_LTLIBRARIES}, or even
+Libtool convenience libraries are declared by directory-less variables
+such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
 @code{EXTRA_LTLIBRARIES}.  Unlike installed libtool libraries they do
 not need an @code{-rpath} flag at link time (actually this is the only
 difference).
@@ -3896,8 +3901,9 @@
 @samp{_LDADD} (see below), then you should list the corresponding source
 files in the @samp{EXTRA_} variable.
 
-This variable also supports @samp{dist_} and @samp{nodist_} prefixes,
-e.g., @samp{nodist_EXTRA_maude_SOURCES}.
+This variable also supports @samp{dist_} and @samp{nodist_} prefixes.
+For instance @samp{nodist_EXTRA_maude_SOURCES} would list extra
+sources that may need to be built, but should not be distributed.
 
 @item maude_AR
 A static library is created by default by invoking @code{$(AR)
@@ -4230,7 +4236,7 @@
 tool2_SOURCES = @dots{}
 @end example
 
-Please note it would be wrong to use the @code{$(LIBOBJS)} or
+Please note it would be wrong to use the variables @code{$(LIBOBJS)} or
 @code{$(ALLOCA)} in @file{src/Makefile.am}, because these variables
 contains unprefixed object names, and for instance
 @file{malloc.$(OBJEXT)} is not buildable in the @file{src/} directory.
@@ -4600,7 +4606,8 @@
 @table @file
 
 @item .F
address@hidden(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) 
$(AM_FFLAGS) $(FFLAGS)}
address@hidden(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
+$(AM_FFLAGS) $(FFLAGS)}
 
 @item .r
 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
@@ -4622,7 +4629,8 @@
 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
 
 @item .F
address@hidden(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) 
$(AM_FFLAGS) $(FFLAGS)}
address@hidden(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
+$(AM_FFLAGS) $(FFLAGS)}
 
 @item .r
 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
@@ -5658,14 +5666,15 @@
 @samp{pyexecdir_PYTHON}, @samp{pkgpyexecdir_PYTHON}, depending where you
 want your files installed.
 
address@hidden(address@hidden, address@hidden,
address@hidden)} takes three optional arguments.  It will
-search a Python interpreter on the system.  The first argument, if
-present, is the minimum version of Python required for this package:
address@hidden will skip any Python interpreter which is older
-than @var{VERSION}.  If an interpreter is found and satisfies
address@hidden, then @var{ACTION-IF-FOUND} is run.  Otherwise,
address@hidden is run.
address@hidden AM_PATH_PYTHON (address@hidden, address@hidden, address@hidden)
+
+Search a Python interpreter on the system.  This macro takes three
+optional arguments.  The first argument, if present, is the minimum
+version of Python required for this package: @code{AM_PATH_PYTHON}
+will skip any Python interpreter which is older than @var{VERSION}.
+If an interpreter is found and satisfies @var{VERSION}, then
address@hidden is run.  Otherwise, @var{ACTION-IF-NOT-FOUND} is
+run.
 
 If @var{ACTION-IF-NOT-FOUND} is not specified, the default is to abort
 configure.  This is fine when Python is an absolute requirement for the
@@ -5673,11 +5682,12 @@
 package, @code{AM_PATH_PYTHON} could be called as follows.
 
 @example
-  AM_PATH_PYTHON(2.2,, :)
+AM_PATH_PYTHON(2.2,, :)
 @end example
 
address@hidden creates several output variables based on the
-Python installation found during configuration.
address@hidden creates the following output variables based on
+the Python installation found during configuration.
address@hidden defmac
 
 @vtable @code
 @item PYTHON
@@ -5694,10 +5704,6 @@
   AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
 @end example
 
-
-If the @var{ACTION-IF-NOT-FOUND}
-is specified
-
 @item PYTHON_VERSION
 The Python version number, in the form @address@hidden
 (e.g. @samp{1.5}).  This is currently the value of
@@ -5872,7 +5878,7 @@
 @opindex no-texinfo.tex
 
 The option @samp{no-texinfo.tex} can be used to eliminate the
-requirement for @file{texinfo.tex}.  Use of the variable
+requirement for the file @file{texinfo.tex}.  Use of the variable
 @code{TEXINFO_TEX} is preferable, however, because that allows the
 @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
 
@@ -5912,11 +5918,12 @@
 
 @item AM_MAKEINFOFLAGS
 @itemx AM_MAKEINFOHTMLFLAGS
-Maintainer flags passed to each @code{makeinfo} invocation.  These
-are maintainer variables that can be overridden in @file{Makefile.am}.
address@hidden(AM_MAKEINFOFLAGS)} is passed to @code{makeinfo} when building
address@hidden files; and @code{$(AM_MAKEINFOHTMLFLAGS)} is used when
-building @file{.html} files.
+Maintainer flags passed to each @code{makeinfo} invocation.  Unlike
address@hidden, these variables are meant to be defined by
+maintainers in @file{Makefile.am}.  @code{$(AM_MAKEINFOFLAGS)} is
+passed to @code{makeinfo} when building @file{.info} files; and
address@hidden(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
+files.
 
 For instance the following setting can be used to obtain one single
 @file{.html} file per manual, without node separators.
@@ -5924,10 +5931,9 @@
 AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
 @end example
 
-By default, @code{$(AM_MAKEINFOHTMLFLAGS)} is set to
address@hidden(AM_MAKEINFOFLAGS)}.  This means that defining
address@hidden(AM_MAKEINFOFLAGS)} without defining
address@hidden(AM_MAKEINFOHTMLFLAGS)} will impact builds of both @file{.info}
address@hidden Default to @code{$(AM_MAKEINFOFLAGS)}.
+This means that defining @code{AM_MAKEINFOFLAGS} without defining
address@hidden will impact builds of both @file{.info}
 and @file{.html} files.
 
 @item TEXI2DVI
@@ -6082,13 +6088,15 @@
 
 Variables using the standard directory prefixes @samp{data},
 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
address@hidden, or @samp{pkginclude} (e.g. @samp{data_DATA}) are
-installed by @samp{install-data}.
address@hidden, or @samp{pkginclude} are installed by
address@hidden
+
+Variables using the standard directory prefixes @samp{bin},
address@hidden, @samp{libexec}, @samp{sysconf}, @samp{localstate},
address@hidden, or @samp{pkglib} are installed by @samp{install-exec}.
 
-Variables using the standard directory prefixes @samp{bin}, @samp{sbin},
address@hidden, @samp{sysconf}, @samp{localstate}, @samp{lib}, or
address@hidden (e.g. @samp{bin_PROGRAMS}) are installed by
address@hidden
+For instance @samp{data_DATA} files are installed by @samp{install-data},
+while @samp{bin_PROGRAMS} files are installed by @code{install-exec}.
 
 Any variable using a user-defined directory prefix with @samp{exec} in
 the name (e.g. @samp{myexecbin_PROGRAMS}) is installed by
@@ -6391,8 +6399,8 @@
 @trindex distcleancheck
 @vindex DISTCLEANFILES
 @vindex distcleancheck_listfiles
-Speaking about potential distribution errors, @code{distcheck} will also
-ensure that the @code{distclean} rule actually removes all built
+Speaking about potential distribution errors, @code{distcheck} also
+ensures that the @code{distclean} rule actually removes all built
 files.  This is done by running @code{make distcleancheck} at the end of
 the @code{VPATH} build.  By default, @code{distcleancheck} will run
 @code{distclean} and then make sure the build tree has been emptied by
@@ -7022,7 +7030,7 @@
 @end example
 
 If you add filenames to @samp{ETAGS_ARGS}, you will probably also
-want to set @samp{TAGS_DEPENDENCIES}.  The contents of this variable
+want to define @samp{TAGS_DEPENDENCIES}.  The contents of this variable
 are added directly to the dependencies for the @code{tags} rule.
 @vindex TAGS_DEPENDENCIES
 
@@ -7037,11 +7045,11 @@
 directory-by-directory basis.
 @trindex id
 
-Automake also supports the @uref{http://www.gnu.org/software/global/,
-GNU Global Tags program}.  The @code{GTAGS} rule runs Global Tags
-automatically and puts the result in the top build directory.  The
-variable @code{GTAGS_ARGS} holds arguments which are passed to
address@hidden
+Finally, Automake also emit rules to support the
address@hidden://www.gnu.org/software/global/, GNU Global Tags program}.
+The @code{GTAGS} rule runs Global Tags and puts the
+result in the top build directory.  The variable @code{GTAGS_ARGS}
+holds arguments which are passed to @code{gtags}.
 @vindex GTAGS_ARGS
 
 
@@ -7200,7 +7208,7 @@
 noinst_PROGRAMS = $(DBG)
 @end example
 
-This trivial example could also be handled using EXTRA_PROGRAMS
+This trivial example could also be handled using @code{EXTRA_PROGRAMS}
 (@pxref{Conditional Programs}).
 
 You may only test a single variable in an @code{if} statement, possibly
@@ -7466,18 +7474,19 @@
 @code{install-ps}, @code{uninstall}, @code{installdirs},
 @code{installcheck} and the various @code{clean} targets
 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
address@hidden).  Note that there are no
address@hidden or @code{uninstall-data-local} targets;
-just use @code{uninstall-local}.  It doesn't make sense to uninstall
-just data or just executables.
address@hidden).
+
+Note that there are no @code{uninstall-exec-local} or
address@hidden targets; just use @code{uninstall-local}.
+It doesn't make sense to uninstall just data or just executables.
 
 For instance, here is one way to erase a subdirectory during
 @code{make clean} (@pxref{Clean}).
 
address@hidden
address@hidden
 clean-local:
         -rm -rf testSubDir
address@hidden smallexample
address@hidden example
 
 Older version of this manual used to show how to use
 @code{install-data-local} to install a file to some hard-coded
@@ -7985,9 +7994,9 @@
 out-of-date file is up-to-date.
 
 For instance, suppose a developer has modified @file{Makefile.am} and
-rebuilt @file{Makefile.in}, and then decide to do a last-minute change
-to @file{Makefile.am} right before checking in both files (without
-rebuilding @file{Makefile.in} to account for the change).
+has rebuilt @file{Makefile.in}.  He then decide to do a last-minute
+change to @file{Makefile.am} right before checking in both files
+(without rebuilding @file{Makefile.in} to account for the change).
 
 This last change to @file{Makefile.am} make the copy of
 @file{Makefile.in} out-of-date.  Since CVS processes files
@@ -8096,11 +8105,11 @@
 rules that need exotic tools that users may not have available.
 
 Several years ago Fran@,{c}ois Pinard pointed out several arguments
-against @code{AM_MAINTAINER_MODE}.  Most of them relate to insecurity.
-By removing dependencies you get non-dependable builds: change to
-sources files can have no effect on generated files and this can be
-very confusing when unnoticed.  He adds that security shouldn't be
-reserved to maintainers (what @code{--enable-maintainer-mode}
+against this @code{AM_MAINTAINER_MODE} macro.  Most of them relate to
+insecurity.  By removing dependencies you get non-dependable builds:
+change to sources files can have no effect on generated files and this
+can be very confusing when unnoticed.  He adds that security shouldn't
+be reserved to maintainers (what @code{--enable-maintainer-mode}
 suggests), on the contrary.  If one user has to modify a
 @file{Makefile.am}, then either @file{Makefile.in} should be updated
 or a warning should be output (this is what Automake uses
@@ -8667,7 +8676,7 @@
 three objects will be linked to form @file{foo}.
 
 This trick can also be achieved using Libtool convenience libraries,
-i.e., @code{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
+for instance @code{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
 Convenience Libraries}).
 
 Another tempting idea to implement per-object flags is to override the
@@ -8945,9 +8954,9 @@
 The above @code{install-data-local} example for installing
 @file{/etc/afile} would be better replaced by
 
address@hidden
address@hidden
 sysconf_DATA = afile
address@hidden smallexample
address@hidden example
 
 @noindent
 by default @code{sysconfdir} will be @code{$(prefix)/etc}, because
@@ -9009,12 +9018,16 @@
 
 @example
 $EMACS -batch -q -eval '(while load-path
-                          (princ (concat (car load-path) "\n"))
-                          (setq load-path (cdr load-path)))' >conftest.out
-lispdir=`sed -n \
-  -e 's,/$,,' \
-  -e 
'/.*\/lib\/x*emacs\/site-lisp$/@{s,.*/lib/\(x*emacs/site-lisp\)$,address@hidden@}/\1,;p;q;@}'
 \
-  -e 
'/.*\/share\/x*emacs\/site-lisp$/@{s,.*/share/\(x*emacs/site-lisp\),address@hidden@}/\1,;p;q;@}'
 \
+  (princ (concat (car load-path) "\n"))
+  (setq load-path (cdr load-path)))' >conftest.out
+lispdir=`sed -n
+  -e 's,/$,,'
+  -e '/.*\/lib\/x*emacs\/site-lisp$/@{
+        s,.*/lib/\(x*emacs/site-lisp\)$,address@hidden@}/\1,;p;q;
+      @}'
+  -e '/.*\/share\/x*emacs\/site-lisp$/@{
+        s,.*/share/\(x*emacs/site-lisp\),address@hidden@}/\1,;p;q;
+      @}'
   conftest.out`
 @end example
 
@@ -9360,7 +9373,7 @@
 @item 1997-02-28 @email{automake@@gnu.ai.mit.edu} list alive
 
 The mailing list is announced as follows:
address@hidden
address@hidden
 I've created the "automake" mailing list.  It is
 "automake@@gnu.ai.mit.edu".  Administrivia, as always, to
 automake-request@@gnu.ai.mit.edu.
@@ -9376,7 +9389,7 @@
 This list is open to anybody who wants to join.  Tell all your
 friends!
 -- Tom Tromey
address@hidden example
address@hidden smallexample
 
 Before that people were discussing Automake privately, on the Gnits
 mailing list (which is not public either), and less frequently on
-- 
Alexandre Duret-Lutz