FYI: Portable shell is a chapter

[Akim Demaille]

Index: doc/autoconf.texi
===================================================================
RCS file: /cvs/autoconf/doc/autoconf.texi,v
retrieving revision 1.458
diff -u -u -r1.458 autoconf.texi
--- doc/autoconf.texi 2001/06/09 18:39:12 1.458
+++ doc/autoconf.texi 2001/06/09 18:42:48
@@ -137,6 +137,7 @@
 * Setup::                       Initialization and output
 * Existing Tests::              Macros that check for particular features
 * Writing Tests::               How to write new feature checks
+* Portable Shell::              Shell script portability pitfalls
 * Results::                     What to do with results from feature checks
 * Writing Macros::              Adding new macros to Autoconf
 * Manual Configuration::        Selecting features that can't be guessed
@@ -260,7 +261,6 @@
 * Examining Libraries::         Detecting functions and global variables
 * Run Time::                    Testing for run-time features
 * Systemology::                 A zoology of operating systems
-* Portable Shell::              Shell script portability pitfalls
 * Multiple Cases::              Tests for several possible values
 * Language Choice::             Selecting which language to use for testing
 
@@ -4809,7 +4809,7 @@
 
 @c ========================================================= Writing Tests
 
address@hidden Writing Tests, Results, Existing Tests, Top
address@hidden Writing Tests, Portable Shell, Existing Tests, Top
 @chapter Writing Tests
 
 If the existing feature tests don't do something you need, you have to
@@ -4842,7 +4842,6 @@
 * Examining Libraries::         Detecting functions and global variables
 * Run Time::                    Testing for run-time features
 * Systemology::                 A zoology of operating systems
-* Portable Shell::              Shell script portability pitfalls
 * Multiple Cases::              Tests for several possible values
 * Language Choice::             Selecting which language to use for testing
 @end menu
@@ -5136,7 +5135,7 @@
 them, either pass them the correct number of arguments or redeclare them
 with a different return type (such as @code{char}).
 
address@hidden Systemology, Portable Shell, Run Time, Writing Tests
address@hidden Systemology, Multiple Cases, Run Time, Writing Tests
 @section Systemology
 
 This section aims at presenting some systems and pointers to
@@ -5158,9 +5157,112 @@
 @end table
 
 
