some modernizations to the documentation (esp. VPATH builds)

[Paul Eggert]

I installed the following patch to the Autoconf documentation to
modernize things a bit.  The biggest deal is that this changes
INSTALL to recommend only GNU make for VPATH builds.  I recently
discovered that VPATH builds don't work for Solaris make.  The
problems are already well documented in the Autoconf manual.  Rather
than try to support them (which would be difficult -- it's mostly an
Automake issue, I think) we might as well just warn people away from
them.

The patch also marks several macros as obsolescent; if you think they
aren't obsolescent, please let me know.  (I have no current plans to
remove these macros.)

2006-06-04  Paul Eggert  <address@hidden>

        * NEWS: GNU make now recommended for VPATH builds.
        Mention that some macros are now documented to be obsolescent.
        * doc/autoconf.texi:
        Prefer "current" to "modern" to describe
        currently-used (albeit perhaps old-fashioned) hosts.
        Mention which ancient features no longer need to be worried about.
        setgid -> set-group-ID
        setuid -> set-user-ID (these are the Posix terms)
        Fix some misuses of "only".
        (AC_C_BACKSLASH_A, AC_C_CONST, AC_C_PROTOTYPES):
        (AC_C_STRINGIZE, AC_C_VOLATILE, AC_FUNC_CLOSEDIR_VOID):
        (AC_FUNC_GETPGRP, AC_FUNC_LSTAT, AC_FUNC_MEMCMP):
        (AC_FUNC_SELECT_ARGTYPES, AC_FUNC_SETPGRP):
        (AC_FUNC_SETVBUF_REVERSED, AC_FUNC_STAT, AC_FUNC_STRFTIME):
        (AC_FUNC_STRNLEN, AC_FUNC_UTIME_NULL, AC_FUNC_VPRINTF):
        (AC_HEADER_DIRENT, AC_HEADER_STAT, AC_HEADER_STDC):
        (AC_HEADER_SYS_WAIT, AC_HEADER_TIME, AC_ISC_POSIX):
        (AC_PROG_GCC_TRADITIONAL, AC_STRUCT_TM):
        Mention that these macros are obsolescent.
        (Installation Directory Variables): shall -> should
        (File Descriptors): Mention that 0, 1, 2 might get reopened.
        Mention that it's now safe to use 3 and 4.
        (Limitations of Usual Tools): cp -r is now specified by Posix.
        Omit longwinded and obsolescent discussion of cp -f.
        Modernize discussion of expr, ls.
        (Limitations of Make): Modernize discussion of VPATH builds.
        Mention $? as a workaround in some cases.
        * doc/install.texi (Basic Installation):
        Mention "./configure; make; make install" first.  Be more
        specific about why this file is generic.  Remove unnecessary
        parens.  Remove misleading "only".  Remove obsolete advice
        about csh.  Don't say "configure" takes awhile; say it
        might take a while.  Suggest CFLAGS=-g rather than CFLAGS=-O2,
        and CC=c99 rather than CC=c89, as these are blessed by current
        Posix.  Recommend GNU make if doing a VPATH build.

Index: NEWS
===================================================================
RCS file: /cvsroot/autoconf/autoconf/NEWS,v
retrieving revision 1.375
diff -p -u -r1.375 NEWS
--- NEWS        28 May 2006 12:38:49 -0000      1.375
+++ NEWS        4 Jun 2006 07:37:22 -0000
@@ -1,8 +1,16 @@
 * Major changes in Autoconf 2.59d
 
- ** Even more safety checks for the new Directory variables:
-   Warn about suspicious `${datarootdir}' found in config files output.
- 
+** GNU make now recommended for VPATH builds
+  INSTALL now suggests VPATH builds (e.g., "sh ../srcdir/configure")
+  only if you use GNU make.  In practice, other 'make' implementations
+  have too many subtle incompatibilities in their support for VPATH.
+  These incompatibilities do not hurt bare Autoconf, but do affect
+  Automake-generated makefiles.  Recommending GNU make keeps the
+  installation instructions simpler.
+
+** Even more safety checks for the new Directory variables:
+  Warn about suspicious `${datarootdir}' found in config files output.
+
 ** AC_TRY_COMMAND, AC_TRY_EVAL, ac_config_guess, ac_config_sub, ac_configure
   These never-documented macros and variables have been marked with
   comments saying that they may be removed in a future release,
@@ -28,6 +36,24 @@
   Now more robust with special characters in file names, or when
   multiple processes create the same directory at the same time.
 
+** Obsolescent macros
+  The documentation now says that the following macros are obsolescent:
+  they test for problems that are so old that they are no longer of
+  practical importance on current systems.
+
+    AC_C_BACKSLASH_A       AC_FUNC_SELECT_ARGTYPES   AC_HEADER_STAT
+    AC_C_CONST             AC_FUNC_SETPGRP           AC_HEADER_STDC
+    AC_C_PROTOTYPES        AC_FUNC_SETVBUF_REVERSED  AC_HEADER_SYS_WAIT
+    AC_C_STRINGIZE         AC_FUNC_STAT              AC_HEADER_TIME
+    AC_C_VOLATILE          AC_FUNC_STRFTIME          AC_ISC_POSIX
+    AC_FUNC_CLOSEDIR_VOID  AC_FUNC_STRNLEN           AC_PROG_GCC_TRADITIONAL
+    AC_FUNC_GETPGRP        AC_FUNC_UTIME_NULL        AC_STRUCT_TM
+    AC_FUNC_LSTAT          AC_FUNC_VPRINTF
+    AC_FUNC_MEMCMP         AC_HEADER_DIRENT
+
+  New programs need not use these macros.  We have no current plans to
+  remove them.
+
 * Major changes in Autoconf 2.59c
 
   Released 2006-04-12, by Ralf Wildenhues.
