GNU bug report logs - #21305
25.0.50; `get-buffer-window-list' doc - what order?

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 21305 in the body.
You can then email your comments to 21305 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Thu, 20 Aug 2015 10:49:26 -0700 (PDT)

The doc string says: "Windows are scanned starting with the selected
window."  What does that mean?  Scanned?  How so?  In what order are
they scanned (besides starting with selected)?  And how is the scanning
used?

What I would really like to know should have little or nothing to do
with "scanning".  It is what order the list is in.  Details of how the
function computes the list are not so important, but if you have to tell
us that in order to specify the resulting order, so be it.

Please update both the doc string and (elisp) `Buffers and Windows'
to tell us what order the list is in.


In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2015-07-31 on LEG570
Bzr revision: 8d332aeccab2208e6c6bd434738565e6abf12043
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --host=i686-pc-mingw32 --enable-checking=yes,glyphs'

Message #8 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 21305 <at> debbugs.gnu.org
Subject: Re: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Fri, 21 Aug 2015 15:56:42 +0300

> Date: Thu, 20 Aug 2015 10:49:26 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> 
> The doc string says: "Windows are scanned starting with the selected
> window."  What does that mean?  Scanned?  How so?  In what order are
> they scanned (besides starting with selected)?  And how is the scanning
> used?

I replaced that sentence with this one:

  If the selected window displays BUFFER-OR-NAME, it will be the first
  in the resulting list.

