33312: document redirections applied to function definitions

ChangeLog

@@ -1,3 +1,8 @@
+2014-10-01  Peter Stephenson  <p.w.stephenson@ntlworld.com>
+
+	* 33312: Doc/Zsh/builtins.yo, Doc/Zsh/grammar.yo: document
+	redirections applied to function definitions.
+
 2014-09-30  Barton E. Schaefer  <schaefer@zsh.org>
 
 	* 33298: Src/lex.c: make lexrestore() more signal-safe

Doc/Zsh/builtins.yo

@@ -2174,6 +2174,20 @@ match one of these patterns will be written. If no var(name) is given,
 the definitions of all functions currently defined or marked as
 autoloaded will be written.
 
+Note the second form cannot be used for compiling functions that
+include redirections as part of the definition rather than within
+the body of the function; for example
+
+example(fn1() { { ... } >~/logfile })
+
+can be compiled but
+
+example(fn1() { ... } >~/logfile)
+
+cannot.  It is possible to use the first form of tt(zcompile) to compile
+autoloadable functions that include the full function definition instead
+of just the body of the function.
+
 The third form, with the tt(-t) option, examines an existing
 compiled file.  Without further arguments, the names of the original
 files compiled into it are listed.  The first line of output shows

Doc/Zsh/grammar.yo

@@ -352,6 +352,15 @@ If the option tt(SH_GLOB) is set for compatibility with other shells, then
 whitespace may appear between between the left and right parentheses when
 there is a single var(word);  otherwise, the parentheses will be treated as
 forming a globbing pattern in that case.
+
+In any of the forms above, a redirection may appear outside the
+function body, for example
+
+example(func() { ... } 2>&1)
+
+The redirection is stored with the function and applied whenever the
+function is executed.  Any variables in the redirection are expanded
+at the point the function is executed, but outside the function scope.
 )
 cindex(timing)
 findex(time)