Re: prevent some lines directly coming from the history from being executed

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

v3.  This should incorporate all feedback up to this point.

Cheers,

Daniel

diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index 2d033a0a1..7266aa80a 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -746,16 +746,67 @@ 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
-starting with `tt(.)'.
+
+cindex(widgets, shadowing standard)
+cindex(widgets, overriding standard)
+cindex(shadowing standard widgets)
+cindex(overriding standard widgets)
+User-defined widgets may shadow (override) standard widgets: for instance,
+after `tt(zle -N self-insert) var(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 var(myfunc) rather than the standard implementation of that widget.
+
+In order for the standard implementations to be available to be called by
+user-defined widgets or bound to keypresses even when shadowed, 
+each standard widget `var(foo)' is also available under the
+name `tt(.)var(foo)'.
+These names are reserved and cannot be created as user-defined widgets,
+so for compatibility with possible future revisions of the shell,
+it is recommended that users avoid naming widgets with a leading `tt(.)'.
+
+Continuing the example, var(myfunc) would typically invoke the built-in widget
+it is replacing using the dot-prefix syntax.  For instance:
+
+em(Example #1)
+
+example(self-insert-vowels-twice+LPAR()+RPAR() {
+  [[ $KEYS == [aeiou] ]] && zle .self-insert -- "$@"
+  zle .self-insert -- "$@" 
+}
+zle -N self-insert self-insert-vowels-twice)
+
+This example causes vowels to be inserted twice.  For instance, typing
+`tt(hello)' would insert `tt(heelloo)'.
+
+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(self-insert-vowels-twice) would have been called again, effecting
+a bottomless recursion.
+
+em(Example #2)
+
+In a similar way, to perform a final action on all lines returned from Zle,
+the tt(accept-line) widget can be rebound to a function that performs an action
+on the current line, then calls the tt(.accept-line) widget to return the line
+to the shell.  For example, to change the default behaviour that pressing
+tt(<Enter>) on an empty line redraws the prompt (and runs tt(precmd) hooks,
+if any are configured), one may override accept-line as follows:
+
+example(accept-non-empty-lines+LPAR()+RPAR() {
+    [[ -z $PREBUFFER && -z $BUFFER ]] || zle .accept-line -- "$@"
+}
+zle -N accept-line accept-non-empty-lines)
+
+The special parameters used by these examples DASH()- tt($KEYS),
+tt($PREBUFFER), and tt($BUFFER) DASH()- are documented in the next
+section.
+
 
 texinode(User-Defined Widgets)(Standard Widgets)(Zle Widgets)(Zsh Line Editor)
 sect(User-Defined Widgets)