From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#32798: 26; doc string of `pop-to-buffer-same-window' and similar Date: Fri, 21 Sep 2018 09:43:29 -0700 (PDT) Message-ID: NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="__1537548210230306439abhmp0015.oracle.com" X-Trace: blaine.gmane.org 1537548202 11441 195.159.176.226 (21 Sep 2018 16:43:22 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 21 Sep 2018 16:43:22 +0000 (UTC) To: 32798@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Sep 21 18:43:18 2018 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1g3OWS-0002p5-ED for geb-bug-gnu-emacs@m.gmane.org; Fri, 21 Sep 2018 18:43:16 +0200 Original-Received: from localhost ([::1]:56545 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g3OYZ-0000lg-3k for geb-bug-gnu-emacs@m.gmane.org; Fri, 21 Sep 2018 12:45:27 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:46959) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g3OYL-0000ij-QU for bug-gnu-emacs@gnu.org; Fri, 21 Sep 2018 12:45:18 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g3OYC-0002RM-SD for bug-gnu-emacs@gnu.org; Fri, 21 Sep 2018 12:45:10 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:44148) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1g3OYB-0002Qc-Jh for bug-gnu-emacs@gnu.org; Fri, 21 Sep 2018 12:45:04 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1g3OYB-0005Fw-D6 for bug-gnu-emacs@gnu.org; Fri, 21 Sep 2018 12:45:03 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 21 Sep 2018 16:45:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 32798 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.153754826820126 (code B ref -1); Fri, 21 Sep 2018 16:45:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 21 Sep 2018 16:44:28 +0000 Original-Received: from localhost ([127.0.0.1]:48406 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1g3OXc-0005EY-4i for submit@debbugs.gnu.org; Fri, 21 Sep 2018 12:44:28 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:53679) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1g3OXa-0005EJ-8M for submit@debbugs.gnu.org; Fri, 21 Sep 2018 12:44:27 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g3OXF-0001aQ-7s for submit@debbugs.gnu.org; Fri, 21 Sep 2018 12:44:13 -0400 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:51998) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1g3OXF-0001a6-08 for submit@debbugs.gnu.org; Fri, 21 Sep 2018 12:44:05 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:46274) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g3OX9-0008QV-Ay for bug-gnu-emacs@gnu.org; Fri, 21 Sep 2018 12:44:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g3OX3-0001Jy-1B for bug-gnu-emacs@gnu.org; Fri, 21 Sep 2018 12:43:59 -0400 Original-Received: from aserp2120.oracle.com ([141.146.126.78]:39926) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1g3OX2-00010R-NS for bug-gnu-emacs@gnu.org; Fri, 21 Sep 2018 12:43:52 -0400 Original-Received: from pps.filterd (aserp2120.oracle.com [127.0.0.1]) by aserp2120.oracle.com (8.16.0.22/8.16.0.22) with SMTP id w8LGhaHe036005 for ; Fri, 21 Sep 2018 16:43:36 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : subject : content-type; s=corp-2018-07-02; bh=Z7/C/P+XL2zXR+sxmp8Wf7mF98+HiCsuNNS9eRmPTN8=; b=M8GipTyRLiBGeLNnoXIktmzUsjnpPrwMORm0Cd6zXX3AZ5Efvwzx8s9RdTkw6Fh4ldi1 tiY9v2EV+1LjEvcr/07scPORg1f2HDrS/UkHKbl3QM9M1inIu8c5yrhXYwLHzF0q/6yz z803b2u92F59rD260qa9dMPf7zrSDcie2EFPpY0+gUxU8fUP+HeV97zPhWiZQEJ/FpxH 3fLXfMy6yPPt/T9fXm67twWdPP0tFvsNJBxrQ7x35v0C6gLHuwbF8x6gP+AcnA9MzhqN Ereej3cXfuhiGqibhRTDwrgv6GIzd6C4o1tNsY+GnHpm+wzL098ivhJSYYJIh/twUcoB Jg== Original-Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by aserp2120.oracle.com with ESMTP id 2mmkm24ac2-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Fri, 21 Sep 2018 16:43:35 +0000 Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id w8LGhUqE008088 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Fri, 21 Sep 2018 16:43:30 GMT Original-Received: from abhmp0015.oracle.com (abhmp0015.oracle.com [141.146.116.21]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id w8LGhUlu023237 for ; Fri, 21 Sep 2018 16:43:30 GMT X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4735.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=9022 signatures=668707 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=1 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1807170000 definitions=main-1809210165 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [generic] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:150528 Archived-At: --__1537548210230306439abhmp0015.oracle.com Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable 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'. =20 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: =20 If the selected window is dedicated ('window-dedicated-p'), then use another window, regardless of argument FORCE-SAME-WINDOW. =20 Clear, simple. What does `p-t-b-s-w' do if the selected window is dedicated? Let's find out... =20 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. =20 For `p-t-b-s-w', for example, if you want to find out the particulars then you need to do something like this: =20 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?) =20 2. You go to the `p-t-b-s-w' source code, which you see is just this: =20 (pop-to-buffer buffer display-buffer--same-window-action norecord) =20 Great; very simple code. What does it mean? =20 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'. =20 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? =20 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. =20 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: =20 (display-buffer-same-window (inhibit-same-window)) =20 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'.) =20 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. =20 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))'. =20 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))'. =20 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. =20 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. =20 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. =20 Moral: Doc of `switch-to-buffer': simple and clear. Doc of `pop-to-buffer-same-window': not so much. =20 Doc of specific functions should be specific. The goal is not maximum factorization - sending all doc strings down the rabbit hole of `display-buffer'. =20 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. =20 --- =20 [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".] =20 [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.] =20 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=3Dx86_64-w64-mingw32 --without-compress-install 'CFLAGS=3D-O2 -static -g3'' =20 --__1537548210230306439abhmp0015.oracle.com Content-Type: text/html; charset=us-ascii Content-Transfer-Encoding: quoted-printable

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 `s= witch-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 (‘w= indow-dedicated-p’), then use

&nbs= p; another window, regardless of argument FORCE-SAME-WINDOW.

=

 

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

<= p class=3DMsoNormal>dedicated? Let's find out...

 

Unfortunately, ever sinc= e `display-buffer-alist' came along it seems