address@hidden Portable Shell, Multiple Cases, Systemology, Writing Tests
address@hidden Portable Shell Programming
address@hidden Multiple Cases, Language Choice, Systemology, Writing Tests
address@hidden Multiple Cases
+
+Some operations are accomplished in several possible ways, depending on
+the @sc{unix} variant.  Checking for them essentially requires a ``case
+statement''.  Autoconf does not directly provide one; however, it is
+easy to simulate by using a shell variable to keep track of whether a
+way to perform the operation has been found yet.
+
+Here is an example that uses the shell variable @code{fstype} to keep
+track of whether the remaining cases need to be checked.
+
address@hidden
address@hidden
+AC_MSG_CHECKING([how to get file system type])
+fstype=no
+# The order of these tests is important.
+AC_TRY_CPP([#include <sys/statvfs.h>
+#include <sys/fstyp.h>],
+           [AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4])
+if test $fstype = no; then
+  AC_TRY_CPP([#include <sys/statfs.h>
+#include <sys/fstyp.h>],
+             [AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3])
+fi
+if test $fstype = no; then
+  AC_TRY_CPP([#include <sys/statfs.h>
+#include <sys/vmount.h>],
+             [AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX])
+fi
+# (more cases omitted here)
+AC_MSG_RESULT([$fstype])
address@hidden group
address@hidden example
+
address@hidden Language Choice,  , Multiple Cases, Writing Tests
address@hidden Language Choice
address@hidden Language
+
+Autoconf-generated @code{configure} scripts check for the C compiler and
+its features by default.  Packages that use other programming languages
+(maybe more than one, e.g. C and C++) need to test features of the
+compilers for the respective languages.  The following macros determine
+which programming language is used in the subsequent tests in
address@hidden
+
address@hidden AC_LANG (@var{language})
+Do compilation tests using the compiler, preprocessor and file
+extensions for the specified @var{language}.
+
+Supported languages are:
+
address@hidden @samp
address@hidden C
+Do compilation tests using @code{CC} and @code{CPP} and use extension
address@hidden for test programs.
+
address@hidden C++
+Do compilation tests using @code{CXX} and @code{CXXCPP} and use
+extension @file{.C} for test programs.
+
address@hidden Fortran 77
+Do compilation tests using @code{F77} and use extension @file{.f} for
+test programs.
address@hidden table
address@hidden defmac
+
address@hidden AC_LANG_PUSH (@var{language})
address@hidden LANG_PUSH
+Remember the current language (as set by @code{AC_LANG}) on a stack, and
+then select the @var{language}.  Use this macro and @code{AC_LANG_POP}
+in macros that need to temporarily switch to a particular language.
address@hidden defmac
+
address@hidden AC_LANG_POP (@ovar{language})
address@hidden LANG_POP
+Select the language that is saved on the top of the stack, as set by
address@hidden, and remove it from the stack.
+
+If given, @var{language} specifies the language we just @emph{quit}.  It
+is a good idea to specify it when it's known (which should be the
address@hidden), since Autoconf will detect inconsistencies.
+
address@hidden
+AC_LANG_PUSH(Fortran 77)
+# Perform some tests on Fortran 77.
+# ...
+AC_LANG_POP(Fortran 77)
address@hidden example
address@hidden defmac
+
address@hidden AC_REQUIRE_CPP
address@hidden REQUIRE_CPP
+Ensure that whichever preprocessor would currently be used for tests has
+been found.  Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
+argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
+depending on which language is current.
address@hidden defmac
+
+
 
address@hidden ============================================= Portable Shell 
Programming
+
address@hidden Portable Shell, Results, Writing Tests, Top
address@hidden Portable Shell Programming
+
 When writing your own checks, there are some shell-script programming
 techniques you should avoid in order to make your code portable.  The
 Bourne shell and upward-compatible shells like the Korn shell and Bash
@@ -5204,7 +5306,7 @@
 @end menu
 
 @node Shellology, File Descriptors, Portable Shell, Portable Shell
address@hidden Shellology
address@hidden Shellology
 
 There are several families of shells, most prominently the Bourne
 family and the C shell family which are deeply incompatible.  If you
@@ -5310,7 +5412,7 @@
 @end quotation
 
 @node File Descriptors, File System Conventions, Shellology, Portable Shell
address@hidden File Descriptors
address@hidden File Descriptors
 
 Some file descriptors shall not be used, since some systems, admittedly
 arcane, use them for special purpose:
@@ -5379,7 +5481,7 @@
 good address@hidden
 
 @node File System Conventions, Shell Substitutions, File Descriptors, Portable 
Shell
address@hidden File System Conventions
address@hidden File System Conventions
 
 While @command{autoconf} and friends will usually be run on some Unix
 variety, it can and will be used on other systems, most notably @sc{dos}
@@ -5495,7 +5597,7 @@
 @end table
 
 @node Shell Substitutions, Assignments, File System Conventions, Portable Shell
address@hidden Shell Substitutions
address@hidden Shell Substitutions
 
 Contrary to a persistent urban legend, the Bourne shell does not
 systematically split variables and backquoted expressions, in particular
@@ -5689,7 +5791,7 @@
 
 
 @node Assignments, Special Shell Variables, Shell Substitutions, Portable Shell
address@hidden Assignments
address@hidden Assignments
 
 When setting several variables in a row, be aware that the order of the
 evaluation is undefined.  For instance @samp{foo=1 foo=2; echo $foo}
@@ -5759,7 +5861,7 @@
 
 
 @node Special Shell Variables, Limitations of Builtins, Assignments, Portable 
Shell
address@hidden Special Shell Variables
address@hidden Special Shell Variables
 
 Some shell variables should not be used, since they can have a deep
 influence on the behavior of the shell.  In order to recover a sane
@@ -5887,7 +5989,7 @@
 
 
 @node Limitations of Builtins, Limitations of Usual Tools, Special Shell 
Variables, Portable Shell
address@hidden Limitations of Shell Builtins
address@hidden Limitations of Shell Builtins
 
 No, no, we are serious: some shells do have limitations! :)
 
@@ -6362,7 +6464,7 @@
 @end table
 
 @node Limitations of Usual Tools, Limitations of Make, Limitations of 
Builtins, Portable Shell
address@hidden Limitations of Usual Tools
address@hidden Limitations of Usual Tools
 
 The small set of tools you can expect to find on any machine can still
 include some limitations you should be aware of.
@@ -6781,7 +6883,7 @@
 
 
 @node Limitations of Make,  , Limitations of Usual Tools, Portable Shell
address@hidden Limitations of Make
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
@@ -6795,109 +6897,11 @@
 @end table
 
 
address@hidden Multiple Cases, Language Choice, Portable Shell, Writing Tests
address@hidden Multiple Cases
-
-Some operations are accomplished in several possible ways, depending on
-the @sc{unix} variant.  Checking for them essentially requires a ``case
-statement''.  Autoconf does not directly provide one; however, it is
-easy to simulate by using a shell variable to keep track of whether a
-way to perform the operation has been found yet.
-
-Here is an example that uses the shell variable @code{fstype} to keep
-track of whether the remaining cases need to be checked.
-
address@hidden
address@hidden
-AC_MSG_CHECKING([how to get file system type])
-fstype=no
-# The order of these tests is important.
-AC_TRY_CPP([#include <sys/statvfs.h>
-#include <sys/fstyp.h>],
-           [AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4])
-if test $fstype = no; then
-  AC_TRY_CPP([#include <sys/statfs.h>
-#include <sys/fstyp.h>],
-             [AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3])
-fi
-if test $fstype = no; then
-  AC_TRY_CPP([#include <sys/statfs.h>
-#include <sys/vmount.h>],
-             [AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX])
-fi
-# (more cases omitted here)
-AC_MSG_RESULT([$fstype])
address@hidden group
address@hidden example
-
address@hidden Language Choice,  , Multiple Cases, Writing Tests
address@hidden Language Choice
address@hidden Language
-
-Autoconf-generated @code{configure} scripts check for the C compiler and
-its features by default.  Packages that use other programming languages
-(maybe more than one, e.g. C and C++) need to test features of the
-compilers for the respective languages.  The following macros determine
-which programming language is used in the subsequent tests in
address@hidden
-
address@hidden AC_LANG (@var{language})
-Do compilation tests using the compiler, preprocessor and file
-extensions for the specified @var{language}.
-
-Supported languages are:
-
address@hidden @samp
address@hidden C
-Do compilation tests using @code{CC} and @code{CPP} and use extension
address@hidden for test programs.
-
address@hidden C++
-Do compilation tests using @code{CXX} and @code{CXXCPP} and use
-extension @file{.C} for test programs.
-
address@hidden Fortran 77
-Do compilation tests using @code{F77} and use extension @file{.f} for
-test programs.
address@hidden table
address@hidden defmac
-
address@hidden AC_LANG_PUSH (@var{language})
address@hidden LANG_PUSH
-Remember the current language (as set by @code{AC_LANG}) on a stack, and
-then select the @var{language}.  Use this macro and @code{AC_LANG_POP}
-in macros that need to temporarily switch to a particular language.
address@hidden defmac
-
address@hidden AC_LANG_POP (@ovar{language})
address@hidden LANG_POP
-Select the language that is saved on the top of the stack, as set by
address@hidden, and remove it from the stack.
-
-If given, @var{language} specifies the language we just @emph{quit}.  It
-is a good idea to specify it when it's known (which should be the
address@hidden), since Autoconf will detect inconsistencies.
-
address@hidden
-AC_LANG_PUSH(Fortran 77)
-# Perform some tests on Fortran 77.
-# ...
-AC_LANG_POP(Fortran 77)
address@hidden example
address@hidden defmac
-
address@hidden AC_REQUIRE_CPP
address@hidden REQUIRE_CPP
-Ensure that whichever preprocessor would currently be used for tests has
-been found.  Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
-argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
-depending on which language is current.
address@hidden defmac
 
 
 @c ====================================================== Results of Tests.
 
address@hidden Results, Writing Macros, Writing Tests, Top
address@hidden Results, Writing Macros, Portable Shell, Top
 @chapter Results of Tests
 
 Once @code{configure} has determined whether a feature exists, what can