GNU bug report logs - #32798
26; doc string of `pop-to-buffer-same-window' and similar

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 32798 in the body.
You can then email your comments to 32798 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: 26; doc string of `pop-to-buffer-same-window' and similar
Date: Fri, 21 Sep 2018 09:43:29 -0700 (PDT)

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

The doc string of `pop-to-buffer-same-window' doesn't describe the

behavior well enough.  Similar problems exist with other doc strings

that now, in essence, just send you down the rabbit holes of

`display-buffer' and `display-buffer-alist'.

 

Contrast the doc string of `switch-to-buffer', for which `p-t-b-s-w' is

often (rightfully) promoted as a replacement.  There you see a

description of the behavior for a dedicated window, for example:

 

  If the selected window is dedicated ('window-dedicated-p'), then use

  another window, regardless of argument FORCE-SAME-WINDOW.

 

Clear, simple.  What does `p-t-b-s-w' do if the selected window is

dedicated? Let's find out...

 

Unfortunately, ever since `display-buffer-alist' came along it seems

that the doc of specific functions pretty much just punt, forcing you

to follow a long and winding search thread to learn their actual

behavior.

 

For `p-t-b-s-w', for example, if you want to find out the particulars

then you need to do something like this:

 

1. You try `C-h f pop-to-buffer-same-window'. It says only "in some

window, preferably the same one".  (Preferably how?  What if the

window is dedicated?)

 

2. You go to the `p-t-b-s-w' source code, which you see is just this:

 

  (pop-to-buffer buffer display-buffer--same-window-action norecord)

 

Great; very simple code.  What does it mean?

 

3. You use `C-h v display-buffer--same-window-action' (an "internal"

variable?) to find ... essentially no new info - an "action for

displaying in the same window".  A wasted detour, but the only thing

that was specific in that invocation of `pop-to-buffer'.

 

4. So you try `C-h f pop-to-buffer' (or click the link from the

`p-t-b-s-w' doc), where you find only a reference to `display-buffer'

and mention of its ACTION argument.  Hm, what's this?

 

5. You use `C-h f display-buffer' (or click the link from the `p-t-b'

doc) ... and you spend a day or two trying to make some sense of

the description of parameter ACTION.  Only half-kidding.

 

6. In spite of your time spent with the `d-b' doc, you still don't know

what the `p-t-b-s-w' behavior is.  So maybe you go back and look at `C-h

v display-buffer--same-window-action' again - and this time you look

closer at the value, not the doc:

 

  (display-buffer-same-window (inhibit-same-window))

 

You make an effort to realize that this list doesn't represent code that

invokes function `d-b-s-w' with argument `(i-s-w)'.  It's instead just

an alist whose car happens to be a function name.  (But perhaps you

mistakenly take another wasted detour here with `C-h f d-b-s-w'.)

 

7. Anyway, you now have the `display-buffer' ACTION alist, so you go

back to `C-h f display-buffer' to try some more to figure out the

behavior.

 

Deciphering the `d-b' doc, you now see that FUNCTION in this case is

`d-b-s-w', and the ALIST is `((inhibit-same-window))'.  You instantiate

the description to understand that `d-b-s-w' gets invoked with "two

arguments: the buffer to display" and the alist

`((inhibit-same-window))'.

 

Finally you feel you almost have it - you must be getting very close to

a description of `p-b-s-w'.  What `pop-to-buffer-same-window' does is

invoke `display-buffer-same-window', passing it the buffer to display

and `((inhibit-same-window))'.

 

8. So now you try `C-f display-buffer-same-window'.  There you see that

the buffer is displayed in the same window unless `inhibit-same-window'

has a nil value in the ALIST entry (not the case here), or the window is

a minibuffer, or it is dedicated to another buffer.

 

BRAVO!  You've finally found out what `pop-to-buffer-same-window' does

if the window is dedicated.  Well, almost - it would have been better

if, like the doc of `switch-to-buffer', there was a mention of

`window-dedicated-p' (with a link) - which tells you just what it means

for a window to be dedicated.

 

Could the doc for `p-t-b-s-w' have referred directly to `d-b-s-w"? Better

yet, could it have described that display behavior (and perhaps

mentioned `d-b-s-w')? You betcha.

 

Moral:

Doc of `switch-to-buffer': simple and clear.

Doc of  `pop-to-buffer-same-window': not so much.

 

Doc of specific functions should be specific.  The goal is not maximum

factorization - sending all doc strings down the rabbit hole of

`display-buffer'.

 

A user should get a fairly complete description for each function s?he

checks with `C-h f'.  Extreme factoring might sometimes be OK for the

Elisp manual - there it can make sense to guide readers toward

`display-buffer'.  But a doc string should not force you to follow a

long and winding path through the forest.  It should invite you to

explorer further with links - sure, but you should not have to follow

multiple links just to find out what the function you asked about does.

 

---

 

[BTW: The `d-b-s-w' doc says "has a non-nil `inhibit-same-window'

entry", which is not clear/correct.  It should say something like "has

an `inhibit-same-window' entry whose cdr is non-nil.  Alist entry

`(inhibit-same-window)' is a cons - it is not nil, but it is presumably

not what was intended by "a non-nil `i-s-w' entry".]

 

[BTW2: The `d-b' doc is wrong in saying, on the one hand, that FUNCTION

is either a function or a list of functions, and on the other hand,

"Each such FUNCTION...".  That should presumably be "Each such

function".  Otherwise, if FUNCTION is, say, `(foo bar toto)' then it

means "Each `(foo bar toto)'..." instead of each of `foo', `bar', and

`toto'...".  The latter is presumably what was intended.]

 

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

Configured using:

`configure --without-dbus --host=x86_64-w64-mingw32

--without-compress-install 'CFLAGS=-O2 -static -g3''

 

[Message part 2 (text/html, inline)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 32798 <at> debbugs.gnu.org
Subject: Re: bug#32798: 26;
 doc string of `pop-to-buffer-same-window' and similar
Date: Sat, 22 Sep 2018 13:23:54 +0300

> Date: Fri, 21 Sep 2018 09:43:29 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> 
> The doc string of `pop-to-buffer-same-window' doesn't describe the
> behavior well enough.  Similar problems exist with other doc strings
> that now, in essence, just send you down the rabbit holes of
> `display-buffer' and `display-buffer-alist'.

Since you have already read the relevant code and documentation, I
hope you could suggest how to improve the existing documentation of
pop-to-buffer-same-window.  Bonus points for providing a
ready-to-apply patch.

Thanks.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: drew.adams <at> oracle.com
Cc: 32798-done <at> debbugs.gnu.org
Subject: Re: bug#32798: 26;
 doc string of `pop-to-buffer-same-window' and similar
Date: Mon, 24 Sep 2018 18:09:12 +0300

> Date: Sat, 22 Sep 2018 13:23:54 +0300
> From: Eli Zaretskii <eliz <at> gnu.org>
> Cc: 32798 <at> debbugs.gnu.org
> 
> Since you have already read the relevant code and documentation, I
> hope you could suggest how to improve the existing documentation of
> pop-to-buffer-same-window.  Bonus points for providing a
> ready-to-apply patch.

No luck there, so I clarified/improved the relevant doc strings as
best I could, and I'm marking this bug done.

Previous Next

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