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

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Drew Adams <drew.adams <at> oracle.com>
Subject: bug#21305: closed (Re: bug#21305: 25.0.50; `get-buffer-window-list'
 doc - what order?)
Date: Fri, 21 Aug 2015 15:22:02 +0000

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

Your bug report

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

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to 21305 <at> debbugs.gnu.org.

-- 
21305: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=21305
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

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 part 3 (message/rfc822, inline)]

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'

Previous Next

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