Index: doc/autoconf.texi
===================================================================
RCS file: /cvsroot/autoconf/autoconf/doc/autoconf.texi,v
retrieving revision 1.1035
diff -p -u -r1.1035 autoconf.texi
--- doc/autoconf.texi   3 Jun 2006 23:21:06 -0000       1.1035
+++ doc/autoconf.texi   4 Jun 2006 07:37:23 -0000
@@ -2502,7 +2502,7 @@ the user runs:
 @table @samp
 @item make
 she can still specify a different prefix from the one specified to
address@hidden, in which case, if needed, the package shall hard
address@hidden, in which case, if needed, the package should hard
 code dependencies corresponding to the make-specified prefix.
 
 @item make install
@@ -3916,7 +3916,7 @@ On ancient hosts, @code{exit} returned @
 This is because @code{exit} predates @code{void}, and there was a long
 tradition of it returning @code{int}.
 
-On more-modern hosts, the problem more likely is that @code{exit} is not
+On current hosts, the problem more likely is that @code{exit} is not
 declared, due to C++ problems of some sort or another.  For this reason
 we suggest that test programs not invoke @code{exit}, but return from
 @code{main} instead.
@@ -4047,8 +4047,9 @@ Solaris 7).
 @c @fuindex vsprintf
 @prindex @code{vsprintf}
 The C standard says @code{sprintf} and @code{vsprintf} return the
-number of bytes written, but on some ancient systems (SunOS 4 for
-instance) they return the buffer pointer instead.
+number of bytes written.  On some ancient systems (SunOS 4 for
+instance) they return the buffer pointer instead, but these no
+longer need to be worried about.
 
 @item @code{sscanf}
 @c @fuindex sscanf
@@ -4234,6 +4235,9 @@ return value for an error indicator.
 Currently this test is implemented by running a test program.  When
 cross compiling the pessimistic assumption that @code{closedir} does not
 return a meaningful value is made.
+
+This macro is obsolescent, as @code{closedir} returns a meaningful value
+on current systems.  New programs need not use this macro.
 @end defmac
 
 @defmac AC_FUNC_ERROR_AT_LINE
