--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -746,17 +746,46 @@ ifnzman(noderef(Standard Widgets)).
 Other built-in widgets can be defined by other modules (see
 ifzman(zmanref(zshmodules))\
 ifnzman(noderef(Zsh Modules))\
-).  Each built-in widget has two names: its normal canonical name, and the
-same name preceded by a `tt(.)'.  The `tt(.)' name is special: it can't be
-rebound to a different widget.  This makes the widget available even when
-its usual name has been redefined.
+).
 
 User-defined widgets are defined using `tt(zle -N)', and implemented
 as shell functions.  When the widget is executed, the corresponding
 shell function is executed, and can perform editing (or other) actions.
-It is recommended that user-defined widgets should not have names
+
+cindex(widgets, shadowing standard)
+cindex(widgets, overriding standard)
+User-defined widgets may shadow (override) standard widgets: for instance,
+after `tt(zle -N self-insert myfunc)', any invocation of the standard
+tt(self-insert) widget (including every keypress that appends an alphanumeric
+or space character to the command line) would invoke the user-defined
+function tt(myfunc) rather than the standard implementation of that widget.
+However, each standard widget `var(foo)' is also available under the
+name `tt(.)var(foo)', and this name can't be rebound to a different widget.
+This makes the standard widget available to be called or bound even when
+its usual name has been redefined.
+Therefore, for forward compatibility with future versions of the shell,
+it is recommended that user-defined widgets should not have names
-starting with `tt(.)'.
+starting with `tt(.)'.  (If a user-defined widget is named `tt(.)var(some-name)'
+and a future version of the shell introduces a built-in `var(some-name)' widget,
+the user-defined widget's definition will raise an error under that future
+version of the shell.)
 
+Continuing the example, tt(myfunc) would typically invoke the built-in widget
+it is replacing using the dot-prefix syntax:
+
+example(zle -N self-insert myfunc
+myfunc+LPAR()+RPAR() {
+  [[ $KEYS == [aeiou] ]] && zle .self-insert -- "$@"
+  zle .self-insert -- "$@" 
+})
+
+This example causes vowels to be inserted twice.
+
+Note the use of the dot-prefix syntax.  If the tt(self-insert) widget had been
+invoked without the dot DASH()- that is, as `tt(zle self-insert -- "$@")' DASH()-
+then tt(myfunc) would have been called again, effecting a bottomless
+recursion.
+
 texinode(User-Defined Widgets)(Standard Widgets)(Zle Widgets)(Zsh Line Editor)
 sect(User-Defined Widgets)
 cindex(widgets, user-defined)