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

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

[Drew Adams]

There are several things wrong with `delete-windows-on', and several things that call for improvement.


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).

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.

In general: Please fix the doc string to provide a correct and complete
description of the interactive behavior.


2. The doc string says that when FRAME is anything other than t,
`visible', 0, or a frame then all windows showing the buffer on any
frame are deleted.  But that's not the case:

emacs -Q

`C-h f delete-windows-on'

With window *Help* selected: `C-x 5 2', to display it also in another
frame.

With window *Help* in the original frame selected:
`C-u M-x delete-windows-on *Help*'

Only the *Help* window on the selected frame is deleted, not the one on
the separate frame.  But the doc says that FRAME, which is `(4)' should
cause all windows showing buffer *Help* to be deleted from all frames.

It seems like the interactive behavior is not correct, as well as being
poorly documented.  It's hard to know just what behavior was intended,
or what behavior would be best if (as it seems) we still need to design
this.


3. Why is `B' used in the interactive spec instead of `b'?  What's the
use case for deleting windows showing a nonexistent buffer?


4. The buffer candidates available for completion (which should also be
the only buffer names available for entry - see #3) should depend on
which frames are used, i.e., on the prefix arg or its absence.

You should be presented only with the names of buffers that are actually
shown in windows on the frames that you've chosen to consider for
window-deletion.

In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 10.0.17134
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

[martin rudalics]

 > It seems like the interactive behavior is not correct, as well as being
 > poorly documented.  It's hard to know just what behavior was intended,
 > or what behavior would be best if (as it seems) we still need to design
 > this.

If anyone has any ideas, we should implement that.  Suggestions highly
welcome.

 > 3. Why is `B' used in the interactive spec instead of `b'?  What's the
 > use case for deleting windows showing a nonexistent buffer?

I hopefully fixed that now on master.

 > 4. The buffer candidates available for completion (which should also be
 > the only buffer names available for entry - see #3) should depend on
 > which frames are used, i.e., on the prefix arg or its absence.
 >
 > You should be presented only with the names of buffers that are actually
 > shown in windows on the frames that you've chosen to consider for
 > window-deletion.

Good idea.

martin

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

[Eli Zaretskii]

> Date: Tue, 05 Mar 2019 11:12:59 +0100
> From: martin rudalics <rudalics@gmx.at>
> 
>  > It seems like the interactive behavior is not correct, as well as being
>  > poorly documented.  It's hard to know just what behavior was intended,
>  > or what behavior would be best if (as it seems) we still need to design
>  > this.
> 
> If anyone has any ideas, we should implement that.  Suggestions highly
> welcome.

I don't understand what you are asking about.  It sounds like Drew has
pointed out some inconsistencies between the doc string and the actual
behavior, and we should first fix those inconsistencies for the
release branch, probably by fixing the doc string.

Why is Emacs behaving unlike the doc string says?

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

[martin rudalics]

 >>   > It seems like the interactive behavior is not correct, as well as being
 >>   > poorly documented.  It's hard to know just what behavior was intended,
 >>   > or what behavior would be best if (as it seems) we still need to design
 >>   > this.
 >>
 >> If anyone has any ideas, we should implement that.  Suggestions highly
 >> welcome.
 >
 > I don't understand what you are asking about.

About "what behavior would be best if (as it seems) we still need to
design this".  I don't use this function so I don't have any ideas
about what behavior would be best.

 > It sounds like Drew has
 > pointed out some inconsistencies between the doc string and the actual
 > behavior, and we should first fix those inconsistencies for the
 > release branch, probably by fixing the doc string.
 >
 > Why is Emacs behaving unlike the doc string says?

I think because this function has to work in some ad hoc manner, for
example, when a window is not dedicated and alone on its frame.  The
initial claim "Delete all windows showing BUFFER-OR-NAME." is simply
wrong in this regard.  Maybe we should say "Try to delete all windows
showing BUFFER-OR-NAME." instead.

But I'm not keen rewriting this doc-string because I never documented
the behavior of the prefix argument as Drew requested.  I simply don't
understand how that works.

martin

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

[Eli Zaretskii]

> Date: Fri, 08 Mar 2019 12:02:04 +0100
> From: martin rudalics <rudalics@gmx.at>
> CC: drew.adams@oracle.com, 34749@debbugs.gnu.org
> 
> About "what behavior would be best if (as it seems) we still need to
> design this".  I don't use this function so I don't have any ideas
> about what behavior would be best.

I think we should simply try letting the user provide all possible
values of the FRAME argument in interactive invocations, by using
different forms of 'C-u'.

>  > Why is Emacs behaving unlike the doc string says?
> 
> I think because this function has to work in some ad hoc manner, for
> example, when a window is not dedicated and alone on its frame.  The
> initial claim "Delete all windows showing BUFFER-OR-NAME." is simply
> wrong in this regard.  Maybe we should say "Try to delete all windows
> showing BUFFER-OR-NAME." instead.

That'd be too radical, IMO.  I'd rather we described the exceptional
cases, because I think they would be rare.  Can you enumerate those
exceptions?

> But I'm not keen rewriting this doc-string because I never documented
> the behavior of the prefix argument as Drew requested.  I simply don't
> understand how that works.

I think it would be better to rework the interpretation of the prefix
arg so it makes sense.

Thanks.

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

[martin rudalics]

 > I think we should simply try letting the user provide all possible
 > values of the FRAME argument in interactive invocations, by using
 > different forms of 'C-u'.

I have no idea how to do that.  And when trying to read the
documentation on 'interactive' I nowhere detected where the "\nP"
convention is described (which apparently turns a function's last (?)
argument into the prefix argument).  Can someone enlighten me?

 > That'd be too radical, IMO.  I'd rather we described the exceptional
 > cases, because I think they would be rare.  Can you enumerate those
 > exceptions?

The doc-string should hopefully tell these details now.

 > I think it would be better to rework the interpretation of the prefix
 > arg so it makes sense.

The fact that 'delete-windows-on' is the only function (together with
its 'quit-window-on' clone) with the inverted meaning of the
FRAME/ALL-FRAMES argument makes me doubt that such an interpretation
would make sense.  But since I don't know how to specify prefix args
in the first place I'm probably not really entitled to such a comment.

martin

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

[Drew Adams]

>  > I think we should simply try letting the user provide all possible
>  > values of the FRAME argument in interactive invocations, by using
>  > different forms of 'C-u'.
> 
> I have no idea how to do that.  And when trying to read the
> documentation on 'interactive' I nowhere detected where the "\nP"
> convention is described (which apparently turns a function's last (?)
> argument into the prefix argument).  Can someone enlighten me?

Are you asking what "\nP" means/does?  If so, the "\n" separates
arguments and the "P" stands for `current-prefix-arg', i.e., the
raw prefix argument.  This is pretty well documented in (elisp)
`Using Interactive' and (elisp) `Interactive Codes'.

  a string; its contents are a sequence of elements
  separated by newlines, one for each argument(1).  Each element
  consists of a code character (*note Interactive Codes::) optionally
  followed by a prompt (which some code characters use and some
  ignore).  Here is an example:

       (interactive "P\nbFrobnicate buffer: ")

  The code letter ‘P’ sets the command’s first argument to the raw
  command prefix (*note Prefix Command Arguments::).

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

[martin rudalics]

 > Are you asking what "\nP" means/does?

Yes.

 > If so, the "\n" separates
 > arguments and the "P" stands for `current-prefix-arg', i.e., the
 > raw prefix argument.  This is pretty well documented in (elisp)
 > `Using Interactive' and (elisp) `Interactive Codes'.
 >
 >    a string; its contents are a sequence of elements
 >    separated by newlines, one for each argument(1).  Each element
 >    consists of a code character (*note Interactive Codes::) optionally
 >    followed by a prompt (which some code characters use and some
 >    ignore).  Here is an example:
 >
 >         (interactive "P\nbFrobnicate buffer: ")
 >
 >    The code letter ‘P’ sets the command’s first argument to the raw
 >    command prefix (*note Prefix Command Arguments::).

It's clear for you since you probably write such specifications all
the time.  I hope it's now clear for me as well after reading that
text a couple of times.

Thanks, martin

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

[Drew Adams]

>  > Are you asking what "\nP" means/does?
> 
> Yes.

>  > This is pretty well documented in (elisp)
>  > `Using Interactive' and (elisp) `Interactive Codes'.
>  >
>  >    separated by newlines, one for each argument...
>  >    The code letter ‘P’ sets the command’s first argument
>  >    to the raw command prefix...
> 
> It's clear for you since you probably write such specifications all
> the time.

Yes.  Looking at some existing Elisp code is a good
way to get this.  I probably did that too at some
point, in addition to consulting the doc.

> I hope it's now clear for me as well after reading that
> text a couple of times.

If it can be made clearer then we should try to do so.

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

[Eli Zaretskii]

> Date: Fri, 08 Mar 2019 19:52:17 +0100
> From: martin rudalics <rudalics@gmx.at>
> CC: drew.adams@oracle.com, 34749@debbugs.gnu.org
> 
>  > I think we should simply try letting the user provide all possible
>  > values of the FRAME argument in interactive invocations, by using
>  > different forms of 'C-u'.
> 
> I have no idea how to do that.

Maybe we are having a misunderstanding.  Because all I meant is to
have each of the possible values of FRAME be expressible with some
form of prefix-arg.  There are several such forms available:

 . just C-u
 . C-u with a numeric argument
 . repeated C-u C-u ...

We currently only use the second of these, and with a single numeric
argument of zero.  What I had in mind is to use the other forms, and
perhaps also other numeric arguments, to allow users in interactive
invocation access to all possible values of FRAME.

>  > That'd be too radical, IMO.  I'd rather we described the exceptional
>  > cases, because I think they would be rare.  Can you enumerate those
>  > exceptions?
> 
> The doc-string should hopefully tell these details now.

I'm not sure it covers the use case described by Drew.  Maybe I'm
missing something.

>  > I think it would be better to rework the interpretation of the prefix
>  > arg so it makes sense.
> 
> The fact that 'delete-windows-on' is the only function (together with
> its 'quit-window-on' clone) with the inverted meaning of the
> FRAME/ALL-FRAMES argument makes me doubt that such an interpretation
> would make sense.

Do you still think that, after reading my explanation above?

> And when trying to read the documentation on 'interactive' I nowhere
> detected where the "\nP" convention is described (which apparently
> turns a function's last (?)  argument into the prefix argument).
> Can someone enlighten me?

It's described in this passage from "Using Interactive":

   There are three possibilities for the argument ARG-DESCRIPTOR:

   [...]
   • It may be a string; its contents are a sequence of elements
     separated by newlines, one for each argument(1).  Each element
     consists of a code character (*note Interactive Codes::) optionally
     followed by a prompt (which some code characters use and some
     ignore).  Here is an example:

          (interactive "P\nbFrobnicate buffer: ")

     The code letter ‘P’ sets the command’s first argument to the raw
     command prefix (*note Prefix Command Arguments::).  ‘bFrobnicate
     buffer: ’ prompts the user with ‘Frobnicate buffer: ’ to enter the
     name of an existing buffer, which becomes the second and final
     argument.

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

[martin rudalics]

 > Maybe we are having a misunderstanding.  Because all I meant is to
 > have each of the possible values of FRAME be expressible with some
 > form of prefix-arg.  There are several such forms available:
 >
 >   . just C-u
 >   . C-u with a numeric argument
 >   . repeated C-u C-u ...
 >
 > We currently only use the second of these, and with a single numeric
 > argument of zero.  What I had in mind is to use the other forms, and
 > perhaps also other numeric arguments, to allow users in interactive
 > invocation access to all possible values of FRAME.

I understood that part.

 >> The doc-string should hopefully tell these details now.
 >
 > I'm not sure it covers the use case described by Drew.  Maybe I'm
 > missing something.

I'm not sure either.

 >> The fact that 'delete-windows-on' is the only function (together with
 >> its 'quit-window-on' clone) with the inverted meaning of the
 >> FRAME/ALL-FRAMES argument makes me doubt that such an interpretation
 >> would make sense.
 >
 > Do you still think that, after reading my explanation above?

You mean to use a universal prefix nomenclature such that, for
example, 0 means all visible and iconified frames, 1 all windows on
the selected frame, 2 all visible frames (for a C-u with a numeric
argument only solution) and so on?  But the most interesting functions
that would benefit from such a nomenclature are `other-window' and
`other-frame' and both use the prefix argument for skipping.  Still,
don't count my opinion here - I don't use or specify prefix arguments.

 > It's described in this passage from "Using Interactive":
 >
 >     There are three possibilities for the argument ARG-DESCRIPTOR:
 >
 >     [...]
 >     • It may be a string; its contents are a sequence of elements
 >       separated by newlines, one for each argument(1).  Each element
 >       consists of a code character (*note Interactive Codes::) optionally
 >       followed by a prompt (which some code characters use and some
 >       ignore).  Here is an example:
 >
 >            (interactive "P\nbFrobnicate buffer: ")
 >
 >       The code letter ‘P’ sets the command’s first argument to the raw
 >       command prefix (*note Prefix Command Arguments::).  ‘bFrobnicate
 >       buffer: ’ prompts the user with ‘Frobnicate buffer: ’ to enter the
 >       name of an existing buffer, which becomes the second and final
 >       argument.

That text is all right and yet was incomprehensible for me at first
(and second) reading.  It's probably just me, so ignore that.

martin

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

[Eli Zaretskii]

> Date: Sat, 09 Mar 2019 09:39:50 +0100
> From: martin rudalics <rudalics@gmx.at>
> CC: drew.adams@oracle.com, 34749@debbugs.gnu.org
> 
> You mean to use a universal prefix nomenclature such that, for
> example, 0 means all visible and iconified frames, 1 all windows on
> the selected frame, 2 all visible frames (for a C-u with a numeric
> argument only solution) and so on?

Something like that, except "C-u C-u" might be easier to type than
"C-u 2", so perhaps use the former for some of the possible values.

> But the most interesting functions that would benefit from such a
> nomenclature are `other-window' and `other-frame' and both use the
> prefix argument for skipping.

Those other-* function also need to allow the user to specify a count,
something that we don't have to do here.  So there's no reason to
expect consistency here.  (I do think it would be good to allow the
user to control the last argument of other-window and other-frame as
well, if that's possible, but the solution doesn't have to be
identical to what we do with delete-windows-on.)

>  >     • It may be a string; its contents are a sequence of elements
>  >       separated by newlines, one for each argument(1).  Each element
>  >       consists of a code character (*note Interactive Codes::) optionally
>  >       followed by a prompt (which some code characters use and some
>  >       ignore).  Here is an example:
>  >
>  >            (interactive "P\nbFrobnicate buffer: ")
>  >
>  >       The code letter ‘P’ sets the command’s first argument to the raw
>  >       command prefix (*note Prefix Command Arguments::).  ‘bFrobnicate
>  >       buffer: ’ prompts the user with ‘Frobnicate buffer: ’ to enter the
>  >       name of an existing buffer, which becomes the second and final
>  >       argument.
> 
> That text is all right and yet was incomprehensible for me at first
> (and second) reading.  It's probably just me, so ignore that.

Maybe we should improve it.  But I cannot tell how, because "a
sequence of elements separated by newlines, one for each argument" is
very clear for me.  If you can tell what was incomprehensible in that,
maybe we will be able to come up with an improvement.

Thanks.

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

[martin rudalics]

 > Those other-* function also need to allow the user to specify a count,
 > something that we don't have to do here.  So there's no reason to
 > expect consistency here.  (I do think it would be good to allow the
 > user to control the last argument of other-window and other-frame as
 > well, if that's possible, but the solution doesn't have to be
 > identical to what we do with delete-windows-on.)

It would be confusing if it weren't.

 >>   >     • It may be a string; its contents are a sequence of elements
 >>   >       separated by newlines, one for each argument(1).  Each element
 >>   >       consists of a code character (*note Interactive Codes::) optionally
 >>   >       followed by a prompt (which some code characters use and some
 >>   >       ignore).  Here is an example:
 >>   >
 >>   >            (interactive "P\nbFrobnicate buffer: ")
 >>   >
 >>   >       The code letter ‘P’ sets the command’s first argument to the raw
 >>   >       command prefix (*note Prefix Command Arguments::).  ‘bFrobnicate
 >>   >       buffer: ’ prompts the user with ‘Frobnicate buffer: ’ to enter the
 >>   >       name of an existing buffer, which becomes the second and final
 >>   >       argument.
 >>
 >> That text is all right and yet was incomprehensible for me at first
 >> (and second) reading.  It's probably just me, so ignore that.
 >
 > Maybe we should improve it.  But I cannot tell how, because "a
 > sequence of elements separated by newlines, one for each argument" is
 > very clear for me.  If you can tell what was incomprehensible in that,
 > maybe we will be able to come up with an improvement.

The text is too perfect with two cross references, a footnote and an
example with a hacker idiom.  Not a single redundancy, not a word to
miss.  Probably too terse for me.

martin

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

[Drew Adams]

>  >> That text is all right and yet was incomprehensible for me at first
>  >> (and second) reading.  It's probably just me, so ignore that.
>  >
>  > Maybe we should improve it.  But I cannot tell how, because "a
>  > sequence of elements separated by newlines, one for each argument" is
>  > very clear for me.  If you can tell what was incomprehensible in that,
>  > maybe we will be able to come up with an improvement.
> 
> The text is too perfect with two cross references, a footnote and an
> example with a hacker idiom.  Not a single redundancy, not a word to
> miss.  Probably too terse for me.

I wonder if it would help to give an example where
we show correspondence between a spec that uses a
string argument to `interactive' that specifies a
few args to the function, of different types, and
a spec that uses a Lisp sexp, which when evaluated
produces a list of those same args.

For example (doing this quickly just to show what
I mean - I'm sure we could come up with something
better):

(interactive
  (let* ((arg   current-prefix-arg)
         (narg  (prefix-numeric-value arg))
         (buf   (read-buffer "Existing buffer: "
                             (buffer-name (current-buffer))
                             t))
         (char  (read-char "Character: ")))
    (list (buf narg arg nil char))))

(interactive "bExisting buffer: \np\nP\ni\ncCharacter: ")

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

[Eli Zaretskii]

> Date: Sat, 9 Mar 2019 08:33:54 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 34749@debbugs.gnu.org
> 
> >  >> That text is all right and yet was incomprehensible for me at first
> >  >> (and second) reading.  It's probably just me, so ignore that.
> >  >
> >  > Maybe we should improve it.  But I cannot tell how, because "a
> >  > sequence of elements separated by newlines, one for each argument" is
> >  > very clear for me.  If you can tell what was incomprehensible in that,
> >  > maybe we will be able to come up with an improvement.
> > 
> > The text is too perfect with two cross references, a footnote and an
> > example with a hacker idiom.  Not a single redundancy, not a word to
> > miss.  Probably too terse for me.
> 
> I wonder if it would help to give an example where
> we show correspondence between a spec that uses a
> string argument to `interactive' that specifies a
> few args to the function, of different types, and
> a spec that uses a Lisp sexp, which when evaluated
> produces a list of those same args.

There's an example right after that text.

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

[martin rudalics]

 > For example (doing this quickly just to show what
 > I mean - I'm sure we could come up with something
 > better):
 >
 > (interactive
 >    (let* ((arg   current-prefix-arg)
 >           (narg  (prefix-numeric-value arg))
 >           (buf   (read-buffer "Existing buffer: "
 >                               (buffer-name (current-buffer))
 >                               t))
 >           (char  (read-char "Character: ")))
 >      (list (buf narg arg nil char))))
 >
 > (interactive "bExisting buffer: \np\nP\ni\ncCharacter: ")

This tells me only that our machinery permits doing things I would
never ever understand how to put into practice.  But yes, less
complicated additional examples might help.  An example with no \n
first, an example with one \n second and one with two \n's third.

But no.  I think everyone else understands this stuff well enough, so
don't bother.  It's probably some sort of reader's block with me.

martin

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

[martin rudalics]

 > Those other-* function also need to allow the user to specify a count,
 > something that we don't have to do here.  So there's no reason to
 > expect consistency here.  (I do think it would be good to allow the
 > user to control the last argument of other-window and other-frame as
 > well, if that's possible, but the solution doesn't have to be
 > identical to what we do with delete-windows-on.)

I sometimes wonder whether we try to invent a raison d'être for the
prefix argument even if there's none.  'other-window' is one example.
How are users able to calculate in advance the window that would
result from a prefix argument larger than say 1 here?  Wouldn't that
depend on the knowledge of how the window list is constructed from the
traversal of the window trees, how it wraps, where in that list the
active minibuffer window is and what the ALL-FRAMES argument is?  As a
matter of fact, I could use 'other-window' only if a frame contains at
most two windows and always use directional movement instead.

Note: This is no suggestion how things should be specified.  It only
serves to explain why I'm not able to come up with a useful proposal
here.

martin

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

[Eli Zaretskii]

> Date: Mon, 4 Mar 2019 08:25:54 -0800 (PST)
> From: 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.

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.

> 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.

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

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> 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).
>
> 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.

Eli fixed some of this, and I've now moved the interactive doc up.

> It seems like the interactive behavior is not correct, as well as being
> poorly documented.  It's hard to know just what behavior was intended,
> or what behavior would be best if (as it seems) we still need to design
> this.

I've now mapped all other non-zero interactive prefixes to t (meaning
"only this frame") in Emacs 29.  It was suggested to do further
mappings, but I don't think the other FRAME values are particularly
usable in an interactive form.

> 4. The buffer candidates available for completion (which should also be
> the only buffer names available for entry - see #3) should depend on
> which frames are used, i.e., on the prefix arg or its absence.
>
> You should be presented only with the names of buffers that are actually
> shown in windows on the frames that you've chosen to consider for
> window-deletion.

Makes sense.  I've now fixed this in Emacs 29.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Drew Adams]

> > 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.

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

[Eli Zaretskii]

> Date: Fri, 8 Mar 2019 08:34:05 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 34749@debbugs.gnu.org
> 
> > > 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.

But if the effect of the prefix arg is mapped into the non-interactive
arguments, then there's nothing more to say, right?

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

[Drew Adams]

> > I wonder if it would help to give an example where
> > we show correspondence between a spec that uses a
> > string argument to `interactive' that specifies a
> > few args to the function, of different types, and
> > a spec that uses a Lisp sexp, which when evaluated
> > produces a list of those same args.
> 
> There's an example right after that text.

I don't see an example that shows the correspondence
between a string arg and a Lisp sexp arg that returns
a list of args.

I see two examples with a string arg and (not "right
after that text") two examples of Lisp sexps (one of
which shows something you should not do).

I see no correspondence between the string examples
and the sexp examples. 

In any case, the question I pose is whether Martin
feels that some additional example(s) might help.

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

[Eli Zaretskii]

> Date: Sat, 9 Mar 2019 09:35:24 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: rudalics@gmx.at, 34749@debbugs.gnu.org
> 
> > > I wonder if it would help to give an example where
> > > we show correspondence between a spec that uses a
> > > string argument to `interactive' that specifies a
> > > few args to the function, of different types, and
> > > a spec that uses a Lisp sexp, which when evaluated
> > > produces a list of those same args.
> > 
> > There's an example right after that text.
> 
> I don't see an example that shows the correspondence
> between a string arg and a Lisp sexp arg that returns
> a list of args.

Why is it important what types are the arguments?  The issue was the
significance of the newline in the interactive spec string, and that
is independent of the types of the arguments.

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

[Drew Adams]

> > > > 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.
> 
> But if the effect of the prefix arg is mapped into the non-interactive
> arguments, then there's nothing more to say, right?

Sorry, I don't follow you.

The doc says that if the window is dedicated and alone
in its frame then the frame is deleted (provided it is
not the only frame).

And the doc (now) presumably describes prefix-arg behavior.
But a prefix arg is ignored when the window is dedicated
and alone etc.  That info too needs to be provided, e.g.
in the doc describing prefix-arg behavior.

If you've now done that, fine.

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

[Eli Zaretskii]

> Date: Fri, 8 Mar 2019 09:14:32 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 34749@debbugs.gnu.org
> 
> > > I was saying that the doc string should also mention
> > > that in this case any prefix arg you provide is ignored.
> > 
> > But if the effect of the prefix arg is mapped into the non-interactive
> > arguments, then there's nothing more to say, right?
> 
> Sorry, I don't follow you.
> 
> The doc says that if the window is dedicated and alone
> in its frame then the frame is deleted (provided it is
> not the only frame).
> 
> And the doc (now) presumably describes prefix-arg behavior.
> But a prefix arg is ignored when the window is dedicated
> and alone etc.  That info too needs to be provided, e.g.
> in the doc describing prefix-arg behavior.

What does prefix-arg have to do with this use case?  AFAIU, the answer
is "nothing", so there's nothing to be told, because the doc string
changes I made just explain how the prefix argument maps into the
FRAME argument.

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

[Drew Adams]

> > > > I wonder if it would help to give an example where
> > > > we show correspondence between a spec that uses a
> > > > string argument to `interactive' that specifies a
> > > > few args to the function, of different types, and
> > > > a spec that uses a Lisp sexp, which when evaluated
> > > > produces a list of those same args.
> > >
> > > There's an example right after that text.
> >
> > I don't see an example that shows the correspondence
> > between a string arg and a Lisp sexp arg that returns
> > a list of args.
> 
> Why is it important what types are the arguments?  The issue was the
> significance of the newline in the interactive spec string, and that
> is independent of the types of the arguments.

I don't think anyone said that it's important what
types the arguments are or whether arguments of
different types are used in the examples.

I suggested that we show correspondence between use
of a string spec and a Lisp sexp, and do so with the
use of more than one arg (so "\n" in the string spec).

Martin has not answered wrt whether he thinks doing
this would have helped him understand better.

Apparently he did not initially understand this well.
You asked him to say what parts he didn't understand
well.  I made a suggestion, guessing that it might
help.

I don't choose to argue with you about this.  Just
trying to help.

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

[Drew Adams]

> > > > I was saying that the doc string should also mention
> > > > that in this case any prefix arg you provide is ignored.
> > >
> > > But if the effect of the prefix arg is mapped into the non-interactive
> > > arguments, then there's nothing more to say, right?
> >
> > Sorry, I don't follow you.
> >
> > The doc says that if the window is dedicated and alone
> > in its frame then the frame is deleted (provided it is
> > not the only frame).
> >
> > And the doc (now) presumably describes prefix-arg behavior.
> > But a prefix arg is ignored when the window is dedicated
> > and alone etc.  That info too needs to be provided, e.g.
> > in the doc describing prefix-arg behavior.
> 
> What does prefix-arg have to do with this use case?

A user might use a prefix arg, regardless.  Telling her
that in this case the prefix arg is ignored (has nothing
to do with this case, in your words) lets her know not
to expect something; that is, this is a special case
where the prefix arg descriptions do not apply.

> AFAIU, the answer
> is "nothing", so there's nothing to be told, because the doc string
> changes I made just explain how the prefix argument maps into the
> FRAME argument.

I haven't seen the changes you made.  If it's clear now
that the prefix-arg descriptions do not apply in this
case then great.

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

[Eli Zaretskii]

> Date: Fri, 8 Mar 2019 11:48:51 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 34749@debbugs.gnu.org
> 
> > > And the doc (now) presumably describes prefix-arg behavior.
> > > But a prefix arg is ignored when the window is dedicated
> > > and alone etc.  That info too needs to be provided, e.g.
> > > in the doc describing prefix-arg behavior.
> > 
> > What does prefix-arg have to do with this use case?
> 
> A user might use a prefix arg, regardless.  Telling her
> that in this case the prefix arg is ignored (has nothing
> to do with this case, in your words) lets her know not
> to expect something; that is, this is a special case
> where the prefix arg descriptions do not apply.

The doc string already says that in this case the FRAME argument is
not consulted (by not mentioning FRAME in the description of that
case).  And after my changes the doc string explains that the prefix
arg sets the FRAME argument.  So what you want to say follows
trivially from the doc string.

> > AFAIU, the answer
> > is "nothing", so there's nothing to be told, because the doc string
> > changes I made just explain how the prefix argument maps into the
> > FRAME argument.
> 
> I haven't seen the changes you made.

May I suggest that you do?  The current sources can be viewed on
Savannah.