Merge of unposted revision 1.10: alter reference to process substitutions in redriction docs.

1 files changed, 55 insertions, 6 deletions

diff --git a/Doc/Zsh/redirect.yo b/Doc/Zsh/redirect.yo
index d6d662d4a..f192470bc 100644
--- a/Doc/Zsh/redirect.yo
+++ b/Doc/Zsh/redirect.yo
@@ -70,12 +70,22 @@ occurs, `tt(\)' followed by a newline is removed,
 and `tt(\)' must be used to quote the characters
 `tt(\)', `tt($)', `tt(`)' and the first character of var(word).
 
+Note that var(word) itself does not undergo shell expansion.  Backquotes
+in var(word) do not have their usual effect; instead they behave
+similarly to double quotes, except that the backquotes themselves are
+passed through unchanged.  (This information is given for completeness
+and it is not recommended that backquotes be used.)  Quotes in the form
+tt($')var(...)tt(') have their standard effect of expanding backslashed
+references to special characters.
+
 If tt(<<-) is used, then all leading
 tabs are stripped from var(word) and from the document.
 )
 item(tt(<<<) var(word))(
 Perform shell expansion on var(word) and pass the result
 to standard input.  This is known as a em(here-string).
+Compare the use of var(word) in here-documents above, where var(word)
+does not undergo shell expansion.
 )
 xitem(tt(<&) var(number))
 item(tt(>&) var(number))(
@@ -138,12 +148,29 @@ If the order of redirections were reversed,
 file descriptor 2 would be associated
 with the terminal (assuming file descriptor 1 had been)
 and then file descriptor 1 would be associated with file var(fname).
+
+The `tt(|&)' command separator described in
+ifzman(em(Simple Commands & Pipelines) in zmanref(zshmisc))\
+ifnzman(noderef(Simple Commands & Pipelines))
+is a shorthand for `tt(2>&1 |)'.
+
+The various forms of process substitution, `tt(<LPAR())var(list)tt(RPAR())',
+and `tt(=LPAR())var(list)(RPAR())' for input and
+`tt(>LPAR())var(list)tt(RPAR())' for output, are often used together with
+redirection.  For example, if var(word) in an output redirection is of the
+form `tt(>LPAR())var(list)tt(RPAR())' then the output is piped to the
+command represented by var(list).  See
+ifzman(\
+em(Process Substitution) in zmanref(zshexpn))\
+ifnzman(\
+noderef(Process Substitution)).
 sect(Multios)
+cindex(multios)
 pindex(MULTIOS, use of)
 If the user tries to open a file descriptor for writing more than once,
 the shell opens the file descriptor as a pipe to a process that copies
 its input to all the specified outputs, similar to bf(tee),
-provided the tt(MULTIOS) option is set.  Thus:
+provided the tt(MULTIOS) option is set, as it is by default.  Thus:
 
 example(date >foo >bar)
 
@@ -195,23 +222,45 @@ example(echo foo > bar > baz)
 
 when tt(MULTIOS) is unset will truncate bar, and write `tt(foo)' into baz.
 
+There is a problem when an output multio is attached to an external
+program.  A simple example shows this:
+
+example(cat file >file1 >file2
+cat file1 file2)
+
+Here, it is possible that the second `tt(cat)' will not display the full
+contents of tt(file1) and tt(file2) (i.e. the original contents of
+tt(file) repeated twice).
+
+The reason for this is that the multios are spawned after the tt(cat)
+process is forked from the parent shell, so the parent shell does not
+wait for the multios to finish writing data.  This means the command as
+shown can exit before tt(file1) and tt(file2) are completely written.
+As a workaround, it is possible to run the tt(cat) process as part of a
+job in the current shell:
+
+example({ cat file } >file >file2)
+
+Here, the tt({)var(...)tt(}) job will pause to wait for both files to be
+written.
+
 sect(Redirections with no command)
-vindex(NULLCMD, use of)
-vindex(READNULLCMD, use of)
-pindex(CSH_NULLCMD, use of)
-pindex(SH_NULLCMD, use of)
 When a simple command consists of one or more redirection operators
 and zero or more parameter assignments, but no command name, zsh can
 behave in several ways.
 
+vindex(NULLCMD, use of)
+pindex(CSH_NULLCMD, use of)
 If the parameter tt(NULLCMD) is not set or the option tt(CSH_NULLCMD) is
 set, an error is caused.  This is the bf(csh) behavior and tt(CSH_NULLCMD)
 is set by default when emulating bf(csh).
 
-If the option (SH_NULLCMD) is set, the builtin tt(`:') is inserted as a
+pindex(SH_NULLCMD, use of)
+If the option tt(SH_NULLCMD) is set, the builtin `tt(:)' is inserted as a
 command with the given redirections.  This is the default when emulating
 bf(sh) or bf(ksh).
 
+vindex(READNULLCMD, use of)
 Otherwise, if the parameter tt(NULLCMD) is set, its value will be used as a
 command with the given redirections.  If both tt(NULLCMD) and
 tt(READNULLCMD) are set, then the value of the latter will be used instead