@@ -4376,7 +4380,7 @@ If @samp{struct nlist} has an @samp{n_un
 @code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
 
 @item
-Programs may need to be installed setgid (or setuid) for
+Programs may need to be installed set-group-ID (or set-user-ID) for
 @code{getloadavg} to work.  In this case, define
 @code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
 to @samp{true} (and otherwise to @samp{false}), and set
@@ -4419,6 +4423,9 @@ behaves like Posix's @code{getpgid}.
 This macro does not check whether
 @code{getpgrp} exists at all; if you need to work in that situation,
 first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
+
+This macro is obsolescent, as current systems have a @code{getpgrp}
+whose signature conforms to Posix.  New programs need not use this macro.
 @end defmac
 
 @defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
@@ -4488,6 +4495,9 @@ If the @code{memcmp} function is not ava
 bytes or more and with at least one buffer not starting on a 4-byte
 boundary (such as the one on NeXT x86 OpenStep), require an
 @code{AC_LIBOBJ} replacement for @samp{memcmp}.
+
+This macro is obsolescent, as current systems have a working
address@hidden  New programs need not use this macro.
 @end defmac
 
 @defmac AC_FUNC_MBRTOWC
@@ -4517,7 +4527,7 @@ Posix standard and should be the inverse
 @c @fuindex mmap
 @prindex @code{mmap}
 If the @code{mmap} function exists and works correctly, define
address@hidden  Only checks private fixed mapping of already-mapped
address@hidden  This checks only private fixed mapping of already-mapped
 memory.
 @end defmac
 
@@ -4557,6 +4567,9 @@ in @code{SELECT_TYPE_ARG1}, @code{SELECT
 @code{SELECT_TYPE_ARG5} respectively.  @code{SELECT_TYPE_ARG1} defaults
 to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
 and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
+
+This macro is obsolescent, as current systems have a @code{select} whose
+signature conforms to Posix.  New programs need not use this macro.
 @end defmac
 
 @defmac AC_FUNC_SETPGRP
@@ -4569,6 +4582,9 @@ If @code{setpgrp} takes no argument (the
 two process IDs as arguments.  This macro does not check whether
 @code{setpgrp} exists at all; if you need to work in that situation,
 first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
+
+This macro is obsolescent, as current systems have a @code{setpgrp}
+whose signature conforms to Posix.  New programs need not use this macro.
 @end defmac
 
 @defmac AC_FUNC_STAT
@@ -4589,6 +4605,9 @@ this.
 If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
 @code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
 replacement of it.
+
+These macros are obsolescent, as no current systems have the bug.
+New programs need not use these macros.
 @end defmac
 
 @defmac AC_FUNC_SETVBUF_REVERSED
@@ -4599,6 +4618,9 @@ replacement of it.
 If @code{setvbuf} takes the buffering type as its second argument and
 the buffer pointer as the third, instead of the other way around, define
 @code{SETVBUF_REVERSED}.
+
+This macro is obsolescent, as no current systems have the bug.
+New programs need not use this macro.
 @end defmac
 
 @defmac AC_FUNC_STRCOLL
@@ -4636,6 +4658,9 @@ the buffer argument.
 @prindex @code{strftime}
 Check for @code{strftime} in the @file{intl} library, for SCO Unix.
 Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
+
+This macro is obsolescent, as no current systems require the @file{intl}
+library for @code{strftime}.  New programs need not use this macro.
 @end defmac
 
 @defmac AC_FUNC_STRTOD
@@ -4663,6 +4688,9 @@ If the @code{strtold} function exists an
 @prindex @code{strnlen}
 If the @code{strnlen} function is not available, or is buggy (like the one
 from @acronym{AIX} 4.3), require an @code{AC_LIBOBJ} replacement for it.
+
+This macro is obsolescent, as no current systems have the bug.
+New programs need not use this macro.
 @end defmac
 
 @defmac AC_FUNC_UTIME_NULL
@@ -4672,6 +4700,9 @@ from @acronym{AIX} 4.3), require an @cod
 @prindex @code{utime}
 If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to
 the present, define @code{HAVE_UTIME_NULL}.
+
+This macro is obsolescent, as all current systems have a @code{utime}
+that behaves this way.  New programs need not use this macro.
 @end defmac
 
 @defmac AC_FUNC_VPRINTF
@@ -4684,6 +4715,9 @@ If @code{vprintf} is found, define @code
 @code{_doprnt} is found, define @code{HAVE_DOPRNT}.  (If @code{vprintf}
 is available, you may assume that @code{vfprintf} and @code{vsprintf}
 are also available.)
+
+This macro is obsolescent, as all current systems have @code{vprintf}.
+New programs need not use this macro.
 @end defmac
 
 @defmac AC_REPLACE_FNMATCH
@@ -5044,6 +5078,9 @@ the length of a directory entry name by 
 
 This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
 
+This macro is obsolescent, as all current systems with directory
+libraries have @code{<dirent.h>}.  New programs need not use this macro.
+
 Also see @code{AC_STRUCT_DIRENT_D_INO} and
 @code{AC_STRUCT_DIRENT_D_TYPE} (@pxref{Particular Structures}).
 @end defmac
@@ -5093,6 +5130,9 @@ If the macros @code{S_ISDIR}, @code{S_IS
 @file{sys/stat.h} do not work properly (returning false positives),
 define @code{STAT_MACROS_BROKEN}.  This is the case on Tektronix UTekV,
 Amdahl UTS and Motorola System V/88.
+
+This macro is obsolescent, as no current systems have the bug.
+New programs need not use this macro.
 @end defmac
 
 @defmac AC_HEADER_STDBOOL
@@ -5150,11 +5190,12 @@ declare @code{free} (and thus presumably
 functions), and whether the @file{ctype.h} macros work on characters
 with the high bit set, as the C standard requires.
 
-Nowadays this macro is becoming obsolete.  However, if you use it, your
-code can refer to @code{STDC_HEADERS} instead of @code{__STDC__} to
+If you use this macro, your code can refer to @code{STDC_HEADERS} to
 determine whether the system has conforming header files (and probably C
-library functions).  This is useful if you worry about portability
-to ancient systems that lack C89 header files.
+library functions).
+
+This macro is obsolescent, as current systems have conforming header
+files.  New programs need not use this macro.
 
 @hdrindex{string.h}
 @hdrindex{strings.h}
@@ -5162,21 +5203,23 @@ Nowadays @file{string.h} is part of the 
 @code{strcpy}, and @file{strings.h} is standardized by Posix and declares
 @acronym{BSD} functions like @code{bcopy}; but
 historically, string functions were a major sticking point in this area.
-If you worry about portability to ancient systems without standard
-headers, there is so much variation
+If you still want to worry about portability to ancient systems without
+standard headers, there is so much variation
 that it is probably easier to declare the functions you use than to
 figure out exactly what the system header files declare.  Some ancient systems
-contain a mix of functions from the C standard and from @acronym{BSD}; some are
-mostly standard but lack @samp{memmove}; some define the
+contained a mix of functions from the C standard and from @acronym{BSD};
+some were mostly standard but lacked @samp{memmove}; some defined the
 @acronym{BSD} functions as macros in @file{string.h} or
address@hidden; some have only the @acronym{BSD} functions but
address@hidden; some declare the memory functions in @file{memory.h},
address@hidden; some had only the @acronym{BSD} functions but
address@hidden; some declared the memory functions in @file{memory.h},
 some in @file{string.h}; etc.  It is probably sufficient to check for
-one string function and one memory function; if the library has the
-standard versions of those then it probably has most of the others.
+one string function and one memory function; if the library had the
+standard versions of those then it probably had most of the others.
 If you put the following in @file{configure.ac}:
 
 @example
+# This example is obsolescent.
+# Nowadays you can omit these macro calls.
 AC_HEADER_STDC
 AC_CHECK_FUNCS([strchr memcpy])
 @end example
@@ -5186,6 +5229,8 @@ then, in your code, you can use declarat
 
 @example
 @group
+/* This example is obsolescent.
+   Nowadays you can just #include <string.h>.  */
 #if STDC_HEADERS
 # include <string.h>
 #else
@@ -5205,7 +5250,8 @@ char *strchr (), *strrchr ();
 @noindent
 If you use a function like @code{memchr}, @code{memset}, @code{strtok},
 or @code{strspn}, which have no @acronym{BSD} equivalent, then macros won't
-suffice; you must provide an implementation of each function.  An easy
+suffice to port to ancient hosts; you must provide an implementation of
+each function.  An easy
 way to incorporate your implementations only when needed (since the ones
 in system C libraries may be hand optimized) is to, taking @code{memchr}
 for example, put it in @file{memchr.c} and use
@@ -5238,6 +5284,10 @@ example:
 #endif
 @end group
 @end example
+
address@hidden
+This macro is obsolescent, as current systems are compatible with Posix.
+New programs need not use this macro.
 @end defmac
 
 @cvindex _POSIX_VERSION
@@ -5268,9 +5318,9 @@ The way to check whether the system supp
 @hdrindex{time.h}
 @hdrindex{sys/time.h}
 If a program may include both @file{time.h} and @file{sys/time.h},
-define @code{TIME_WITH_SYS_TIME}.  On some older systems,
address@hidden/time.h} includes @file{time.h}, but @file{time.h} is not
-protected against multiple inclusion, so programs should not explicitly
+define @code{TIME_WITH_SYS_TIME}.  On some ancient systems,
address@hidden/time.h} included @file{time.h}, but @file{time.h} was not
+protected against multiple inclusion, so programs could not explicitly
 include both files.  This macro is useful in programs that use, for
 example, @code{struct timeval} as well as
 @code{struct tm}.  It is best used in conjunction with
