add-zle-hook-widget Re: Next release (5.3)

[Daniel Shahaf <d.s@daniel.shahaf.name>]

Daniel Shahaf wrote on Thu, Jul 07, 2016 at 02:00:21 +0000:
> Bart Schaefer wrote on Mon, Jul 04, 2016 at 08:04:24 -0700:
> > (2) add-zle-hook-widget [I'd be fine with omitting that entirely]
> > 
> 
> Well, I'd like to use it in z-sy-h.  (I'd like to use zle-line-pre-redraw
> in z-sy-h, because that would solve multiple bugs; and I'd like to do so
> through add-zle-hook-widget for interoperability with other plugins.)
> 
> How about including add-zle-hook-widget in 5.3, but without any indices
> or before:/after: support, just the basic 'add-zle-hook-widget
> $hook_name $widget_name' syntax?  (And have it just invoke the widgets
> in the order they were registered)  That would be an improvement over
> the 5.2 status quo, and we can add indices or --option arguments in 5.4.

I've heard neither ayes nor nays, so here's a patch we can use if we
choose this approach.

The ifzman() thing at the beginning is to fix a preëxisting issue
where the "rather than..." line is rendered in bold.  (I tried making
the example() macro generate \fB/\fP around the .RS/.RE but that didn't
help.)

Shall we go for this patch then, or something else (what?)?

Daniel


diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index d4a4538..2e4ba9a 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -345,9 +345,15 @@ tt(zle-isearch-exit), etc.
 var(widgetname) is the name of a ZLE widget.  If no options are given this
 is added to the array of widgets to be invoked in the given hook context.
 Note that the hooks are called as widgets, that is, with
-example(tt(zle )var(widgetname)tt( -Nw "$@"))
+example(tt(zle )var(widgetname)tt( -Nw "$@"))ifzman(NOTRANS(\fR))
 rather than as a function call.
 
+COMMENT(
+The implementation supports specifying a var(widgetname) of the form
+var(index)tt(:)var(name), however, that is an implementation detail that third
+party scripts may not rely on.  See various threads in June/July 2016.  The
+original docs of that feature are retained herein for reference:
+
 In typical usage, var(widgetname) has the form var(index)tt(:)var(name).
 In this case var(index) is an integer which determines the order in which
 the widget var(name) will be called relative to other widgets in the
@@ -355,6 +361,7 @@ array.  Widgets having the same var(index) are called in unspecified
 order.  However, var(widgetname) may omit the index, in which case an
 index is computed for it to arrange for it to be called in the order
 in which it was added to the array.
+)
 
 If the option tt(-d) is given, the var(widgename) is removed from
 the array of widgets to be executed.

Cheers,

Daniel