FYI: Here documents as a section

[Akim Demaille]

The point of Shellology is not to list the problems of this or that
shell, rather it is meant to present them.  The pitfalls are to be
classified.

Index: ChangeLog
from  Akim Demaille  <address@hidden>
        * doc/autoconf.texi (Here-Documents): New section, gathering
        documentation about here-documents.
        Use `href', not `uref', and other changes.

Index: TODO
===================================================================
RCS file: /cvs/autoconf/TODO,v
retrieving revision 1.106
diff -u -u -r1.106 TODO
--- TODO 2001/06/01 13:40:06 1.106
+++ TODO 2001/06/11 08:20:33
@@ -7,7 +7,7 @@
 
 ------------------------------------------------------------------------------
 
-* Autoconf 2.51
+* Soon
 
 ** --target & AC_ARG_PROGRAM
 Shouldn't *any* `program' be installed as `$target_alias-program' even
@@ -15,7 +15,7 @@
 Ian?
 
 ** Document
-Automake, Libtool, AC_ARG_VAR.
+AC_ARG_VAR, m4_pattrern_*
 
 ** RedHat's Autoconf page
 should be removed.
@@ -23,6 +23,11 @@
 ** AC_CHECK_TOOL...
 Write a test that checks that it honors the values set by the user.
 
+* Autoconf 2.52 or later
+
+** Languages
+Integrate other Fortrans etc.
+
 ** AC_CHECK_FUNCS and AC_TRY_LINK_FUNC
 I have still not understood what's the difference  between the two
 which requires to have two different sources: AC_LANG_CALL and
@@ -47,8 +52,6 @@
 specializing macros will call them.  OTOH, this doubles our work,
 since specializing macros will save us from additional typing.  But
 the more powerful autoscan is, the better...
-
-* Autoconf 2.51 or later
 
 ** Libtool
 Define once for all the hooks they need, any redefinition of
Index: doc/autoconf.texi
===================================================================
RCS file: /cvs/autoconf/doc/autoconf.texi,v
retrieving revision 1.459
diff -u -u -r1.459 autoconf.texi
--- doc/autoconf.texi 2001/06/09 18:45:00 1.459
+++ doc/autoconf.texi 2001/06/11 08:20:38
@@ -273,6 +273,7 @@
 Portable Shell Programming
 
 * Shellology::                  A zoology of shells
+* Here-Documents::              Quirks and tricks
 * File Descriptors::            FDs and redirections
 * File System Conventions::     File- and pathnames
 * Shell Substitutions::         Variable and command expansions
@@ -603,28 +604,29 @@
 @item Web
 
 The home pages for
address@hidden://www.gnu.org/software/autoconf/,Autoconf},
address@hidden://www.gnu.org/software/automake/,Automake}, and
address@hidden://www.gnu.org/software/libtool/,Libtool}.
address@hidden://www.gnu.org/software/autoconf/,Autoconf},
address@hidden://www.gnu.org/software/automake/,Automake}, and
address@hidden://www.gnu.org/software/libtool/,Libtool}.
 
address@hidden Automake Manual (TeXinfo)
address@hidden Automake Manual
 
 @xref{Top,,Automake,automake,GNU Automake}, for more
 information on Automake.
 
 @item Books
 
-The book @cite{GNU Autoconf, Automake and Libtool}, by G. V. Vaughan,
-B. Elliston, T. Tromey, and I. L. Taylor (New Riders, 2000) (ISBN
-1578701902) describes the complete GNU build environment.  You can also
-find the entire book on-line at
address@hidden://sources.redhat.com/autobook/,``The Goat Book'' home page}.
+The book @cite{GNU Autoconf, Automake and address@hidden@cite{GNU
+Autoconf, Automake and Libtool}, by G. V. Vaughan, B. Elliston,
+T. Tromey, and I. L. Taylor. New Riders, 2000, ISBN 1578701902.}
+describes the complete GNU build environment.  You can also find the
+entire book on-line at @href{http://sources.redhat.com/autobook/,``The
+Goat Book'' home page}.
 
 @item Tutorials and Examples
 
-The @uref{http://sources.redhat.com/autoconf/,Autoconf Developer Page}
+The @href{http://sources.redhat.com/autoconf/,Autoconf Developer Page}
 maintains links to a number of Autoconf/Automake tutorials online, and
-also links to the @uref{http://www.gnu.org/software/ac-archive/,
+also links to the @href{http://www.gnu.org/software/ac-archive/,
 Autoconf Macro Archive}.
 
 @end itemize
@@ -1289,17 +1291,18 @@
 
 @example
 @group
-$ autoconf -t 'AC_SUBST:address@hidden"$1"@} = "$f:$l";'
address@hidden"ECHO_C"@} = "configure.ac:2";
address@hidden"ECHO_N"@} = "configure.ac:2";
address@hidden"ECHO_T"@} = "configure.ac:2";
+$ autoconf -t 'AC_SUBST:address@hidden"$1"@} = "$f:$l";'
address@hidden"ECHO_C"@} = "configure.ac:2";
address@hidden"ECHO_N"@} = "configure.ac:2";
address@hidden"ECHO_T"@} = "configure.ac:2";
 @i{More traces deleted}
 @end group
 @end example
 
 @noindent
 A long @var{separator} can be used to improve the readability of complex
-structures:
+structures, and to ease its parsing (for instance when no single
+character is suitable as a separator)):
 
 @example
 @group
@@ -4724,7 +4727,7 @@
 @cvindex _LARGE_FILES
 @ovindex CC
 Arrange for
address@hidden://www.sas.com/standards/large.file/x_open.20Mar96.html,
address@hidden://www.sas.com/standards/large.file/x_open.20Mar96.html,
 large-file support}.  On some hosts, one must use special compiler
 options to build programs that can access large files.  Append any such
 options to the output variable @code{CC}.  Define
@@ -5295,6 +5298,7 @@
 
 @menu
 * Shellology::                  A zoology of shells
+* Here-Documents::              Quirks and tricks
 * File Descriptors::            FDs and redirections
 * File System Conventions::     File- and pathnames
 * Shell Substitutions::         Variable and command expansions
@@ -5305,7 +5309,7 @@
 * Limitations of Make::         Portable Makefiles
 @end menu
 
address@hidden Shellology, File Descriptors, Portable Shell, Portable Shell
address@hidden Shellology, Here-Documents, Portable Shell, Portable Shell
 @section Shellology
 
 There are several families of shells, most prominently the Bourne
@@ -5358,15 +5362,6 @@
 Mode,, Bash @sc{posix} Mode, bash, The GNU Bash Reference Manual}, for
 details.
 
address@hidden @command{/bin/sh} on OpenBSD
address@hidden @command{/bin/sh} on OpenBSD
-
address@hidden"} expands to @samp{"} in here-documents with unquoted
-delimiter in the native @command{/bin/sh} on OpenBSD 2.7.  As a general
-rule, if @samp{\\} expands to @samp{\} use @samp{\\} to get @samp{\}.
-Don't rely on @samp{\} being preserved just because it has no special
-meaning together with the next symbol.
-
 @item @command{/usr/xpg4/bin/sh} on Solaris
 @cindex @command{/usr/xpg4/bin/sh} on Solaris
 The @sc{posix}-compliant Bourne shell on a Solaris system is
@@ -5381,6 +5376,8 @@
 compatible with the Bourne shell: you have to run @samp{emulate sh} and
 set @code{NULLCMD} to @samp{:}. @xref{Compatibility,, Compatibility,
 zsh, The Z Shell Manual}, for details.
+
+Zsh 3.0.8 is the native @command{/bin/sh} on Mac OS X 10.0.3.
 @end table
 
 The following discussion between Russ Allbery and Robert Lipe is worth
@@ -5410,8 +5407,78 @@
 So while most modern systems do have a shell _somewhere_ that meets the
 @sc{posix} standard, the challenge is to find it.
 @end quotation
+
address@hidden Here-Documents, File Descriptors, Shellology, Portable Shell
address@hidden Here-Documents
+
+Don't rely on @samp{\} being preserved just because it has no special
+meaning together with the next symbol.  in the native @command{/bin/sh}
+on OpenBSD 2.7 @samp{\"} expands to @samp{"} in here-documents with
+unquoted delimiter.  As a general rule, if @samp{\\} expands to @samp{\}
+use @samp{\\} to get @samp{\}.
+
+With OpenBSD 2.7's @command{/bin/sh}
+
address@hidden
address@hidden
+$ cat <<EOF
+> \" \\
+> EOF
+" \
address@hidden group
address@hidden example
+
address@hidden
+and with Bash:
+
address@hidden
address@hidden
+bash-2.04$ cat <<EOF
+> \" \\
+> EOF
+\" \
address@hidden group
address@hidden example
+
+
+Many older shells (including the Bourne shell) implement here-documents
+inefficiently.  Users can generally speed things up by using a faster
+shell, e.g., by using the command @samp{bash ./configure} rather than
+plain @samp{./configure}.
+
+Some shells can be extremely inefficient when there are a lot of
+here-documents inside a single statement.  For instance if your
address@hidden includes something like:
+
address@hidden
address@hidden
+if <cross_compiling>; then
+  assume this and that
+else
+  check this
+  check that
+  check something else
+  on and on forever
+fi
address@hidden group
address@hidden example
 
address@hidden File Descriptors, File System Conventions, Shellology, Portable 
Shell
+A shell parses the whole @code{if}/@code{fi} construct, creating
+temporary files for each here document in it.  Some shells create links
+for such here-documents on every @code{fork ()}, so that the clean-up
+code they had installed correctly removes them.  It is creating the
+links that the shell can take forever.
+
+Moving the tests out of the @code{if}/@code{fi}, or creating multiple
address@hidden/@code{fi} constructs, would improve the performance
+significantly.  Anyway, this kind of construct is not exactly the
+typical use of Autoconf.  In fact, it's even not recommended, because M4
+macros can't look into shell conditionals, so we may fail to expand a
+macro when it was expanded before in a conditional path, and the
+condition turned out to be false at run-time, and we end up not
+executing the macro at all.
+
address@hidden File Descriptors, File System Conventions, Here-Documents, 
Portable Shell
 @section File Descriptors
 
 Some file descriptors shall not be used, since some systems, admittedly
@@ -5527,10 +5594,10 @@
 File names need extra care as well.  While @sc{dos}-based environments
 that are Unixy enough to run @command{autoconf} (such as DJGPP) will
 usually be able to handle long file names properly, there are still
-limitations that can seriously break packages.  Several of these issues can
-be easily detected by
address@hidden://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, the doschk
-package}.
+limitations that can seriously break packages.  Several of these issues
+can be easily detected by the
address@hidden://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
+package.
 
 A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
 indicate where they apply: @sc{sfn} means the issues are only relevant to
@@ -6071,43 +6138,6 @@
 $foo
 EOF
 @end example
-
-Many older shells (including the Bourne shell) implement here-documents
-inefficiently.  Users can generally speed things up by using a faster
-shell, e.g., by using the command @samp{bash ./configure} rather than
-plain @samp{./configure}.
-
-Some shells can be extremely inefficient when there are a lot of
-here-documents inside a single statement.  For instance if your
address@hidden includes something like:
-
address@hidden
address@hidden
-if <cross_compiling>; then
-  assume this and that
-else
-  check this
-  check that
-  check something else
-  on and on forever
-fi
address@hidden group
address@hidden example
-
-A shell parses the whole @code{if}/@code{fi} construct, creating
-temporary files for each here document in it.  Some shells create links
-for such here-documents on every @code{fork ()}, so that the clean-up
-code they had installed correctly removes them.  It is creating the
-links that the shell can take forever.
-
-Moving the tests out of the @code{if}/@code{fi}, or creating multiple
address@hidden/@code{fi} constructs, would improve the performance
-significantly.  Anyway, this kind of construct is not exactly the
-typical use of Autoconf.  In fact, it's even not recommended, because M4
-macros can't look into shell conditionals, so we may fail to expand a
-macro when it was expanded before in a conditional path, and the
-condition turned out to be false at run-time, and we end up not
-executing the macro at all.
 
 
 @item @command{exit}