20330: rationalise zle return statuses

3 files changed, 26 insertions, 15 deletions

diff --git a/ChangeLog b/ChangeLog
index a31882037..d274fdc27 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2004-09-08  Peter Stephenson  <pws@csr.com>
+
+	* 20330: Src/Zle/zle_thingy.c, Doc/Zsh/zle.yo: rationalise status
+	from zle -I and improve documentation of status from zle, zle -I,
+	zle -R.
+
 2004-09-08  Bart Schaefer  <schaefer@zanshin.com>
 
 	* 20325: Src/exec.c, Test/E01options.ztst: fix crash when using
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index 7b59d32d3..ed80b269a 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -312,6 +312,7 @@ cindex(widgets, calling)
 cindex(calling widgets)
 cindex(widgets, defining)
 cindex(defining widgets)
+xitem(tt(zle))
 xitem(tt(zle) tt(-l) [ tt(-L) | tt(-a) ] [ var(string) ... ])
 xitem(tt(zle) tt(-D) var(widget) ...)
 xitem(tt(zle) tt(-A) var(old-widget) var(new-widget))
@@ -323,10 +324,18 @@ xitem(tt(zle) tt(-U) var(string))
 xitem(tt(zle) tt(-K) var(keymap))
 xitem(tt(zle) tt(-F) [ tt(-L) ] [ var(fd) [ var(handler) ] ])
 xitem(tt(zle) tt(-I))
-xitem(tt(zle) var(widget) tt([ -n) var(num) tt(]) tt([ -N ]) var(args) ...)
-item(tt(zle))(
+item(tt(zle) var(widget) tt([ -n) var(num) tt(]) tt([ -N ]) var(args) ...)(
 The tt(zle) builtin performs a number of different actions concerning
-ZLE.  Which operation it performs depends on its options:
+ZLE.
+
+With no options and no arguments, only the return status will be
+set.  It is zero if ZLE is currently active and widgets could be
+invoked using this builtin command and non-zero otherwise.
+Note that even if non-zero status is returned, zle may still be active as
+part of the completion system; this does not allow direct calls to ZLE
+widgets.
+
+Otherwise, which operation it performs depends on its options:
 
 startitem()
 item(tt(-l) [ tt(-L) | tt(-a) ])(
@@ -392,7 +401,9 @@ immediately after return from the widget.
 This command can safely be called outside user defined widgets; if zle is
 active, the display will be refreshed, while if zle is not active, the
 command has no effect.  In this case there will usually be no other
-arguments.  The status is zero if zle was active, else one.
+arguments.
+
+The status is zero if zle was active, else one.
 )
 item(tt(-M) var(string))(
 As with the tt(-R) option, the var(string) will be displayed below the 
@@ -505,12 +516,10 @@ to minimise disruption.
 Note that there are normally better ways of manipulating the display from
 within zle widgets; see, for example, `tt(zle -R)' above.
 
-The returned status is zero if a zle widget can be called immediately.
-Note this is independent of whether the display has been invalidated.
-For example, if a completion widget is active a zle widget cannot be used
-and the status is one even if the display was invalidated; on the other
-hand, the status may be zero if the display was invalidated by a previous
-call to `tt(zle -I)'.
+The returned status is zero if zle was invalidated, even though
+this may have been by a previous call to `tt(zle -I)' or by a system
+notification.  To test if a zle widget may be called at this point, execute
+tt(zle) with no arguments and examine the return status.
 )
 item(var(widget) tt([ -n) var(num) tt(]) tt([ -N ]) var(args) ...)(
 Invoke the specified widget.  This can only be done when ZLE is
@@ -540,10 +549,6 @@ tt(zle) command.  Thus if a user defined widget requires an immediate beep,
 it should call the tt(beep) widget directly.
 )
 enditem()
-
-With no options and no arguments, only the return status will be
-set. It is zero if ZLE is currently active and widgets could be
-invoked using this builtin command and non-zero if ZLE is not active.
 )
 enditem()
 
diff --git a/Src/Zle/zle_thingy.c b/Src/Zle/zle_thingy.c
index c252eee1e..441d85b2c 100644
--- a/Src/Zle/zle_thingy.c
+++ b/Src/Zle/zle_thingy.c
@@ -709,7 +709,7 @@ bin_zle_invalidate(UNUSED(char *name), UNUSED(char **args), UNUSED(Options ops),
     if (zleactive) {
 	if (!trashedzle)
 	    trashzle();
-	return !zle_usable();
+	return 0;
     } else
 	return 1;
 }