@@ -5291,6 +5341,10 @@ example, @code{struct timeval} as well a
 #endif
 @end group
 @end example
+
address@hidden
+This macro is obsolescent, as current systems can include both files
+when they exist.  New programs need not use this macro.
 @end defmac
 
 
@@ -5521,8 +5575,10 @@ member, define @code{HAVE_STRUCT_DIRENT_
 @code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of
 @code{d_ino}, not whether its contents are always reliable.
 Traditionally, a zero @code{d_ino} indicated a deleted directory entry,
-though modern systems hide this detail from the user and never return
+though current systems hide this detail from the user and never return
 zero @code{d_ino} values.
+Many current systems report an incorrect @code{d_ino} for a directory
+entry that is a mount point.
 @end defmac
 
 @defmac AC_STRUCT_DIRENT_D_TYPE
@@ -5581,6 +5637,9 @@ AC_CHECK_MEMBERS([struct stat.st_rdev])
 If @file{time.h} does not define @code{struct tm}, define
 @code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
 had better define @code{struct tm}.
+
+This macro is obsolescent, as @file{time.h} defines @code{struct tm} in
+current systems.  New programs need not use this macro.
 @end defmac
 
 @defmac AC_STRUCT_TIMEZONE
@@ -6215,6 +6274,9 @@ set to accept C99; if not, the shell var
 @acindex{HAVE_C_BACKSLASH_A}
 Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
 @samp{\a}.
+
+This macro is obsolescent, as current C compilers understand @samp{\a}.
+New programs need not use this macro.
 @end defmac
 
 @defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, 
@ovar{action-if-unknown})
@@ -6266,6 +6328,9 @@ as this generally yields better results 
 C++ compiler to compile C code is not recommended or supported, and
 installers who run into trouble in this area should get a C compiler
 like GCC to compile their C code.
+
+This macro is obsolescent, as current C compilers support @code{const}.
+New programs need not use this macro.
 @end defmac
 
 @defmac AC_C_RESTRICT
@@ -6304,6 +6369,9 @@ In general, the @code{volatile} keyword 
 you might expect that @code{volatile} is available only when
 @code{__STDC__} is defined.  However, Ultrix 4.3's native compiler does
 support volatile, but does not define @code{__STDC__}.
+
+This macro is obsolescent, as current C compilers support @code{volatile}.
+New programs need not use this macro.
 @end defmac
 
 @defmac AC_C_INLINE
@@ -6331,6 +6399,9 @@ found in macros such as this:
 @example
 #define x(y) #y
 @end example
+
+This macro is obsolescent, as current C compilers support the
+stringizing operator.  New programs need not use this macro.
 @end defmac
 
 @defmac AC_C_TYPEOF
@@ -6352,6 +6423,9 @@ If function prototypes are understood by
 @code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
 Defining @code{__PROTOTYPES} is for the benefit of
 header files that cannot use macros that infringe on user name space.
+
+This macro is obsolescent, as current C compilers support prototypes.
+New programs need not use this macro.
 @end defmac
 
 @defmac AC_PROG_GCC_TRADITIONAL
@@ -6360,9 +6434,10 @@ header files that cannot use macros that
 Add @option{-traditional} to output variable @code{CC} if using the
 @acronym{GNU} C compiler and @code{ioctl} does not work properly without
 @option{-traditional}.  That usually happens when the fixed header files