Do you see any issues left after that change?  (I don't.)

> Please update both the doc string and (elisp) `Buffers and Windows'
> to tell us what order the list is in.

The order is unspecified, which means the caller should not depend on
it.  I don't think there's anything wrong with that; do you?

Message #11 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21305 <at> debbugs.gnu.org
Subject: RE: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Fri, 21 Aug 2015 06:21:18 -0700 (PDT)

> > The doc string says: "Windows are scanned starting with the
> > selected window."  What does that mean?  Scanned?  How so?
> > In what order are they scanned (besides starting with selected)?
> > And how is the scanning used?
> 
> I replaced that sentence with this one:
> 
>   If the selected window displays BUFFER-OR-NAME, it will be the
>   first in the resulting list.
> 
> Do you see any issues left after that change?  (I don't.)
> 
> > Please update both the doc string and (elisp) `Buffers and
> > Windows' to tell us what order the list is in.
> 
> The order is unspecified, which means the caller should not depend
> on it.  I don't think there's anything wrong with that; do you?

Well, it's certainly the prerogative of designers to decide that
the order is undefined and that users cannot depend on it.  In
that case, you can close the bug now.

But as one user I'm disappointed.  I was hoping for a usable
window order.  In fact, I was hoping for something similar to
`buffer-list' - hoping that users would get a list of the windows
(displaying a particular buffer) in order of their last use.

I know no way to obtain such a list, but if there is one, please
be so kind as to let me know.  `walk-windows' etc. go through
windows in their "structural" order, but how can I tell, given
a list of windows showing a given buffer, which were last used
after which others?

Yes, my question is outside the scope of this bug (if the list
`get-buffer-window-list' has no order we can depend on or even
if its order is unrelated to the chronological order of access).

Thanks for fixing the doc string.

Message #14 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 21305 <at> debbugs.gnu.org
Subject: Re: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Fri, 21 Aug 2015 16:51:35 +0300

> Date: Fri, 21 Aug 2015 06:21:18 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 21305 <at> debbugs.gnu.org
> 
> > The order is unspecified, which means the caller should not depend
> > on it.  I don't think there's anything wrong with that; do you?
> 
> Well, it's certainly the prerogative of designers to decide that
> the order is undefined and that users cannot depend on it.  In
> that case, you can close the bug now.
> 
> But as one user I'm disappointed.  I was hoping for a usable
> window order.

It's the order of traversing the window tree depth-first (as described
in the ELisp manual under "Cyclic Window Ordering").  I don't see how
saying that would be of any help to users of this function.
Describing the order would require a non-trivial amount of text, so
without a good reason, I don't think we should add it.

Message #17 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21305 <at> debbugs.gnu.org
Subject: RE: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Fri, 21 Aug 2015 08:08:25 -0700 (PDT)

> > > The order is unspecified, which means the caller should not
> > > depend on it.  I don't think there's anything wrong with that;
> > > do you?
> >
> > Well, it's certainly the prerogative of designers to decide that
> > the order is undefined and that users cannot depend on it.  In
> > that case, you can close the bug now.
> >
> > But as one user I'm disappointed.  I was hoping for a usable
> > window order.
> 
> It's the order of traversing the window tree depth-first (as
> described in the ELisp manual under "Cyclic Window Ordering").

If so, then the order is not undefined.  (It's a design decision
whether Emacs wants to commit to supporting this order or just
tell users that the order is undefined, keeping its options open.)

> I don't see how saying that would be of any help to users of this
> function.

Well, it apparently won't help me in my quest for a chronological
ordering of windows for the same buffer by access time.

But I think it would be helpful to tell users that the order is
the same as that described in `Cyclic Window Ordering'.

> Describing the order would require a non-trivial amount of text, so
> without a good reason, I don't think we should add it.

How is it more difficult than saying that the order is the same as
that specified in `Cyclic Window Ordering', and xreffing that node?

Perhaps I'm missing something.  And I will leave it up to you to
decide what, if anything, should be said about the order.  Thanks
for thinking about it.

Message #22 received at 21305-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 21305-done <at> debbugs.gnu.org
Subject: Re: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Fri, 21 Aug 2015 18:21:18 +0300

> Date: Fri, 21 Aug 2015 08:08:25 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 21305 <at> debbugs.gnu.org
> 
> > > > The order is unspecified, which means the caller should not
> > > > depend on it.  I don't think there's anything wrong with that;
> > > > do you?
> > >
> > > Well, it's certainly the prerogative of designers to decide that
> > > the order is undefined and that users cannot depend on it.  In
> > > that case, you can close the bug now.
> > >
> > > But as one user I'm disappointed.  I was hoping for a usable
> > > window order.
> > 
> > It's the order of traversing the window tree depth-first (as
> > described in the ELisp manual under "Cyclic Window Ordering").
> 
> If so, then the order is not undefined.

I didn't say "undefined", I said "unspecified".

> > I don't see how saying that would be of any help to users of this
> > function.
> 
> Well, it apparently won't help me in my quest for a chronological
> ordering of windows for the same buffer by access time.
> 
> But I think it would be helpful to tell users that the order is
> the same as that described in `Cyclic Window Ordering'.

What can the users do with that information?  (It is already in the
ELisp manual; I'm talking about the doc string here.)

> > Describing the order would require a non-trivial amount of text, so
> > without a good reason, I don't think we should add it.
> 
> How is it more difficult than saying that the order is the same as
> that specified in `Cyclic Window Ordering', and xreffing that node?

I consider references to the manual in doc strings a bad habit.

I'm closing the bug.

Message #25 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: martin rudalics <rudalics <at> gmx.at>
To: Drew Adams <drew.adams <at> oracle.com>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 21305 <at> debbugs.gnu.org
Subject: Re: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Fri, 21 Aug 2015 17:28:06 +0200

> But as one user I'm disappointed.  I was hoping for a usable
> window order.  In fact, I was hoping for something similar to
> `buffer-list' - hoping that users would get a list of the windows
> (displaying a particular buffer) in order of their last use.
>
> I know no way to obtain such a list, but if there is one, please
> be so kind as to let me know.  `walk-windows' etc. go through
> windows in their "structural" order, but how can I tell, given
> a list of windows showing a given buffer, which were last used
> after which others?
>
> Yes, my question is outside the scope of this bug (if the list
> `get-buffer-window-list' has no order we can depend on or even
> if its order is unrelated to the chronological order of access).

I suppose you mean that we should document `window-use-time' too.
Correct?

martin

Message #28 received at 21305-done <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 21305-done <at> debbugs.gnu.org
Subject: RE: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Fri, 21 Aug 2015 08:28:18 -0700 (PDT)

> > But I think it would be helpful to tell users that the order is
> > the same as that described in `Cyclic Window Ordering'.
> 
> What can the users do with that information?  (It is already in the
> ELisp manual; I'm talking about the doc string here.)

In the manual?  Where?  I don't see it, so far (in the build I have
from 7/31.  I do see that the manual says this, but this speaks only
to the meaning of these two arguments - it says nothing about the
order of the windows in the returned value.

  The arguments MINIBUF and ALL-FRAMES have the same meanings as in
                ^^^^^^^^^^^^^^^^^^^^^^
  the function 'next-window' (*note Cyclic Window Ordering::).  Note
  that the ALL-FRAMES argument does _not_ behave exactly like in
  'get-buffer-window'. 

> > > Describing the order would require a non-trivial amount of text,
> > > so without a good reason, I don't think we should add it.
> >
> > How is it more difficult than saying that the order is the same as
> > that specified in `Cyclic Window Ordering', and xreffing that
> > node?
> 
> I consider references to the manual in doc strings a bad habit.

I meant in the manual.  There is an xref to that node, but it is
given only for info about arguments MINIBUF and ALL-FRAMES.  It would
be helpful, I think, to explicitly say that the order of the windows
in the return value (a) starts with the selected window (which you
have added) and (b) follows the order cyclic window ordering.

Message #31 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: martin rudalics <rudalics <at> gmx.at>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 21305 <at> debbugs.gnu.org
Subject: RE: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Fri, 21 Aug 2015 08:30:52 -0700 (PDT)

>  > But as one user I'm disappointed.  I was hoping for a usable
>  > window order.  In fact, I was hoping for something similar to
>  > `buffer-list' - hoping that users would get a list of the windows
>  > (displaying a particular buffer) in order of their last use.
>  >
>  > I know no way to obtain such a list, but if there is one, please
>  > be so kind as to let me know.  `walk-windows' etc. go through
>  > windows in their "structural" order, but how can I tell, given
>  > a list of windows showing a given buffer, which were last used
>  > after which others?
>  >
>  > Yes, my question is outside the scope of this bug (if the list
>  > `get-buffer-window-list' has no order we can depend on or even
>  > if its order is unrelated to the chronological order of access).
> 
> I suppose you mean that we should document `window-use-time' too.
> Correct?

Oh, yes; please do.  I was unaware of it.  I can map that over 
`get-buffer-window-list' or otherwise filter that list wrt use time.
Very good.  Thx.  Somehow, I wasn't able to find this, which was
for me a missing piece.

Message #34 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: martin rudalics <rudalics <at> gmx.at>
To: Drew Adams <drew.adams <at> oracle.com>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 21305 <at> debbugs.gnu.org
Subject: Re: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Fri, 21 Aug 2015 17:58:27 +0200

>> I suppose you mean that we should document `window-use-time' too.
>> Correct?
>
> Oh, yes; please do.

Done.

martin

Message #37 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: martin rudalics <rudalics <at> gmx.at>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 21305 <at> debbugs.gnu.org
Subject: RE: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Fri, 21 Aug 2015 09:00:54 -0700 (PDT)

> >> I suppose you mean that we should document `window-use-time' too.
> >> Correct?
> >
> > Oh, yes; please do.
> 
> Done.

Great.  Thx.

Message #40 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: martin rudalics <rudalics <at> gmx.at>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 21305 <at> debbugs.gnu.org
Subject: RE: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Fri, 21 Aug 2015 09:12:08 -0700 (PDT)

BTW, it would be nice to know whether `get-buffer-window-list'
returns a new list or returns a list that is pointed to (used)
by something else.

In particular, it would be good to know whether one can use
`sort' on it (e.g., `sort' according to `window-use-time')
without bothering something else somewhere.  I'm supposing so.

Message #43 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: martin rudalics <rudalics <at> gmx.at>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 21305 <at> debbugs.gnu.org
Subject: RE: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Fri, 21 Aug 2015 09:32:16 -0700 (PDT)

Sorry for drifting from the bug, but is something like this useful
generally?  I will use it, but I'm thinking others might also.

(defun mru-window-for-buffer (buffer &optional minibuf all-frames)
  "Return the most recently used window for BUFFER.
Optional args MINIBUF and ALL-FRAMES are as for `get-buffer-window-list'."
  (let* ((wins     (get-buffer-window-list buffer minibuf all-frames))
         (mru-win  (car wins)))
    (dolist (win  (cdr wins))
      (unless  (time-less-p win mru-win) (setq mru-win  win)))
    mru-win))

Similary, `lru-window-for-buffer'.

Message #46 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: martin rudalics <rudalics <at> gmx.at>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 21305 <at> debbugs.gnu.org
Subject: RE: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Fri, 21 Aug 2015 10:42:18 -0700 (PDT)

> (defun mru-window-for-buffer (buffer &optional minibuf all-frames)
>   "Return the most recently used window for BUFFER.
> Optional args MINIBUF and ALL-FRAMES are as for `get-buffer-window-
> list'."
>   (let* ((wins     (get-buffer-window-list buffer minibuf all-frames))
>          (mru-win  (car wins)))
>     (dolist (win  (cdr wins))
>       (unless  (time-less-p win mru-win) (setq mru-win  win)))
>     mru-win))
> 
> Similarly, `lru-window-for-buffer'.

Sorry, I meant something like this:

(defun mru-window-for-buffer (buffer &optional minibuf all-frames)
  "Return the most recently used window for BUFFER.
Optional args MINIBUF and ALL-FRAMES are as for `get-buffer-window-list'."
  (let* ((wins      (get-buffer-window-list buffer minibuf all-frames))
         (mru-win   (car wins))
         (mru-time  (window-use-time mru-win))
         wtime)
    (dolist (win  (cdr wins))
      (when  (time-less-p (setq wtime  (window-use-time win)) mru-time)
        (setq mru-time  wtime
              mru-win   win)))
    mru-win))

