1 files changed, 133 insertions, 21 deletions
diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo
index c2fc71d55..af21fba82 100644
--- a/Doc/Zsh/func.yo
+++ b/Doc/Zsh/func.yo
@@ -5,7 +5,8 @@ sect(Functions)
 )\
 cindex(functions)
 findex(function)
-The tt(function) reserved word is used to define shell functions.
+Shell functions are defined with the tt(function) reserved word or the
+special syntax `var(funcname) tt(())'.
 Shell functions are read in and stored internally.
 Alias names are resolved when the function is read.
 Functions are executed like commands with the arguments
@@ -30,29 +31,119 @@ sect(Autoloading Functions)
 findex(autoload, use of)
 cindex(autoloading functions)
 cindex(functions, autoloading)
+
 A function can be marked as em(undefined) using the tt(autoload) builtin
 (or `tt(functions -u)' or `tt(typeset -fu)').  Such a function has no
-body.  When the function is first executed, the tt(fpath)
-variable will be searched for a file with the same name as the
-function.
+body.  When the function is first executed, the shell searches for its
+definition using the elements of the tt(fpath) variable.  Thus to define
+functions for autoloading, a typical sequence is:
+
+example(fpath=(~/myfuncs $fpath)
+autoload myfunc1 myfunc2 ...)
+
+The usual alias expansion during reading will be suppressed if the
+tt(autoload) builtin or its equivalent is given the option tt(-U). This is
+recommended for the use of functions supplied with the zsh distribution.
+Note that for functions precompiled with the tt(zcompile) builtin command
+the flag tt(-U) must be created when the tt(.zwc) file is created, as the
+corresponding information is compiled into the latter.
+
+For each var(element) in tt(fpath), the shell looks for three possible
+files, the newest of which is used to load the definition for the function:
+
+startitem()
+item(var(element)tt(.zwc))(
+A file created with the tt(zcompile) builtin command, which is expected to
+contain the definitions for all functions in the directory named
+var(element).  The file is treated in the same manner as a directory
+containing files for functions and is searched for the definition of the
+function.   If the definition is not found, the search for a definition
+proceeds with the the other two possibilities described below.
+
+If var(element) already includes a tt(.zwc) extension (i.e. the extension
+was explicitly given by the user), var(element) is searched for the
+definition of the function without comparing its age to that of other
+files; in fact, there does not need to be any directory named var(element)
+without the suffix.  Thus including an element such as
+`tt(/usr/local/funcs.zwc)' in tt(fpath) will speed up the search for
+functions, with the disadvantage that functions included must be explicitly
+recompiled by hand before the shell notices any changes.  )
+item(var(element)tt(/)var(function)tt(.zwc))( A file created with
+tt(zcompile), which is expected to contain the definition for
+var(function).  It may include other function definitions as well, but
+those are neither loaded nor executed; a file found in this way is searched
+em(only) for the definition of var(function).  )
+item(var(element)tt(/)var(function))( A file of zsh command text, taken to
+be the definition for var(function).  ) enditem()
+
+In summary, the order of searching is, first, directories in tt(fpath),
+with the earliest directory containing a function definition being used;
+within that directory, the newest of the three possibilities --- a compiled
+directory, a compiled function, or an ordinary function defition --- is
+used.
 
 pindex(KSH_AUTOLOAD, use of)
-If the tt(KSH_AUTOLOAD) option is set, or the file contains only a simple
-definition of the function, the file's contents will be
-executed.  It would normally define the function in question, but may
-also perform initialisation.
-It is executed in the context of the function
-execution, and may therefore define local parameters.
-
-Otherwise, the function is defined such that its body is the
-complete contents of the file.  This form allows the file to be
-used directly as an executable shell script.
-Initialisation code can be executed, but only as part of the first
-function execution, so the function would have to redefine itself to
-avoid reinitialising on the next execution.
-
-If this processing of the file results in the function being
-fully defined, the function itself is then executed.
+If the tt(KSH_AUTOLOAD) option is set, or the file contains only a
+simple definition of the function, the file's contents will be executed.
+This will normally define the function in question, but may also perform
+initialization, which is executed in the context of the function execution,
+and may therefore define local parameters.  It is an error if the function
+is not defined by loading the file.
+
+Otherwise, the function body with no surrounding `var(funcname)tt(()
+{)var(...)tt(}) is taken to be the complete contents of the file.  This
+form allows the file to be used directly as an executable shell script.  If
+processing of the file results in the function being re-defined, the
+function itself is not re-executed.  To force the shell to perform
+initialization and then call the function defined, the file should contain
+initialization code (which will be executed then discarded) in addition to
+a complete function definition (which will be retained for subsequent calls
+to the function), and a call to the shell function, including any
+arguments, at the end.
+
+For example, suppose the autoload file tt(func) contains
+
+example(func() { print This is func; }
+print func is initialized
+)
+
+then `tt(func; func)' with tt(KSH_AUTOLOAD) set will produce both messages
+on the first call, but only the message `tt(This is func)' on the second
+and subsequent calls.  Without tt(KSH_AUTOLOAD) set, it will produce
+the initialization message on the first call, and the other message on the
+second and subsequent calls.
+
+It is also possible to create a function that is not marked as autoloaded,
+but which loads its own definition by searching tt(fpath), by using
+`tt(autoload -X)' within a shell function.  For example, the following are
+equivalent:
+
+example(myfunc() {
+  autoload -X
+}
+myfunc args...)
+
+and
+
+example(unfunction myfunc   # if myfunc was defined
+autoload myfunc
+myfunc args...)
+
+In fact, the tt(functions) command outputs `tt(builtin autoload -X)' as
+the body of an autoloaded function.  A true autoloaded function can be
+identified by the presence of the comment `tt(# undefined)' in the body,
+because all comments are discarded from defined functions.  This is done
+so that
+
+example(eval "$(functions)")
+
+produces a reasonable result.
+
+To load the definition of an autoloaded function tt(myfunc) without
+executing tt(myfunc), use:
+
+example(autoload +X myfunc)
+
 sect(Special Functions)
 The following functions, if defined, have special meaning to
 the shell:
@@ -102,6 +193,27 @@ or when the current function exits if defined inside a function.
 )
 findex(TRAPZERR)
 item(tt(TRAPZERR))(
-Executed whenever a command has a non-zero exit status.
+Executed whenever a command has a non-zero exit status.  However, the
+function is not executed if the command occurred in a sublist followed by
+`tt(&&)' or `tt(||)'; only the final command in a sublist of this type
+causes the trap to be executed.
 )
 enditem()
+
+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
+
+example(TRAPNAL() { 
+ # code
+})
+
+and
+
+example(trap '
+ # code
+' NAL)
+
+are equivalent.