-have not been installed on an old system.  Since recent versions of the
address@hidden C compiler fix the header files automatically when installed,
-this macro is becoming obsolete.
+have not been installed on an old system.
+
+This macro is obsolescent, since current versions of the @acronym{GNU} C
+compiler fix the header files automatically when installed.
 @end defmac
 
 
@@ -8384,7 +8459,7 @@ For instance:
 @group
 # Checks for programs.
 AC_PROG_CC
-AC_PROG_GCC_TRADITIONAL
+AC_PROG_AWK
 @r{ @dots{} more program checks @dots{}}
 AC_CACHE_SAVE
 @end group
@@ -10032,9 +10107,8 @@ C variables in libraries.
 
 After the category comes the name of the particular feature being
 tested.  Any further words in the macro name indicate particular aspects
-of the feature.  For example, @code{AC_FUNC_UTIME_NULL} checks the
-behavior of the @code{utime} function when called with a @code{NULL}
-pointer.
+of the feature.  For example, @code{AC_FUNC_FNMATCH_GNU} checks whether
+the @code{fnmatch} function supports @acronym{GNU} extensions.
 
 An internal macro should have a name that starts with an underscore;
 Autoconf internals should therefore start with @samp{_AC_}.
@@ -10550,12 +10624,12 @@ classes, or other features that are not 
 shells; restrict yourself to the lowest common denominator.  Even
 @code{unset} is not supported by all shells!
 
-Some old systems have quite
+Some ancient systems have quite
 small limits on the length of the @samp{#!} line; for instance, 32
 bytes (not including the newline) on SunOS 4.
 A few ancient address@hidden based systems (such as Dynix circa 1984)
-required a single space between the @samp{#!} and the @samp{/}, but
-these are no longer of practical concern.
+required a single space between the @samp{#!} and the @samp{/}.
+However, these ancient systems are no longer of practical concern.
 
 The set of external programs you should run in a @command{configure} script
 is fairly small.  @xref{Utilities in Makefiles, , Utilities in
@@ -10842,14 +10916,6 @@ executing the macro at all.
 @cindex File descriptors
 @cindex Shell file descriptors
 
-Some file descriptors shall not be used, since some systems, admittedly
-arcane, use them for special purpose:
-
address@hidden
-3 --- some systems may open it to @samp{/dev/tty}.
-4 --- used on the Kubota Titan.
address@hidden display
-
 Don't redirect the same file descriptor several times, as you are doomed
 to failure under Ultrix.
 
@@ -10908,11 +10974,18 @@ good address@hidden
 Don't try to move/delete open files, such as in @samp{exec >foo; mv foo
 bar}; see @ref{Limitations of Builtins}, @command{mv} for more details.
 
+Don't rely on file descriptors 0, 1, and 2 remaining closed in a
+subsidiary program.  If any of these descriptors is closed, the
+operating system may open an unspecified file for the descriptor in the
+new process image.  Posix says this may be done only if the subsidiary
+program is set-user-ID or set-group-ID, but HP-UX 11.23 does it even for
+ordinary programs.
+
 Don't rely on open file descriptors being open in child processes.  In
 @command{ksh}, file descriptors above 2 which are opened using
address@hidden n>file} are closed by a subsequent @samp{exec} (such as
address@hidden @var{n}>file} are closed by a subsequent @samp{exec} (such as
 that involved in the fork-and-exec which runs a program or script).
-Thus, using sh, we have:
+Thus, using @command{sh}, we have:
 
 @example
 $ @kbd{cat ./descrips}
@@ -10938,7 +11011,15 @@ $
 
 @noindent
 Within the process which runs the @samp{descrips} script, file
-descriptor number 5 is closed.
+descriptor 5 is closed.
+
+A few ancient systems reserved some file descriptors.  By convention,
+file descriptor 3 was opened to @file{/dev/tty} when you logged into
+Eighth Edition (1985) through Tenth Edition Unix (1989).  File
+descriptor 4 had a special use on the Stardent/Kubota Titan (circa
+1990), though we don't now remember what it was.  Both these systems are
+obsolete, so it's now safe to treat file descriptors 3 and 4 like any
+other file descriptors.
 
 @node File System Conventions
 @section File System Conventions
@@ -11692,7 +11773,8 @@ etc.)@: as described above.
 @item LINENO
 Most modern shells provide the current line number in @code{LINENO}.
 Its value is the line number of the beginning of the current command.
-Autoconf attempts to execute @command{configure} with a modern shell.
+Autoconf attempts to execute @command{configure} with a shell that
+supports @code{LINENO}.
 If no such shell is available, it attempts to implement @code{LINENO}
 with a Sed prepass that replaces each instance of the string
 @code{$LINENO} (not followed by an alphanumeric character) with the
@@ -11847,7 +11929,7 @@ directory, you must use @samp{. ./foo}.
 @prindex @command{!}
 The Unix version 7 shell did not support
 negating the exit status of commands with @command{!}, and this feature
-is still absent from more modern shells (e.g., Solaris @command{/bin/sh}).
+is still absent from some shells (e.g., Solaris @command{/bin/sh}).
 Shell code like this:
 
 @example
@@ -12744,8 +12826,9 @@ newline encoding.
 @item @command{cp}
 @c ---------------
 @prindex @command{cp}
-Avoid the @option{-r} option, since its behavior is not specified by
-Posix.  Use @option{-R} instead.  On @acronym{GNU} hosts the two options
+Avoid the @option{-r} option, since Posix 1003.1-2004 marks it as
+obsolescent and its behavior on special files is implementation-defined.
+Use @option{-R} instead.  On @acronym{GNU} hosts the two options
 are equivalent, but on Solaris hosts (for example) @command{cp -r}
 reads from pipes instead of replicating them.
 
@@ -12756,19 +12839,8 @@ avoid this problem, omit the trailing sl
 /tmp/newdir/} if @file{/tmp/newdir} does not exist.
 
 @c This is thanks to Ian.