Message #49 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 21305 <at> debbugs.gnu.org
Subject: Re: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Fri, 21 Aug 2015 21:28:56 +0300

> Date: Fri, 21 Aug 2015 08:28:18 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 21305-done <at> debbugs.gnu.org
> 
> > > But I think it would be helpful to tell users that the order is
> > > the same as that described in `Cyclic Window Ordering'.
> > 
> > What can the users do with that information?  (It is already in the
> > ELisp manual; I'm talking about the doc string here.)
> 
> In the manual?  Where?  I don't see it, so far (in the build I have
> from 7/31.  I do see that the manual says this, but this speaks only
> to the meaning of these two arguments - it says nothing about the
> order of the windows in the returned value.
> 
>   The arguments MINIBUF and ALL-FRAMES have the same meanings as in
>                 ^^^^^^^^^^^^^^^^^^^^^^
>   the function 'next-window' (*note Cyclic Window Ordering::).  Note
>   that the ALL-FRAMES argument does _not_ behave exactly like in
>   'get-buffer-window'. 

In the cross-referenced node.

> I meant in the manual.  There is an xref to that node, but it is
> given only for info about arguments MINIBUF and ALL-FRAMES.

No, it's not.  It actually tells you that this function traverses the
window as next-window does.

Once again, I think this order is random for all practical purposes,
as far as the caller is concerned.  I was actually surprised to see it
documented in the manual.

Message #52 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21305 <at> debbugs.gnu.org
Subject: RE: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Fri, 21 Aug 2015 12:18:37 -0700 (PDT)

> > In the manual?  Where?  I don't see it, so far (in the build I
> > have from 7/31.  I do see that the manual says this, but this
> > speaks only to the meaning of these two arguments - it says
> > nothing about the order of the windows in the returned value.
> >
> >   The arguments MINIBUF and ALL-FRAMES have the same meanings as
> >                 ^^^^^^^^^^^^^^^^^^^^^^
> >   in the function 'next-window' (*note Cyclic Window Ordering::).
> 
> In the cross-referenced node.

It sends you to that node for an entirely different purpose -
not for information about the order of the returned value.  The
xref is even part of the _same sentence_ as the statement about
the args.  It is not a separate sentence telling to go see that
node for more info about the function as a whole.  And it certainly
is not hinting that you will discover there something about the
order of the function's return value.

If I tell you that you can get a great bagel at Schlomo's Deli,
would you expect that you might also get a great car wash there?

> > I meant in the manual.  There is an xref to that node, but it is
> > given only for info about arguments MINIBUF and ALL-FRAMES.
> 
> No, it's not.  It actually tells you that this function traverses
> the window as next-window does.

The xref'd node does.  But the xref is explicitly "given only for
info about arguments MINIBUF and ALL-FRAMES."  A minor change
would make it clear that that node also tells you something about
the order of the return value.  (It would still be better to
document the return value completely in the source node, and send
readers to the xref for _additional_ info.

> Once again, I think this order is random for all practical purposes,
> as far as the caller is concerned.  I was actually surprised to see
> it documented in the manual.

Again, either Emacs decides that it wants to specify nothing
about the order, and says it is unspecified, or it decides it
wants to tell users what the order is (and so commits, to some
extent, to that order, e.g., including for the future).

It's your choice.  What is the design?  Do you want to expose
this as by design, and tell users about it so they can take
advantage of it, or do you want to tell users not to depend
on the currently implemented order?

Message #55 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: martin rudalics <rudalics <at> gmx.at>
To: Drew Adams <drew.adams <at> oracle.com>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 21305 <at> debbugs.gnu.org
Subject: Re: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Sat, 22 Aug 2015 08:40:26 +0200

> Sorry, I meant something like this:
>
> (defun mru-window-for-buffer (buffer &optional minibuf all-frames)

`get-buffer-window-list' is in window.el.  Couldn't you try giving it a
fourth argument, say SORT, which, if `lru-first' or `mru-first', would
cause it to return the windows in the corresponding order?

