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

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

[Drew Adams]

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

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

[Eli Zaretskii]

> Date: Fri, 21 Aug 2015 08:28:18 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 21305-done@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.

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

[Drew Adams]

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

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

[Drew Adams]

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

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

[Eli Zaretskii]

> Date: Fri, 21 Aug 2015 08:08:25 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 21305@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.

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

[Drew Adams]

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

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

[Stefan Monnier]

> 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

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

[Drew Adams]

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

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

[Eli Zaretskii]

> Date: Fri, 21 Aug 2015 06:21:18 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 21305@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.

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

[martin rudalics]

 > 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

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

[Drew Adams]

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

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

[martin rudalics]

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

Done.

martin

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

[Drew Adams]

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'

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

[Eli Zaretskii]

> Date: Thu, 20 Aug 2015 10:49:26 -0700 (PDT)
> From: Drew Adams <drew.adams@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?

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

[Drew Adams]

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.

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

[Drew Adams]

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

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

[Drew Adams]

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

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

[martin rudalics]

 > 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

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

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 228 bytes --]

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

[-- Attachment #2: window-2015-08-22.patch --]
[-- Type: application/octet-stream, Size: 2238 bytes --]

diff -uw window.el window-patched-2015-08-22.el
--- window.el	2015-08-22 07:17:03.887665500 -0700
+++ window-patched-2015-08-22.el	2015-08-22 07:26:37.984069400 -0700
@@ -2296,11 +2296,10 @@
 	  (setq best-window window))))
     best-window))
 
-(defun get-buffer-window-list (&optional buffer-or-name minibuf all-frames)
+(defun get-buffer-window-list (&optional buffer-or-name minibuf all-frames sort)
   "Return list of all windows displaying BUFFER-OR-NAME, or nil if none.
 BUFFER-OR-NAME may be a buffer or the name of an existing buffer
-and defaults to the current buffer.  If the selected window displays
-BUFFER-OR-NAME, it will be the first in the resulting list.
+and defaults to the current buffer.
 
 MINIBUF t means include the minibuffer window even if the
 minibuffer is not active.  MINIBUF nil or omitted means include
@@ -2324,14 +2323,28 @@
 
 - A frame means consider all windows on that frame only.
 
-Anything else means consider all windows on the selected frame
-and no others."
+Anything else for ALL-FRAMES means consider all windows on the
+selected frame and no others.
+
+By default (SORT is nil), the order of the windows in the result is
+unspecified, except that if the selected window shows BUFFER-OR-NAME
+then it is first.
+
+Non-nil SORT means return the windows sorted by last use time:
+- `mru' means most  recently used comes first
+- `lru' means least recently used comes first"
   (let ((buffer (window-normalize-buffer buffer-or-name))
 	windows)
     (dolist (window (window-list-1 (selected-window) minibuf all-frames))
-      (when (eq (window-buffer window) buffer)
-	(setq windows (cons window windows))))
-    (nreverse windows)))
+      (when (eq (window-buffer window) buffer)	(setq windows  (cons window windows))))
+    (setq windows  (nreverse windows))
+    (when sort
+      (let ((pred  (case sort
+                     (lru (lambda (w1 w2) (time-less-p (window-use-time w1) (window-use-time w2))))
+                     (mru (lambda (w1 w2) (time-less-p (window-use-time w2) (window-use-time w1)))))))
+        (setq windows  (sort windows pred))))
+    windows))
+
 
 (defun minibuffer-window-active-p (window)
   "Return t if WINDOW is the currently active minibuffer window."

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

[Stefan Monnier]

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

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

[Drew Adams]

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

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

[Eli Zaretskii]

> Date: Sat, 22 Aug 2015 10:23:22 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: martin rudalics <rudalics@gmx.at>, Eli Zaretskii <eliz@gnu.org>,
>         21305@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.

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

[martin rudalics]

 > 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

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

[Drew Adams]

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

Great.  Thx.