From unknown Mon Aug 18 14:24:06 2025 X-Loop: help-debbugs@gnu.org Subject: bug#32798: 26; doc string of `pop-to-buffer-same-window' and similar 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: To: 32798@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.153754826820126 (code B ref -1); Fri, 21 Sep 2018 16:45:01 +0000 Received: (at submit) by debbugs.gnu.org; 21 Sep 2018 16:44:28 +0000 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 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 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 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50,HTML_MESSAGE, T_DKIM_INVALID autolearn=disabled version=3.3.2 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 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 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 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 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== 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 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 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 MIME-Version: 1.0 Message-ID: Date: Fri, 21 Sep 2018 09:43:29 -0700 (PDT) From: Drew Adams X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4735.0 (x86)] Content-Type: multipart/alternative; boundary="__1537548210230306439abhmp0015.oracle.com" 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-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.0 (----) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) --__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-- From unknown Mon Aug 18 14:24:06 2025 X-Loop: help-debbugs@gnu.org Subject: bug#32798: 26; doc string of `pop-to-buffer-same-window' and similar Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 22 Sep 2018 10:25:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 32798 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Drew Adams Cc: 32798@debbugs.gnu.org Received: via spool by 32798-submit@debbugs.gnu.org id=B32798.15376118565049 (code B ref 32798); Sat, 22 Sep 2018 10:25:01 +0000 Received: (at 32798) by debbugs.gnu.org; 22 Sep 2018 10:24:16 +0000 Received: from localhost ([127.0.0.1]:48717 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1g3f5E-0001JN-LZ for submit@debbugs.gnu.org; Sat, 22 Sep 2018 06:24:16 -0400 Received: from eggs.gnu.org ([208.118.235.92]:59697) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1g3f5D-0001JB-4u for 32798@debbugs.gnu.org; Sat, 22 Sep 2018 06:24:15 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g3f54-0003l0-Jx for 32798@debbugs.gnu.org; Sat, 22 Sep 2018 06:24:09 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:53181) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g3f54-0003kn-FT; Sat, 22 Sep 2018 06:24:06 -0400 Received: from [176.228.60.248] (port=3183 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1g3f53-0003RH-I5; Sat, 22 Sep 2018 06:24:06 -0400 Date: Sat, 22 Sep 2018 13:23:54 +0300 Message-Id: <83h8ihde4l.fsf@gnu.org> From: Eli Zaretskii In-reply-to: (message from Drew Adams on Fri, 21 Sep 2018 09:43:29 -0700 (PDT)) References: X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -6.0 (------) > Date: Fri, 21 Sep 2018 09:43:29 -0700 (PDT) > From: Drew Adams > > 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. From unknown Mon Aug 18 14:24:06 2025 MIME-Version: 1.0 X-Mailer: MIME-tools 5.505 (Entity 5.505) X-Loop: help-debbugs@gnu.org From: help-debbugs@gnu.org (GNU bug Tracking System) To: Drew Adams Subject: bug#32798: closed (Re: bug#32798: 26; doc string of `pop-to-buffer-same-window' and similar) Message-ID: References: <838t3raq5j.fsf@gnu.org> X-Gnu-PR-Message: they-closed 32798 X-Gnu-PR-Package: emacs Reply-To: 32798@debbugs.gnu.org Date: Mon, 24 Sep 2018 15:10:02 +0000 Content-Type: multipart/mixed; boundary="----------=_1537801802-30691-1" This is a multi-part message in MIME format... ------------=_1537801802-30691-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Your bug report #32798: 26; doc string of `pop-to-buffer-same-window' and similar 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 32798@debbugs.gnu.org. --=20 32798: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D32798 GNU Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1537801802-30691-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 32798-done) by debbugs.gnu.org; 24 Sep 2018 15:09:32 +0000 Received: from localhost ([127.0.0.1]:52228 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1g4SUO-0007yB-Mh for submit@debbugs.gnu.org; Mon, 24 Sep 2018 11:09:32 -0400 Received: from eggs.gnu.org ([208.118.235.92]:33514) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1g4SUN-0007xw-0u for 32798-done@debbugs.gnu.org; Mon, 24 Sep 2018 11:09:31 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g4SUD-0004nr-PF for 32798-done@debbugs.gnu.org; Mon, 24 Sep 2018 11:09:25 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:36365) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g4SUB-0004nF-Ow; Mon, 24 Sep 2018 11:09:21 -0400 Received: from [176.228.60.248] (port=1997 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1g4SUA-0002lB-QM; Mon, 24 Sep 2018 11:09:19 -0400 Date: Mon, 24 Sep 2018 18:09:12 +0300 Message-Id: <838t3raq5j.fsf@gnu.org> From: Eli Zaretskii To: drew.adams@oracle.com In-reply-to: <83h8ihde4l.fsf@gnu.org> (message from Eli Zaretskii on Sat, 22 Sep 2018 13:23:54 +0300) Subject: Re: bug#32798: 26; doc string of `pop-to-buffer-same-window' and similar References: <83h8ihde4l.fsf@gnu.org> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-Debbugs-Envelope-To: 32798-done Cc: 32798-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -6.0 (------) > Date: Sat, 22 Sep 2018 13:23:54 +0300 > From: Eli Zaretskii > Cc: 32798@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. ------------=_1537801802-30691-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by debbugs.gnu.org; 21 Sep 2018 16:44:28 +0000 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 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 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 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50,HTML_MESSAGE, T_DKIM_INVALID autolearn=disabled version=3.3.2 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 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 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 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 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== 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 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 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 MIME-Version: 1.0 Message-ID: Date: Fri, 21 Sep 2018 09:43:29 -0700 (PDT) From: Drew Adams To: bug-gnu-emacs@gnu.org Subject: 26; doc string of `pop-to-buffer-same-window' and similar X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4735.0 (x86)] Content-Type: multipart/alternative; boundary="__1537548210230306439abhmp0015.oracle.com" 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-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.0 (----) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) --__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-- ------------=_1537801802-30691-1--