martin

Message #58 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: martin rudalics <rudalics <at> gmx.at>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 21305 <at> debbugs.gnu.org
Subject: RE: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Sat, 22 Aug 2015 07:31:38 -0700 (PDT)

[Message part 1 (text/plain, inline)]

> `get-buffer-window-list' is in window.el.  Couldn't you try giving
> it a fourth argument, say SORT, which, if `lru-first' or `mru-first',
> would cause it to return the windows in the corresponding order?

Patch attached.

[window-2015-08-22.patch (application/octet-stream, attachment)]

Message #61 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: martin rudalics <rudalics <at> gmx.at>, Eli Zaretskii <eliz <at> gnu.org>,
 21305 <at> debbugs.gnu.org
Subject: Re: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Sat, 22 Aug 2015 12:01:38 -0400

>> `get-buffer-window-list' is in window.el.  Couldn't you try giving
>> it a fourth argument, say SORT, which, if `lru-first' or `mru-first',
>> would cause it to return the windows in the corresponding order?
> Patch attached.

FWIW, I think adding an argument for that is a bad idea.  If the caller
needs the windows sorted in a particular way, then *he* should
sort them.

It would make sense to provide sorting directly in the function if the
sorting can't be done, or not as efficiently, after the fact.
But that is not the case here.


        Stefan

