28626: summarize differences between two types of trap

2 files changed, 21 insertions, 7 deletions

diff --git a/ChangeLog b/ChangeLog
index 6cb83facb..1621307f1 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2011-01-11  Peter Stephenson  <pws@csr.com>
+
+	* 28626: Doc/Zsh/func.yo: summarise differences between two
+	types of trap.
+
 2011-01-10  Peter Stephenson  <pws@csr.com>
 
 	* 28617: Src/glob.c, Src/params.c, Test/E01options.ztst: NO_EXEC
@@ -14094,5 +14099,5 @@
 
 *****************************************************
 * This is used by the shell to define $ZSH_PATCHLEVEL
-* $Revision: 1.5178 $
+* $Revision: 1.5179 $
 *****************************************************
diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo
index 5f8df990e..6becc6228 100644
--- a/Doc/Zsh/func.yo
+++ b/Doc/Zsh/func.yo
@@ -348,19 +348,28 @@ enditem()
 
 findex(trap, use of)
 The functions beginning `tt(TRAP)' may alternatively be defined with the
-tt(trap) builtin:  this may be preferable for some uses, as they are then
-run in the environment of the calling process, rather than in their own
-function environment.  Apart from the difference in calling procedure and
-the fact that the function form appears in lists of functions, the forms
+tt(trap) builtin:  this may be preferable for some uses.  The forms
 
 example(TRAPNAL+LPAR()RPAR() { 
  # code
 })
 
-and
+('function traps') and
 
 example(trap '
  # code
 ' NAL)
 
-are equivalent.
+('list traps') are equivalent in most ways, the exceptions being the
+following:
+
+startitemize()
+itemiz(Function traps have all the properties of normal functions,
+appearing in the list of functions and being called with their own
+function context rather than the context where the trap was triggered.)
+itemiz(The return status from function traps is special, whereas a return
+from a list trap causes the surrounding context to return with the given
+status.)
+itemiz(Function traps are not reset within subshells, in accordance with
+zsh behaviour; list traps are reset, in accordance with POSIX behaviour.)
+enditemize()