-SunOS 4 @command{cp} does not support @option{-f}, although its
address@hidden does.  It's possible to deduce why @command{mv} and
address@hidden are different with respect to @option{-f}.  @command{mv}
-prompts by default before overwriting a read-only file.  @command{cp}
-does not.  Therefore, @command{mv} requires a @option{-f} option, but
address@hidden does not.  @command{mv} and @command{cp} behave differently
-with respect to read-only files because the simplest form of
address@hidden cannot overwrite a read-only file, but the simplest form of
address@hidden can.  This is because @command{cp} opens the target for
-write access, whereas @command{mv} simply calls @code{link} (or, in
-newer systems, @code{rename}).
address@hidden Ian said: ``I don't think -p or -r are portable''!!! How can you 
live
address@hidden without -r???
+The ancient SunOS 4 @command{cp} does not support @option{-f}, although
+its @command{mv} does.
 
 @cindex timestamp resolution
 Traditionally, file timestamps had 1-second resolution, and @samp{cp
@@ -12939,11 +13011,13 @@ expr a : '\(b\)' \| ''
 Unfortunately this behaves exactly as the original expression; see the
 @address@hidden (@samp{|})} entry for more information.
 
-Older @command{expr} implementations (e.g., SunOS 4 @command{expr} and
+Ancient @command{expr} implementations (e.g., SunOS 4 @command{expr} and
 Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
 @command{expr} to fail if the matched substring is longer than 120
 bytes.  In this case, you might want to fall back on @samp{echo|sed} if
address@hidden fails.
address@hidden fails.  Nowadays this is of practical importance only for
+the rare installer who mistakenly puts @file{/usr/ucb} before
address@hidden/usr/bin} in @env{PATH}.
 
 On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in
 some cases.  For example, the command
@@ -13127,35 +13201,16 @@ for symbolic links.
 @c ---------------
 @prindex @command{ls}
 @cindex Listing directories
-The portable options are @option{-acdilrtu}.  Modern practice is for
address@hidden to output both owner and group, but traditional
address@hidden omits the group.
-
address@hidden From Bruce Lilly:
address@hidden
address@hidden # telnet dim
address@hidden [...]
address@hidden   Unix System V (TWG-TCP/IP) (dim.blilly.com)
address@hidden [...]
address@hidden $ mkdir foo
address@hidden $ cd foo
address@hidden $ /bin/ls a.exe 2>/dev/null
address@hidden a.exe not found
address@hidden $ what /bin/ls
address@hidden /bin/ls:
address@hidden           fndcmd:fndcmd.sl 1.68
address@hidden $ uname -a
address@hidden Unix dim SYSTEM5 3.51m mc68k
address@hidden
address@hidden It's an AT&T 3B1.  See http://www.faqs.org/faqs/3b1-faq/ or any
address@hidden mirror of the 3B1 FAQ.  It's actually SVR2.2.
-Modern practice is for all diagnostics to go to standard error, but
-traditional @samp{ls foo} prints the message @samp{foo not found} to
-standard output if @file{foo} does not exist.  Be careful when writing
-shell commands like @samp{sources=`ls *.c 2>/dev/null`}, since with
-traditional @command{ls} this is equivalent to @samp{sources="*.c not
-found"} if there are no @samp{.c} files.
-
+The portable options are @option{-acdilrtu}.  Current practice is for
address@hidden to output both owner and group, even though ancient versions
+of @command{ls} omitted the group.
+
+On ancient hosts, @samp{ls foo} sent the diagnostic @samp{foo not found}
+to standard output if @file{foo} did not exist.  Hence a shell command
+like @samp{sources=`ls *.c 2>/dev/null`} did not always work, since it
+was equivalent to @samp{sources='*.c not found'} in the absence of
address@hidden files.  This is no longer a practical problem, since current
address@hidden implementations send diagnostics to standard error.
 
 @item @command{mkdir}
 @c ------------------
@@ -13329,7 +13384,7 @@ Similarly, @samp{\+} and @samp{\?} shoul
 Anchors (@samp{^} and @samp{$}) inside groups are not portable.
 
 Nested parenthesization in patterns (e.g., @samp{\(\(a*\)b*)\)}) is
-quite portable to modern hosts, but is not supported by some older
+quite portable to current hosts, but was not supported by some ancient
 @command{sed} implementations like SVR3.
 
 Some @command{sed} implementations, e.g., Solaris,
@@ -13493,13 +13548,14 @@ option), @command{touch} typically uses 
 @code{utimes} system call, which can result in the same kind of
 timestamp truncation problems that @samp{cp -p} has.
 
