|Subject:||bug#32798: 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:
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
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)
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 10.0.16299
`configure --without-dbus --host=x86_64-w64-mingw32
--without-compress-install 'CFLAGS=-O2 -static -g3''
|[Prev in Thread]||Current Thread||[Next in Thread]|