bug#34749: 26.1; `delete-windows-on': (1) doc, (2) bug, (3) bug, (4) candidates

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

> > 1. The doc string should first of all completely describe the
> > interactive behavior and only secondarily describe the Lisp behavior
> > (completely).
> >
> > In particular, this doc string should say explicitly what happens with a
> > prefix arg, including what happens with different kinds of raw prefix
> > arg (including, but not limited to, 0).
> 
> I fixed this, although not regarding the order. the doc string is not
> too long, so interspersing the description of interactive behavior
> with non-interactive is not a catastrophe.

Thank you.

Agreed.  By "first of all" and "only secondarily" I meant
importance more than order.  I meant that for a command
the interactive use is more important to document (but
both are important).  (And yes, it is typically presented
first, but that's not imperative, and yes, sometimes it
makes more sense to intersperse interactive and non.)

> Btw, it is a pity that only the prefix arg of zero is useful in
> interactive usage, which doesn't let the user select the other
> behaviors regarding the optional FRAME argument.  I think this
> could/should be improved by relatively straightforward changes that
> use values of prefix arg other than zero.

Both you and Martin have now opened a discussion about
possible improvements to the command/function behavior.

I agree that it could be improved.  And I agree with
you that discussion of that should probably happen
outside this bug thread.
_____

Nevertheless and FWIW (toward that discussion):

I've long (since 1996) had my own version of
`delete-windows-on', which differs in the following ways.
My version is not completely up-to-date wrt the latest
vanilla implementation, but the changes I've made are
still relevant, I think.  Here is the code comment that
summarizes my changes:

;; REPLACES ORIGINAL in `window.el' (built-in prior to Emacs 24.5):
;;
;; 1) Use `read-buffer' in interactive spec.
;; 2) Do not raise an error if BUFFER is a string that
;;    does not name a buffer.
;; 3) Call `delete-window', so if you use the advised
;;    `delete-window' here then this also deletes frames
;;    where window showing the BUFFER is the only window.

#3 refers to my advised version of `delete-window', which
does just `delete-frame' if WINDOW is the only one in its
frame.

My code is in `frame-cmds.el':
https://www.emacswiki.org/emacs/download/frame-cmds.el

I also have this related command there, FWIW (since 2006),
which, for my personal use, I bind to the keys that are
normally bound to `delete-window':

(defun delete-windows-for (&optional buffer)
  "`delete-window' or prompt for buffer and delete its windows.
With no prefix arg, delete the selected window.
With a prefix arg, prompt for a buffer and delete all windows, on any
  frame, that show that buffer."
  (interactive (list (and current-prefix-arg
                     (frcmds-read-buffer-for-delete-windows))))
  (if buffer (delete-windows-on buffer) (delete-window)))

Function `frcmds-read-buffer-for-delete-windows' is used
by both `delete-windows-on' and `delete-windows-for'.
It offers only displayed buffers as completion candidates.
 
> > The doc string should also say that a prefix arg is ignored when the
> > condition of the last paragraph applies (dedicated window alone in
> > frame, with other frames existing), if that's true.
> 
> I didn't understand what this alludes to.

It refers to this behavior described in the current
doc string:

  When a window showing BUFFER-OR-NAME is dedicated and
  the only window of its frame, that frame is deleted
  when there are other frames left.

I was saying that the doc string should also mention
that in this case any prefix arg you provide is ignored.