23567: new _complete_help_generic zle non-completion widget

1 files changed, 36 insertions, 0 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index d5651157b..780255e58 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -3179,6 +3179,42 @@ Note that the information about styles may be incomplete; it depends on the
 information available from the completion functions called, which in turn
 is determined by the user's own styles and other settings.
 )
+findex(_complete_help_generic)
+item(tt(_complete_help_generic))(
+Unlike other commands listed here, this must be created as a normal ZLE
+widget rather than a completion widget (i.e. with tt(zle -N)).  It
+is used for generating help with a widget bound to the tt(_generic)
+widget that is described above.
+
+If this widget is created using the name of the function, as it is by
+default, then when executed it will read a key sequence.  This is expected
+to be bound to a call to a completion function that uses the tt(_generic)
+widget.  That widget will be executed, and information provided in
+the same format that the tt(_complete_help) widget displays for
+contextual completion.
+
+If the widget's name contains tt(debug), for example if it is created
+as `tt(zle -N _complete_debug_generic _complete_help_generic)', it
+will read and execute the keystring for a generic widget as before,
+but then generate debugging information as done by tt(_complete_debug)
+for contextual completion.
+
+If the widget's name contains tt(noread), it will not read a keystring
+but instead arrange that the next use of a generic widget run in
+the same shell will have the effect as described above.
+
+The widget works by setting the shell parameter
+tt(ZSH_TRACE_GENERIC_WIDGET) which is read by tt(_generic).  Unsetting
+the parameter cancels any pending effect of the tt(noread) form.
+
+For example, after executing the following:
+
+example(zle -N _complete_debug_generic _complete_help_generic
+bindkey '^x:' _complete_debug_generic)
+
+typing `tt(C-x :)' followed by the key sequence for a generic widget
+will cause trace output for that widget to be saved to a file.
+)
 findex(_complete_tag (^Xt))
 item(tt(_complete_tag (^Xt)))(
 This widget completes symbol tags created by the tt(etags) or tt(ctags)