33518: add support for "_ vi buffer and arguments to vi-set-buffer from a zle widget

1 files changed, 23 insertions, 13 deletions

diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index 98f38025a..881e56b19 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -2180,19 +2180,29 @@ command.  tt(run-help) is normally aliased to tt(man).
 tindex(vi-set-buffer)
 item(tt(vi-set-buffer) (unbound) (") (unbound))(
 Specify a buffer to be used in the following command.
-There are 35 buffers that can be specified:
-the 26 `named' buffers tt("a) to tt("z)
-and the nine `queued' buffers tt("1) to tt("9).  The named buffers can also
-be specified as tt("A) to tt("Z).
-
-When a buffer is specified for a cut command, the text being cut replaces
-the previous contents of the specified buffer.  If a named buffer
-is specified using a capital, the newly cut text is appended to the buffer
-instead of overwriting it.
-
-If no buffer is specified for a cut command, tt("1) is used, and the
-contents of tt("1) to tt("8) are each shifted along one buffer; the contents of
-tt("9) is lost.
+There are 37 buffers that can be specified:
+the 26 `named' buffers tt("a) to tt("z), the `yank' buffer tt("0),
+the nine `queued' buffers tt("1) to tt("9) and the `black hole' buffer
+tt("_).  The named buffers can also be specified as tt("A) to tt("Z).
+
+When a buffer is specified for a cut, change or yank command, the text
+concerned replaces the previous contents of the specified buffer. If
+a named buffer is specified using a capital, the newly cut text is
+appended to the buffer instead of overwriting it. When using the tt("_)
+buffer, nothing happens. This can be useful for deleting text without
+affecting the normal registers.
+
+If no buffer is specified for a cut or change command, tt("1) is used, and
+the contents of tt("1) to tt("8) are each shifted along one buffer;
+the contents of tt("9) is lost. If no buffer is specified for a yank
+command, tt("0") is used. Finally, a paste command without a specified
+buffer will paste the text from the most recent command regardless of any
+buffer that might have been used with that command.
+
+When called from a widget function by the tt(zle) command, the buffer
+can optionally be specified with an argument. For example,
+
+example(zle vi-set-buffer A)
 )
 tindex(vi-set-mark)
 item(tt(vi-set-mark) (unbound) (m) (unbound))(