02-fyi-doc-limitations.patch

[Akim Demaille]

Index: ChangeLog
from  Akim Demaille  <address@hidden>
        * doc/autoconf.texi: Lots of additions and changes.
        (File Descriptors): New.
        (Limitations of Make): New.
        
        
Index: acgeneral.m4
--- acgeneral.m4 Sat, 13 Jan 2001 11:47:33 +0100 akim (ace/27_acgeneral. 
1.169.8.110 666)
+++ acgeneral.m4 Mon, 15 Jan 2001 23:06:36 +0100 akim (ace/27_acgeneral. 
1.169.8.110 666)
@@ -704,7 +704,7 @@ m4_define([_AC_INIT_COPYRIGHT],
 
 m4_define([AS_MESSAGE_FD], 6)
 m4_define([AS_MESSAGE_LOG_FD], 5)
-# That's how trey used to be named.
+# That's how they used to be named.
 AU_ALIAS([AC_FD_CC],  [AS_MESSAGE_LOG_FD])
 AU_ALIAS([AC_FD_MSG], [AS_MESSAGE_FD])
 
@@ -713,8 +713,6 @@ m4_define([_AC_INIT_DEFAULTS_FDS],
 # 0 standard input
 # 1 file creation
 # 2 errors and warnings
-# 3 some systems may open it to /dev/tty
-# 4 used on the Kubota Titan
 @%:@ AS_MESSAGE_FD checking for... messages and results
 @%:@ AS_MESSAGE_LOG_FD compiler messages saved in config.log
 if test "$silent" = yes; then
@@ -3756,9 +3754,8 @@ m4_define([AC_OUTPUT],
 # Let make expand exec_prefix.
 test "x$exec_prefix" = xNONE && exec_prefix='${prefix}'
 
-# Any assignment to VPATH causes Sun make to only execute
-# the first set of double-colon rules, so remove it if not needed.
-# If there is a colon in the path, we need to keep it.
+# VPATH is dangerous, but if there is a colon in the path, we need to
+# keep it.
 if test "x$srcdir" = x.; then
   ac_vpsub=['/^[       ]*VPATH[        ]*=[^:]*$/d']
 fi
Index: doc/autoconf.texi
--- doc/autoconf.texi Mon, 15 Jan 2001 22:19:59 +0100 akim (ace/16_autoconf.t 
1.61.2.98 666)
+++ doc/autoconf.texi Mon, 15 Jan 2001 23:19:50 +0100 akim (ace/16_autoconf.t 
1.61.2.98 666)
@@ -152,8 +152,7 @@ @node Top, Introduction, (dir), (dir)
 * Macro Index::                 Index of Autoconf macros
 * Concept Index::               General index
 
address@hidden
- --- The Detailed Node Listing ---
address@hidden --- The Detailed Node Listing ---
 
 Making @code{configure} Scripts
 
@@ -207,8 +206,8 @@ @node Top, Introduction, (dir), (dir)
 * Structures::                  Structures or members that might be missing
 * Types::                       Types that might be missing
 * Compilers and Preprocessors::  Checking for compiling programs
-* C Compiler Characteristics::
-* Fortran 77 Compiler Characteristics::
+* C Compiler::                  Checking its characteristics
+* Fortran 77 Compiler::         Checking its characteristics
 * System Services::             Operating system services
 * UNIX Variants::               Special kludges for specific UNIX variants
 
@@ -267,11 +266,13 @@ @node Top, Introduction, (dir), (dir)
 Portable Shell Programming
 
 * Shellology::                  A zoology of shells
-* Shell Substitutions::         Variable expansions...
+* File Descriptors::            FDs and redirections
+* Shell Substitutions::         Variable and command expansions
 * Assignments::                 Varying side effects of assignments
 * Special Shell Variables::     Variables you should not change
 * Limitations of Builtins::     Portable use of not so portable /bin/sh
 * Limitations of Usual Tools::  Portable use of portable tools
+* Limitations of Make::         Portable Makefiles
 
 Results of Tests
 
@@ -2571,8 +2572,8 @@ @node Existing Tests, Writing Tests, Set
 * Structures::                  Structures or members that might be missing
 * Types::                       Types that might be missing
 * Compilers and Preprocessors::  Checking for compiling programs
-* C Compiler Characteristics::
-* Fortran 77 Compiler Characteristics::
+* C Compiler::                  Checking its characteristics
+* Fortran 77 Compiler::         Checking its characteristics
 * System Services::             Operating system services
 * UNIX Variants::               Special kludges for specific UNIX variants
 @end menu
@@ -4059,7 +4060,7 @@ @node Generic Types,  , Particular Types
 @code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
 
 
address@hidden Compilers and Preprocessors, C Compiler Characteristics, Types, 
Existing Tests
address@hidden Compilers and Preprocessors, C Compiler, Types, Existing Tests
 @section Compilers and Preprocessors
 
 @ovindex EXEEXT
@@ -4250,7 +4251,7 @@ @node Compilers and Preprocessors, C Com
 @end defmac
 
 
address@hidden C Compiler Characteristics, Fortran 77 Compiler Characteristics, 
Compilers and Preprocessors, Existing Tests
address@hidden C Compiler, Fortran 77 Compiler, Compilers and Preprocessors, 
Existing Tests
 @section C Compiler Characteristics
 
 The following macros check for C compiler or machine architecture
@@ -4407,7 +4408,7 @@ @node C Compiler Characteristics, Fortra
 
 
 
address@hidden Fortran 77 Compiler Characteristics, System Services, C Compiler 
Characteristics, Existing Tests
address@hidden Fortran 77 Compiler, System Services, C Compiler, Existing Tests
 @section Fortran 77 Compiler Characteristics
 
 The following macros check for Fortran 77 compiler characteristics.  To
@@ -4519,7 +4520,7 @@ @node Fortran 77 Compiler Characteristic
 language other than C/C++.
 @end defmac
 
address@hidden System Services, UNIX Variants, Fortran 77 Compiler 
Characteristics, Existing Tests
address@hidden System Services, UNIX Variants, Fortran 77 Compiler, Existing 
Tests
 @section System Services
 
 The following macros check for operating system services or capabilities.
@@ -5050,14 +5051,16 @@ @node Portable Shell, Multiple Cases, Sy
 
 @menu
 * Shellology::                  A zoology of shells
-* Shell Substitutions::         Variable expansions...
+* File Descriptors::            FDs and redirections
+* Shell Substitutions::         Variable and command expansions
 * Assignments::                 Varying side effects of assignments
 * Special Shell Variables::     Variables you should not change
 * Limitations of Builtins::     Portable use of not so portable /bin/sh
 * Limitations of Usual Tools::  Portable use of portable tools
+* Limitations of Make::         Portable Makefiles
 @end menu
 
address@hidden Shellology, Shell Substitutions, Portable Shell, Portable Shell
address@hidden Shellology, File Descriptors, Portable Shell, Portable Shell
 @subsection Shellology
 
 There are several families of shells, most prominently the Bourne
@@ -5068,15 +5071,15 @@ @node Shellology, Shell Substitutions, P
 Below we describe some of the members of the Bourne shell family.
 
 @table @asis
address@hidden @command{ash}
address@hidden @command{ash}
address@hidden Ash
address@hidden Ash
 @command{ash} is often used on @sc{gnu}/Linux and @sc{bsd} systems as a
-light-weight Bourne-compatible shell.  @command{ash} version 0.2 has
-some bugs that are fixed in the 0.3.x series, but portable shell scripts
-should workaround them, since version 0.2 is still shipped with many
address@hidden/Linux distributions.
+light-weight Bourne-compatible shell.  Ash 0.2 has some bugs that are
+fixed in the 0.3.x series, but portable shell scripts should workaround
+them, since version 0.2 is still shipped with many @sc{gnu}/Linux
+distributions.
 
-To be compatible with @command{ash} 0.2
+To be compatible with Ash 0.2:
 
 @itemize @bullet
 @item
@@ -5097,18 +5100,13 @@ @node Shellology, Shell Substitutions, P
 @end example
 
 @item
-beware that @command{exit} inside command substitution causes the
-current shell to exit as well. Use parentheses to prevent @command{ash}
-from exiting:
-
address@hidden
-(`exit 1`) || echo "All right"
-`exit 1` || echo "ash won't print it"
address@hidden example
+beware that single builtin substitutions are not performed by a sub
+shell, hence their effect applies to the current shell!  @xref{Shell
+Substitutions}, item ``Command Substitution''.
 @end itemize
 
address@hidden @command{bash}
address@hidden @command{bash}
address@hidden Bash
address@hidden Bash
 To detect whether you are running @command{bash}, test if
 @code{BASH_VERSION} is set.  To disable its extensions and require
 @sc{posix} compatibility, run @samp{set -o posix}. @xref{Bash POSIX
@@ -5122,8 +5120,8 @@ @node Shellology, Shell Substitutions, P
 There is no extra charge for this package, but it is also not part of a
 minimal OS install and therefore some folks may not have it.
 
address@hidden @command{zsh}
address@hidden @command{zsh}
address@hidden Zsh
address@hidden Zsh
 To detect whether you are running @command{zsh}, test if
 @code{ZSH_VERSION} is set.  By default @command{zsh} is @emph{not}
 compatible with the Bourne shell: you have to run @samp{emulate sh} and
@@ -5159,13 +5157,46 @@ @node Shellology, Shell Substitutions, P
 @sc{posix} standard, the challenge is to find it.
 @end quotation
 
address@hidden File Descriptors, Shell Substitutions, Shellology, Portable Shell
address@hidden File Descriptors
+
+Some file descriptors shall not be used, since some systems, admittedly
+arcane, use them for special purpose:
+
address@hidden @asis
address@hidden 3
+some systems may open it to @samp{/dev/tty}.
 
address@hidden Shell Substitutions, Assignments, Shellology, Portable Shell
address@hidden 4
+used on the Kubota Titan.
address@hidden table
+
+Don't redirect several times the same file descriptor, as you are doomed
+to failure under Ultrix.
+
address@hidden FIXME: Check the exact messages sent by Harlan.
address@hidden
+ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
+UWS V4.4 (Rev. 11)
+$ eval 'echo foo >/tmp/bar' >/tmp/baz
+illegal io
+$ eval '(echo foo >/tmp/bar)' >/tmp/baz
+illegal io
+$ (eval '(echo foo >/tmp/bar)') >/tmp/baz
+Ambiguous output redirect.
address@hidden example
+
address@hidden
+In each case the expected result is of course @file{/tmp/bar} containing
address@hidden and @file{/tmp/baz} being empty.
+
address@hidden Shell Substitutions, Assignments, File Descriptors, Portable 
Shell
 @subsection Shell Substitutions
 
 Contrary to a persistent urban legend, the Bourne shell does not
-systematically split variables and backquoted expressions, in
-particular, the following code:
+systematically split variables and backquoted expressions, in particular
+on the right-hand side of assignments, and the argument of @code{case}.
+For instance the following code:
 
 @example
 case "$given_srcdir" in
@@ -5175,8 +5206,7 @@ @node Shell Substitutions, Assignments, 
 @end example
 
 @noindent
-is more readable with the right-hand side of the assignments, and the
-argument of @code{case} left without quotes:
+is more readable written as:
 
 @example
 case $given_srcdir in
@@ -5198,7 +5228,7 @@ @node Shell Substitutions, Assignments, 
 @cindex @samp{"$@@"}
 One of the most famous shell portability issues is related to
 @samp{"$@@"}: when there are no positional argument, it is supposed to
-be equivalent to nothing.  But some shell, for instance under Digital
+be equivalent to nothing.  But some shells, for instance under Digital
 Unix 4.0 and 5.0, will then replace it with an empty argument.  To be
 portable, use @address@hidden"$@@"@}}.
 
@@ -5307,6 +5337,27 @@ @node Shell Substitutions, Assignments, 
 @end example
 
 
address@hidden address@hidden
address@hidden address@hidden
address@hidden Command Substitution
+While in general it makes no sense, do not substitute a single builtin
+with side effects as Ash 0.2, trying to optimize, does not fork a sub
+shell to perform the command.
+
+For instance if you wanted to check that @command{cd} is silent, do not
+use @samp{test -z "`cd /tmp`"} because...
+
address@hidden
+$ pwd
+/tmp
+$ test -n "`cd /`" && pwd
+/
address@hidden example
+
address@hidden
+The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
+
+
 @item $(@var{commands})
 @cindex $(@var{commands})
 This construct is meant to replace @address@hidden; they can be
@@ -5586,7 +5637,7 @@ @node Limitations of Builtins, Limitatio
 @c -----------------
 @cindex @command{exit}
 The default value of @command{exit} is supposed to be @code{$?},
-unfortunately some shell, such as the @sc{djgpp} port of Bash 2.04, just
+unfortunately some shells, such as the @sc{djgpp} port of Bash 2.04, just
 perform @samp{exit 0}.
 
 @example
@@ -5683,6 +5734,7 @@ @node Limitations of Builtins, Limitatio
 @end example
 
 @item @command{if}
address@hidden ---------------
 @cindex @command{if}
 Using @samp{!} is not portable.  Instead of
 
@@ -5701,6 +5753,28 @@ @node Limitations of Builtins, Limitatio
 fi
 @end example
 
+There are shells which do not reset the exit status out of an
address@hidden:
+
address@hidden
+$ if (exit 42); then true; fi; echo $?
+42
address@hidden example
+
address@hidden
+while a proper shell should have printed @samp{0}.  This is especially
+bad in Makefiles since it produces false failures.  This is why properly
+written Makefiles, such as Automake's, have such hairy constructs:
+
address@hidden
+if test -f "$file"; then
+  install "$file" "$dest"
+else
+  :
+fi
address@hidden example
+
+
 @item @command{set}
 @c ----------------
 @cindex @command{set}
@@ -5743,6 +5817,7 @@ @node Limitations of Builtins, Limitatio
 @samp{test ! -r foo || exit 1}.
 
 @item @command{test} (files)
address@hidden -------------------------
 To enable @code{configure} scripts to support cross-compilation, they
 shouldn't do anything that tests features of the build system instead of
 the host system.  But occasionally you may find it necessary to check
@@ -5752,6 +5827,7 @@ @node Limitations of Builtins, Limitatio
 have it.
 
 @item @command{test} (strings)
address@hidden ---------------------------
 Avoid @samp{test "@var{string}"}, in particular if @var{string} might
 start with a dash, since @code{test} might interpret its argument as an
 option (e.g., @address@hidden = "-n"}).
@@ -5911,7 +5987,7 @@ @node Limitations of Builtins, Limitatio
 the case of environment variables.
 @end table
 
address@hidden Limitations of Usual Tools,  , Limitations of Builtins, Portable 
Shell
address@hidden Limitations of Usual Tools, Limitations of Make, Limitations of 
Builtins, Portable Shell
 @subsection Limitations of Usual Tools
 
 The small set of tools you can expect to find on any machine can still
@@ -6290,6 +6366,20 @@ @node Limitations of Usual Tools,  , Lim
 s/.*/deleted/g
 : end
 @end example
address@hidden table
+
address@hidden Limitations of Make,  , Limitations of Usual Tools, Portable 
Shell
address@hidden Limitations of Make
+
+Make itself suffers a great number of limitations, only a few of which
+being listed here.  First of all, remember that since commands are
+executed by the shell, all its weaknesses are inherited...
+
address@hidden @asis
address@hidden @code{VPATH}
address@hidden @code{VPATH}
+Don't use it!  For instance any assignment to @code{VPATH} causes Sun
address@hidden to only execute the first set of double-colon rules.
 @end table