Message #64 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: martin rudalics <rudalics <at> gmx.at>, Eli Zaretskii <eliz <at> gnu.org>,
 21305 <at> debbugs.gnu.org
Subject: RE: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Sat, 22 Aug 2015 10:23:22 -0700 (PDT)

> >> `get-buffer-window-list' is in window.el.  Couldn't you try
> >> giving it a fourth argument, say SORT, which, if `lru-first'
> >> or `mru-first', would cause it to return the windows in the 
> >> corresponding order?
> >
> > Patch attached.
> 
> FWIW, I think adding an argument for that is a bad idea.  If the
> caller needs the windows sorted in a particular way, then *he*
> should sort them.

(S?he should know whether the return value of `get-buffer-window-list'
is a new list (it is), so that `sort' can be applied to it without
causing problems elsewhere.  For that, s?he will want to consult the
code of `get-buffer-window-list'.)

> It would make sense to provide sorting directly in the function if
> the sorting can't be done, or not as efficiently, after the fact.
> But that is not the case here.

I don't disagree.  What was not obvious was how you might sort
windows wrt last-use time.  But IIUC, Martin has now updated the
manual to mention `window-use-time', of which I was unaware.

What I suggested was not to add a SORT arg to `get-buffer-window-list'
but to add functions such as `(mru|lru)-window-for-buffer'.  (It was
for the latter that I was interested in `get-buffer-window-list'.)