-On some old @acronym{BSD} systems, @command{touch} or any command that
+On ancient @acronym{BSD} systems, @command{touch} or any command that
 results in an empty file does not update the timestamps, so use a
 command like @command{echo} as a workaround.
-
+Also,
 @acronym{GNU} @command{touch} 3.16r (and presumably all before that)
 fails to work on SunOS 4.1.3 when the empty file is on an
 @acronym{NFS}-mounted 4.2 volume.
+However, these problems are no longer of practical concern.
 
 @end table
 
@@ -13830,10 +13886,10 @@ implementations.
 @cindex @code{VPATH} and double-colon rules
 @cindex double-colon rules and @code{VPATH}
 
-Any assignment to @code{VPATH} causes Sun @command{make} to only execute
-the first set of double-colon rules.  (This comment has been here since
-1994 and the context has been lost.  It's probably about SunOS 4.  If
-you can reproduce this, please send us a test case for illustration.)
+With ancient versions of Sun @command{make},
+any assignment to @code{VPATH} @command{make} to only execute
+the first set of double-colon rules.
+However, this problem is no longer of practical concern.
 
 @item @code{$<} not supported in explicit rules
 @cindex explicit rules, @code{$<}, and @code{VPATH}
@@ -13855,34 +13911,35 @@ f.c: if.c
 @cindex @code{VPATH} and automatic rule rewriting
 @cindex automatic rule rewriting and @code{VPATH}
 
-Some @command{make} implementations, such as SunOS 4 @command{make} or
-OSF1/Tru64 @command{make}, will search prerequisites in @code{VPATH} and
-rewrite all their occurrences in the rule appropriately.
-
-For instance
+Some @command{make} implementations, such as Solaris @command{make} and
+OSF1/Tru64 @command{make}, search for prerequisites in @code{VPATH} and
+then rewrite each occurrence as a plain word in the rule.
+For instance:
 
 @example
+# This isn't portable to GNU make.
 VPATH = ../pkg/src
 f.c: if.c
         cp if.c f.c
 @end example
 
 @noindent
-would execute @code{cp ../pkg/src/if.c f.c} if @file{if.c} was
-found in @file{../pkg/src}.  That sounds great.
+executes @code{cp ../pkg/src/if.c f.c} if @file{if.c} is
+found in @file{../pkg/src}.
 
-However, for the sake of other @command{make} implementations, we can't
-rely on this, and we have to search @code{VPATH} manually:
+However, portable makefiles cannot rely on this behavior, and should
+search @code{VPATH} manually.  It is tempting to write this:
 
 @smallexample
+# This isn't portable to Solaris make.
 VPATH = ../pkg/src
 f.c: if.c
         cp `test -f if.c || echo $(VPATH)/`if.c f.c
 @end smallexample
 
 @noindent
-However the "prerequisite rewriting" still applies here.  So if
address@hidden is in @file{../pkg/src}, SunOS 4 @command{make} and OSF1/Tru64
+However the ``prerequisite rewriting'' still applies here.  So if
address@hidden is in @file{../pkg/src}, Solaris @command{make} and OSF1/Tru64
 @command{make} will execute
 
 @smallexample
@@ -13899,17 +13956,30 @@ cp if.c f.c
 @noindent
 and thus fails.  Oops.
 
-One workaround is to make sure that @file{if.c} never appears as a plain word
-in the rule.  For instance these three rules would be safe.
+A simple workaround, and good practice anyway, is to use @samp{$?} and
address@hidden@@} when possible:
 
 @smallexample
 VPATH = ../pkg/src
 f.c: if.c
-        cp `test -f ./if.c || echo $(VPATH)/`if.c f.c
-g.c: ig.c
-        cp `test -f 'ig.c' || echo $(VPATH)/`ig.c g.c
-h.c: ih.c
-        cp `test -f "ih.c" || echo $(VPATH)/`ih.c h.c
+        cp $? $@@
address@hidden smallexample
+
address@hidden
+but this does not generalize well to commands with multiple
+prerequisites.  A more general workaround is to rewrite the rule so that
+the prerequisite @file{if.c} never appears as a plain word.  For
+example, these three rules would be safe, assuming @file{if.c} is in
address@hidden/pkg/src} and the other files are in the working directory:
+
address@hidden
+VPATH = ../pkg/src
+f.c: if.c f1.c
+        cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@@
+g.c: if.c g1.c
+        cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@@
+h.c: if.c h1.c
+        cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@@
 @end smallexample
 
 Things get worse when your prerequisites are in a macro.
@@ -13925,7 +13995,7 @@ install-HEADERS: $(HEADERS)
         done
 @end example
 
