23567: new _complete_help_generic zle non-completion widget

5 files changed, 62 insertions, 2 deletions

diff --git a/Completion/Base/Utility/_complete_help_generic b/Completion/Base/Utility/_complete_help_generic
new file mode 100644
index 000000000..7aaa1a8df
--- /dev/null
+++ b/Completion/Base/Utility/_complete_help_generic
@@ -0,0 +1,17 @@
+#autoload
+
+# Note this is a normal ZLE widget, not a completion widget.
+# A completion widget can't call another widget, while a normal
+# widget can.
+
+[[ $WIDGET = *noread* ]] || local ZSH_TRACE_GENERIC_WIDGET
+
+if [[ $WIDGET = *debug* ]]; then
+  ZSH_TRACE_GENERIC_WIDGET=_complete_debug
+else
+  ZSH_TRACE_GENERIC_WIDGET=_complete_help
+fi
+
+if [[ $WIDGET != *noread* ]]; then
+  zle read-command && zle $REPLY -w
+fi
diff --git a/Completion/Base/Widget/_complete_debug b/Completion/Base/Widget/_complete_debug
index 43cea5b11..39350b5c5 100644
--- a/Completion/Base/Widget/_complete_debug
+++ b/Completion/Base/Widget/_complete_debug
@@ -11,7 +11,7 @@ exec 3>&-	# Too bad if somebody else is using it ...
 
 setopt xtrace
 : $ZSH_NAME $ZSH_VERSION
-_main_complete
+${1:-_main_complete}
 integer ret=$?
 unsetopt xtrace
 
diff --git a/Completion/Base/Widget/_complete_help b/Completion/Base/Widget/_complete_help
index 5cf4c5f0d..99f2f2dba 100644
--- a/Completion/Base/Widget/_complete_help
+++ b/Completion/Base/Widget/_complete_help
@@ -37,7 +37,7 @@ _complete_help() {
   }
   trap 'unfunction compadd zstyle' EXIT INT
 
-  _main_complete
+  ${1:-_main_complete}
 
   unfunction compadd zstyle
   trap - EXIT INT
diff --git a/Completion/Base/Widget/_generic b/Completion/Base/Widget/_generic
index 9a5e726df..0a18b5680 100644
--- a/Completion/Base/Widget/_generic
+++ b/Completion/Base/Widget/_generic
@@ -1,5 +1,12 @@
 #autoload
 
+if [[ -n $ZSH_TRACE_GENERIC_WIDGET ]]; then
+  local widget=$ZSH_TRACE_GENERIC_WIDGET
+  unset ZSH_TRACE_GENERIC_WIDGET
+  $widget _generic
+  return
+fi
+
 local curcontext="${curcontext:-}"
 
 if [[ -z "$curcontext" ]]; then
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)