[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[debbugs-tracker] bug#32798: closed (26; doc string of `pop-to-buffer-sa

From: GNU bug Tracking System
Subject: [debbugs-tracker] bug#32798: closed (26; doc string of `pop-to-buffer-same-window' and similar)
Date: Mon, 24 Sep 2018 15:10:02 +0000

Your message dated Mon, 24 Sep 2018 18:09:12 +0300
with message-id <address@hidden>
and subject line Re: bug#32798: 26; doc string of `pop-to-buffer-same-window' 
and similar
has caused the debbugs.gnu.org bug report #32798,
regarding 26; doc string of `pop-to-buffer-same-window' and similar
to be marked as done.

(If you believe you have received this mail in error, please contact

32798: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=32798
GNU Bug Tracking System
Contact address@hidden with problems
--- Begin Message --- Subject: 26; doc string of `pop-to-buffer-same-window' and similar Date: Fri, 21 Sep 2018 09:43:29 -0700 (PDT)

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



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



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



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.



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



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


--- End Message ---
--- Begin Message --- 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 <address@hidden>
> Cc: address@hidden
> 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.

--- End Message ---

reply via email to

[Prev in Thread] Current Thread [Next in Thread]