-The above @code{install-HEADERS} rule is not SunOS-4-proof because @code{for
+The above @code{install-HEADERS} rule is not Solaris-proof because @code{for
 i in $(HEADERS);} will be expanded as @code{for i in f.h g.h h.h;}
 where @code{f.h} and @code{g.h} are plain words and are hence
 subject to @code{VPATH} adjustments.
@@ -18489,7 +18559,7 @@ introduced in this document.
 @c  LocalWords:  PowerPC GNUC libPW pragma Olibcalls CHOWN chown CLOSEDIR VFORK
 @c  LocalWords:  closedir FNMATCH fnmatch vfork FSEEKO LARGEFILE fseeko SVR sc
 @c  LocalWords:  largefile GETGROUPS getgroups GETLOADAVG DGUX UMAX NLIST KMEM
address@hidden  LocalWords:  GETLODAVG SETGID getloadavg nlist setgid setuid 
GETMNTENT irix
address@hidden  LocalWords:  GETLODAVG SETGID getloadavg nlist GETMNTENT irix
 @c  LocalWords:  getmntent UnixWare GETPGRP getpgid getpgrp Posix's pid LSTAT
 @c  LocalWords:  lstat rpl MEMCMP memcmp OpenStep MBRTOWC mbrtowc MKTIME mktime
 @c  LocalWords:  localtime MMAP mmap OBSTACK obstack obstacks ARGTYPES timeval
@@ -18543,8 +18613,8 @@ introduced in this document.
 @c  LocalWords:  VER Gnulib online xyes strcpy TYPEOF typeof OBJC objcc objc ln
 @c  LocalWords:  GOBJC OBJCCPP OTP ERLC erl valloc decr dumpdef errprint incr
 @c  LocalWords:  esyscmd len maketemp pushdef substr syscmd sysval translit txt
address@hidden  LocalWords:  sinclude foreach myvar tolower toupper uniq 
BASENAME STDIN ig
address@hidden  LocalWords:  Dynix descrips basename aname cname ih 
macroexpands xno xcheck
address@hidden  LocalWords:  sinclude foreach myvar tolower toupper uniq 
BASENAME STDIN
address@hidden  LocalWords:  Dynix descrips basename aname cname macroexpands 
xno xcheck
 @c  LocalWords:  LIBREADLINE lreadline lncurses libreadline
 
 @c Local Variables:
Index: doc/install.texi
===================================================================
RCS file: /cvsroot/autoconf/autoconf/doc/install.texi,v
retrieving revision 1.46
diff -p -u -r1.46 install.texi
--- doc/install.texi    13 Feb 2006 07:59:10 -0000      1.46
+++ doc/install.texi    4 Jun 2006 07:37:23 -0000
@@ -16,7 +16,10 @@ unlimited permission to copy, distribute
 @node Basic Installation
 @section Basic Installation
 
-These are generic installation instructions.
+Briefly, the shell commands @samp{./configure; make; make install}
+should configure, build, and install this package.  The following
+more-detailed instructions are generic; see the @file{README} file for
+instructions specific to this package.
 
 The @command{configure} shell script attempts to guess correct values
 for various system-dependent variables used during compilation.  It uses
@@ -30,8 +33,8 @@ output (useful mainly for debugging @com
 It can also use an optional file (typically called @file{config.cache}
 and enabled with @option{--cache-file=config.cache} or simply
 @option{-C}) that saves the results of its tests to speed up
-reconfiguring.  (Caching is disabled by default to prevent problems with
-accidental use of stale cache files.)
+reconfiguring.  Caching is disabled by default to prevent problems with
+accidental use of stale cache files.
 
 If you need to do unusual things to compile the package, please try to
 figure out how @command{configure} could check whether to do them, and
@@ -41,7 +44,7 @@ cache, and at some point @file{config.ca
 want to keep, you may remove or edit it.
 
 The file @file{configure.ac} (or @file{configure.in}) is used to create
address@hidden by a program called @code{autoconf}.  You only need
address@hidden by a program called @code{autoconf}.  You need
 @file{configure.ac} if you want to change it or regenerate
 @file{configure} using a newer version of @code{autoconf}.
 
@@ -51,12 +54,9 @@ The simplest way to compile this package
 @enumerate
 @item
 @code{cd} to the directory containing the package's source code and type
address@hidden/configure} to configure the package for your system.  If you're
-using @code{csh} on an old version of System V, you might need to type
address@hidden ./configure} instead to prevent @code{csh} from trying to
-execute @command{configure} itself.
address@hidden/configure} to configure the package for your system.
 
-Running @command{configure} takes awhile.  While running, it prints some
+Running @command{configure} might take a while.  While running, it prints some
 messages telling which features it is checking for.
 
 @item
@@ -93,7 +93,7 @@ parameters by setting variables in the c
 Here is an example:
 
 @example
-./configure CC=c89 CFLAGS=-O2 LIBS=-lposix
+./configure CC=c99 CFLAGS=-g LIBS=-lposix
 @end example
 
 @xref{Defining Variables}, for more details.
@@ -104,15 +104,13 @@ Here is an example:
 
 You can compile the package for more than one kind of computer at the
 same time, by placing the object files for each architecture in their
-own directory.  To do this, you must use a version of @command{make}
-that supports the @code{VPATH} variable, such as GNU @command{make}.
+own directory.  To do this, you should use @acronym{GNU} @command{make}.
 @command{cd} to the directory where you want the object files and
 executables to go and run the @command{configure} script.
 @command{configure} automatically checks for the source code in the
 directory that @command{configure} is in and in @file{..}.
 
-If you have to use a @command{make} that does not support the
address@hidden variable, you have to compile the package for one
+With a address@hidden @command{make}, you should compile the package for one
 architecture at a time in the source code directory.  After you have
 installed the package for one architecture, use @samp{make distclean}
 before reconfiguring for another architecture.