Message #67 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: rudalics <at> gmx.at, 21305 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Sat, 22 Aug 2015 20:30:57 +0300

> Date: Sat, 22 Aug 2015 10:23:22 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: martin rudalics <rudalics <at> gmx.at>, Eli Zaretskii <eliz <at> gnu.org>,
>         21305 <at> debbugs.gnu.org
> 
> > FWIW, I think adding an argument for that is a bad idea.  If the
> > caller needs the windows sorted in a particular way, then *he*
> > should sort them.
> 
> (S?he should know whether the return value of `get-buffer-window-list'
> is a new list (it is), so that `sort' can be applied to it without
> causing problems elsewhere.  For that, s?he will want to consult the
> code of `get-buffer-window-list'.)

I see no reason for consulting the source code, just to know whether
it's safe to sort that list.  It would be silly, to say the least, for
Emacs to give Lisp programs direct access to a list that is used
internally by Emacs and whose order is important.  IOW, it is safe to
assume that the returned list can be freely manipulated.

Message #70 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: rudalics <at> gmx.at, 21305 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: RE: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Sat, 22 Aug 2015 12:01:59 -0700 (PDT)

> > (S?he should know whether the return value of `get-buffer-window-
> > list' is a new list (it is), so that `sort' can be applied to it
> > without causing problems elsewhere.  For that, s?he will want to
> > consult the code of `get-buffer-window-list'.)
> 
> I see no reason for consulting the source code, just to know whether
> it's safe to sort that list.  It would be silly, to say the least,
> for Emacs to give Lisp programs direct access to a list that is used
> internally by Emacs and whose order is important.  IOW, it is safe
> to assume that the returned list can be freely manipulated.

Good to know.  So any lists returned by functions in the source
code are either new (conses) or there is no source code that
points to them.  That makes sense, but I wasn't sure it was sure
to be the case.

Message #73 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: martin rudalics <rudalics <at> gmx.at>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>, 
 Drew Adams <drew.adams <at> oracle.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 21305 <at> debbugs.gnu.org
Subject: Re: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Sun, 23 Aug 2015 15:33:46 +0200

> FWIW, I think adding an argument for that is a bad idea.  If the caller
> needs the windows sorted in a particular way, then *he* should
> sort them.
>
> It would make sense to provide sorting directly in the function if the
> sorting can't be done, or not as efficiently, after the fact.
> But that is not the case here.

If I want to write or provide functions like ‘mru-window-for-buffer’ or
‘lru-window-for-buffer’, then such a function could easily use the car
of `get-buffer-window-list' called with the appropriate argument.  So I
don't see why adding an argument would be a "bad idea".

martin

Message #76 received at 21305 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: rudalics <at> gmx.at, Eli Zaretskii <eliz <at> gnu.org>, 21305 <at> debbugs.gnu.org
Subject: Re: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Sun, 23 Aug 2015 18:34:44 -0400

> points to them.  That makes sense, but I wasn't sure it was sure
> to be the case.

I wouldn't say it's sure to be the case, but if/when it's not the case, then
either I'd consider it a bug, or the docstring should make it clear.


        Stefan

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.