that the doc of specific functions pretty much just punt, forcing you<= o:p>

to follow a long and winding search thre= ad to learn their actual

behavior.<= /o:p>

 

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. Yo= u try `C-h f pop-to-buffer-same-window'. It says only "in some

window, preferably the same one".  (P= referably 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-acti= on norecord)

 

Great; very simple code.  What does it mean?=

 

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

variable?) to find ... essentially no new in= fo - an "action for

displaying in t= he same window".  A wasted detour, but the only thing<= /p>

that was specific in that invocation of `pop-to-buf= fer'.

 

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 ref= erence to `display-buffer'

and mention o= f its ACTION argument.  Hm, what's this?

 

5. You use `C-h f display-b= uffer' (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 sti= ll don't know

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

v display-buffer--same-window-action' again - and this time yo= u 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)'.&nb= sp; 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 g= o

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-wi= ndow))'.  You instantiate

the descr= iption to understand that `d-b-s-w' gets invoked with "two<= /p>

arguments: the buffer to display" and the alis= t

`((inhibit-same-window))'.<= /p>

 

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

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

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

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

 

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

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

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 fin= ally 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

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

for a window to be dedicated.

 

Could the doc f= or `p-t-b-s-w' have referred directly to `d-b-s-w"? Better<= /p>

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

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

 

Moral:

Doc of `switch-to-buffe= r': 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 com= plete 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 lin= ks - 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-wi= ndow'

entry", which is not clear/co= rrect.  It should say something like "has

an `inhibit-same-window' entry whose cdr is non-nil.  Ali= st entry

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

not what was intended by "a non-nil `i-s-w' entry".]<= /p>

 

[BTW2: Th= e `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.', vers= ion 10.0.16299

Configured using:

`configure --without-dbus --host=3Dx86_64-w64-= mingw32

--without-compress-install 'CFL= AGS=3D-O2 -static -g3''

 

--__1537548210230306439abhmp0015.oracle.com--