delete-windows-on

["Drew Adams" <drew.adams@oracle.com>]

Some questions and suggestions regarding `delete-windows-on'.

1. Why is this defined in C? Is that needed for performance reasons? If not, why
not move it to Lisp?

2. It returns nil if you pass nil as the BUFFER arg. That's OK, in itself.

But even though undocumented, some Emacs code has in fact depended on this
return value. (Calc, for example - see bug "Minor problem with calc-quit", filed
2006-05-30, though this has apparently been fixed.) Dunno if any code currently
depends on it.

3. It raises an error if you pass the name of a non-existent buffer, or if you
pass anything that is not a string or a buffer (except nil - see #2). Why? Why
doesn't it just do nothing if the BUFFER arg is not an existing buffer or its
name?

A nil value of BUFFER means there is no such buffer. The same is true of a
string that doesn't name an existing buffer. The same is true of a non-string
such as the number 42. In one case (#2), we currently do nothing and return nil;
in all other cases (#3), we currently raise an error. That's not very
consistent.

IMO, we should never raise an error when BUFFER doesn't correspond to an
existing buffer - we should just do nothing (there are simply no windows to
delete). The only purpose of `delete-windows-on' should be to delete windows -
it should not also be interpreted as a test for whether BUFFER actually
corresponds to a buffer.

4. Either the return value is important and part of the design (interface), or
not. If the former, then the return value should be documented (in the special
case of a nil BUFFER and in all other cases). If the latter, then we should
ensure that none of the existing code depends on the return value.

5. The completion list of `delete-windows-on' is currently all (non-internal)
buffers, even buffers that are not displayed anywhere. If you are calling
`delete-windows-on' interactively, then you are not interested in deleting the
windows of buffers that do not have windows (!). It would be better therefore to
have `interactive' propose only displayed buffers.

The `interactive' code could either allow as candidate any buffer displayed in
any frame, or it could check the FRAME arg and propose only buffers that are
compatible (consistent) with FRAME.

Either approach would be reasonable, but probably the former is more flexible
for users, especially those who use multiple frames a lot. Here is an example of
this approach (any buffer displayed anywhere is a candidate):

(completing-read "Delete windows on buffer: "
                 (let ((all-bufs   (buffer-list))
                       (cand-bufs  ()))
                   (dolist (buf  all-bufs)
                     (when (get-buffer-window buf t)
                       (push (list (buffer-name buf)) cand-bufs)))
                   cand-bufs)
                 nil t nil 'minibuffer-history
                 (buffer-name (current-buffer)) t)

Note: This repeats a suggestion I made on 2006-08-07 (Subject
"`delete-windows-on' completion list should include only buffers that correspond
to FRAME arg"). Richard rejected it, saying "It could be confusing for
completion to fail to recognize a buffer name." How about reconsidering this
decision now?

6. What about the return value more generally? Should it indicate whether any
windows were actually deleted (nil/t)? Should it indicate how many were deleted
(0..N)? Should we return a list of the actual deleted-window objects?

I don't have a preference here. But if the return value is to be considered
important, then (i) it should be documented and (ii) we might as well make the
value more useful generally.

7. Putting 1-5 together: Why not a Lisp definition that does this:

a. Do nothing if BUFFER is not an existing buffer or its name. Do not raise an
error because of the BUFFER value in any case.

b. Return nil in case (a) (no-buffer BUFFER). But we would continue to not
document the return value. And we would fix any code (if there is any) that
depends on the (undocumented) return value.

c. Interactively, for reading BUFFER with completion, provide only names of
buffers that are actually displayed.

WDOT?