From unknown Sun Jun 22 04:25:20 2025 X-Loop: help-debbugs@gnu.org Subject: bug#54170: 27.2; Docstring of `with-help-window' (and, in one respect, similar functions) Resent-From: "Florian v. Savigny" Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 26 Feb 2022 11:36:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 54170 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 54170@debbugs.gnu.org X-Debbugs-Original-To: "bug-gnu-emacs@gnu.org" Received: via spool by submit@debbugs.gnu.org id=B.16458753423240 (code B ref -1); Sat, 26 Feb 2022 11:36:02 +0000 Received: (at submit) by debbugs.gnu.org; 26 Feb 2022 11:35:42 +0000 Received: from localhost ([127.0.0.1]:54366 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nNvMU-0000qC-6x for submit@debbugs.gnu.org; Sat, 26 Feb 2022 06:35:42 -0500 Received: from lists.gnu.org ([209.51.188.17]:52970) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nNvMS-0000q4-B5 for submit@debbugs.gnu.org; Sat, 26 Feb 2022 06:35:40 -0500 Received: from eggs.gnu.org ([209.51.188.92]:59468) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nNvMR-0005Vz-QH for bug-gnu-emacs@gnu.org; Sat, 26 Feb 2022 06:35:39 -0500 Received: from mout-p-202.mailbox.org ([80.241.56.172]:51694) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_CHACHA20_POLY1305:256) (Exim 4.90_1) (envelope-from ) id 1nNvMP-0005od-64 for bug-gnu-emacs@gnu.org; Sat, 26 Feb 2022 06:35:39 -0500 Received: from smtp2.mailbox.org (smtp2.mailbox.org [80.241.60.241]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-384) server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-202.mailbox.org (Postfix) with ESMTPS id 4K5Phf2FWTz9sGV for ; Sat, 26 Feb 2022 12:35:30 +0100 (CET) Date: Sat, 26 Feb 2022 12:35:25 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=mailbox.org; s=mail20150812; t=1645875328; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=d+WTN6szz90kiS6uInagsB1hcl7jBVsARexhtmbI0Lc=; b=qSFhfLHPNOFxfM/AalDcTvOpzhUopt/zopyh2TMI+Sn26MOwqhBi3TJMQZ8ECJ7tgvjPiF O91Ovs3J3HaBqiczE/RWU/zvNjSnaLbpNXixukDM7/90DIeSnD+m8WBcJvCn0h6WhX0bhH v9sGzZv4Q9ZI56kgJRs/bPDH9npbBTm/TB7aFNeTuHjv4E60J5BEvNThp1tdEbwHLOaP1Z ecb8iGsAaf85GJMITlMrOUwGjlEwPu116RNHbqEvddI7NNqmqCFT3YlfgSt2v93WH9DMwL vl3GcV7df+oPnlgabv0VUS4OEPifex6dUOuKwM5gm5auWYP/6Q1XKIjy06EckA== From: "Florian v. Savigny" Message-ID: <311288967.117895.1645875325962@office.mailbox.org> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Priority: 3 Importance: Normal Received-SPF: pass client-ip=80.241.56.172; envelope-from=f.savigny@mailbox.org; helo=mout-p-202.mailbox.org X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: -1.3 (-) 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: -2.3 (--) Dear Emacs maintainers, (`with-help-window' BUFFER-OR-NAME &rest BODY) inserts the /standard output/ of whatever BODY does into BUFFER-OR-NAME, not whatever string BODY might return, nor does `insert' insert into BUFFER-OR-NAME. This is the same behaviour as `with-temp-buffer-window', which is referred to in `with-help-window', and is thoroughly spelled out in the docstring of that latter function, and even more so in the docstring of `with-output-to-temp-buffer', which is in turn referred to from `with-temp-buffer-window' ... In the docstring of `with-help-window' itself, however, there is only a faint hint to this behaviour, namely =E2=80=9Csend output to BUFFER-OR-NAME=E2=80=9D. Although I admit that astute readers will perhaps = (or should) wonder why it does not say =E2=80=9Cinsert what BODY returns into BUFFER-OR-NAME=E2=80=9D (or =E2=80=9Cmake BUFFER-OR-NAME the current buffer= =E2=80=9D, or what other behaviours might be expected), less astute readers risk running into what looks like strange behaviour to them (namely, an empty help buffer). I would find it very helpful, and would therefore like to suggest, that the second line of the docstring, i.e. =E2=80=9CThis construct is like `with-temp-buffer-window', =E2=80=A6=E2=80=9D be somehow modified to hint t= o this behaviour more bluntly, e.g. =E2=80=9CPlease see the similar construct `with-temp-buffer-window', especially with regard to the output =E2=80=A6= =E2=80=9D, or, even more edifying, =E2=80=9CSee the similar constructs `with-temp-buffer-window' and `with-output-to-temp-buffer', especially with regard to the output =E2=80=A6=E2=80=9D Of course, this is by no means a "bug" in the documentation at all, rather a stumbling block for the unsuspecting, which, I fear, can discourage=20 or deter people from persevering. (This is because the self-documenting beh= aviour is still so cool that people tend to completely rely on it, I think.) Best regards! Florian v. Savigny Siebenpfeiffer Str. 25 66482 Zweibr=C3=BCcken 0175 - 365 24 17 06332 - 898 52 52 From unknown Sun Jun 22 04:25:20 2025 X-Loop: help-debbugs@gnu.org Subject: bug#54170: 27.2; Docstring of `with-help-window' (and, in one respect, similar functions) Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 26 Feb 2022 11:52:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 54170 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "Florian v. Savigny" Cc: 54170@debbugs.gnu.org Received: via spool by 54170-submit@debbugs.gnu.org id=B54170.16458762975022 (code B ref 54170); Sat, 26 Feb 2022 11:52:01 +0000 Received: (at 54170) by debbugs.gnu.org; 26 Feb 2022 11:51:37 +0000 Received: from localhost ([127.0.0.1]:54380 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nNvbt-0001Iw-GJ for submit@debbugs.gnu.org; Sat, 26 Feb 2022 06:51:37 -0500 Received: from eggs.gnu.org ([209.51.188.92]:56040) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nNvbr-0001Id-7L for 54170@debbugs.gnu.org; Sat, 26 Feb 2022 06:51:35 -0500 Received: from [2001:470:142:3::e] (port=52030 helo=fencepost.gnu.org) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nNvbj-0001UL-Sp; Sat, 26 Feb 2022 06:51:28 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=FTQCOIllnfumvMFXUsjXrBtSzlYHzKoA1uYhTzFgbrY=; b=SmngIXTJtJDf7joAZASQ ZOEhV9fUgEmHiYQSxE5TP0MlA0k06Deu+rBjr/Tu5JSZUERjdpnVt0nuLiweveyolkgZyHNRqa0ow wU980OmpNcuArQvqSH5vqcwjuz4IOsR74gFiWR7/jsLM+oFAQeJ+QolL0MpTDJx3X1LsKlZyLmv+D 6UGMFI9vayrCLhF5NM2RGPElKgwgRQb+54cm2IL4EPqLoKbOYp0rc5tLMgGNpq8kuqRIyGwq7Ycfs MQmOQDgJYgX5kelBX+m+JW2wRGyK29Vh3MoqCEZdliY/0Uj1ZMBnL22SEayviMwP536VA4yZvlf8y uilwAKF+L3/ZsA==; Received: from [87.69.77.57] (port=4368 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nNvbj-0005MN-8v; Sat, 26 Feb 2022 06:51:27 -0500 Date: Sat, 26 Feb 2022 13:51:11 +0200 Message-Id: <83ilt1q21c.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <311288967.117895.1645875325962@office.mailbox.org> (bug-gnu-emacs@gnu.org) References: <311288967.117895.1645875325962@office.mailbox.org> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) 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: -3.3 (---) > Date: Sat, 26 Feb 2022 12:35:25 +0100 (CET) > From: "Florian v. Savigny" via "Bug reports for GNU Emacs, > the Swiss army knife of text editors" > > (`with-help-window' BUFFER-OR-NAME &rest BODY) inserts the /standard > output/ of whatever BODY does into BUFFER-OR-NAME, not whatever string > BODY might return, nor does `insert' insert into BUFFER-OR-NAME. > This is the same behaviour as `with-temp-buffer-window', which is > referred to in `with-help-window', and is thoroughly spelled out in > the docstring of that latter function, and even more so in the > docstring of `with-output-to-temp-buffer', which is in turn referred > to from `with-temp-buffer-window' ... > > In the docstring of `with-help-window' itself, however, there is only > a faint hint to this behaviour, namely “send output to > BUFFER-OR-NAME”. That's why the reference to with-temp-buffer-window is there: to avoid repetition of a non-trivial description, but still let user who want the details to get to them easily and conveniently. I'm not sure I understand why you think this is not enough. We do that many times in Emacs, this macro is not special in that regard. We could add "(which see)" after the reference to with-temp-buffer-window, if you think that will make it more obvious that the reference is there to be read, not just as "see also". From debbugs-submit-bounces@debbugs.gnu.org Sat Feb 26 09:30:01 2022 Received: (at control) by debbugs.gnu.org; 26 Feb 2022 14:30:01 +0000 Received: from localhost ([127.0.0.1]:54609 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nNy5B-0007wN-2t for submit@debbugs.gnu.org; Sat, 26 Feb 2022 09:30:01 -0500 Received: from quimby.gnus.org ([95.216.78.240]:41778) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nNy59-0007wA-TG for control@debbugs.gnu.org; Sat, 26 Feb 2022 09:30:00 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Subject:From:To:Message-Id:Date:Sender:Reply-To:Cc: MIME-Version:Content-Type:Content-Transfer-Encoding:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:In-Reply-To:References:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=P90vEE0dvAdF4cQJF6CSVHt0Is1haypG5eHrjNOXd6A=; b=l0VpUtEFlwU7d30slRuY70moOr 7QLfd6l1bxFU+j1TYIJ227FbvuVdWQN79jGAG/17uDL5ezGfDvRKGybn6ixRoh+eES6RKNZ3Zm/2Y D8w6syCKE8x62vnJ36TC+QSB3li5VJgRwf0BTQsKZPE5P2GM/kePvN+Gl5qFIt3l8ju8=; Received: from [84.212.220.105] (helo=giant) by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nNy51-00062h-2Q for control@debbugs.gnu.org; Sat, 26 Feb 2022 15:29:53 +0100 Date: Sat, 26 Feb 2022 15:29:48 +0100 Message-Id: <87k0dhvgyr.fsf@gnus.org> To: control@debbugs.gnu.org From: Lars Ingebrigtsen Subject: control message for bug #54170 X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: tags 54170 + moreinfo quit Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: control 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: -3.3 (---) tags 54170 + moreinfo quit From unknown Sun Jun 22 04:25:20 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: "Florian v. Savigny" Subject: bug#54170: closed (Re: bug#54170: 27.2; Docstring of `with-help-window' (and, in one respect, similar functions)) Message-ID: References: <83fso4o1kq.fsf@gnu.org> <311288967.117895.1645875325962@office.mailbox.org> X-Gnu-PR-Message: they-closed 54170 X-Gnu-PR-Package: emacs X-Gnu-PR-Keywords: moreinfo Reply-To: 54170@debbugs.gnu.org Date: Sun, 27 Feb 2022 13:57:01 +0000 Content-Type: multipart/mixed; boundary="----------=_1645970221-19090-1" This is a multi-part message in MIME format... ------------=_1645970221-19090-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Your bug report #54170: 27.2; Docstring of `with-help-window' (and, in one respect, similar= functions) 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 54170@debbugs.gnu.org. --=20 54170: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D54170 GNU Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1645970221-19090-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 54170-done) by debbugs.gnu.org; 27 Feb 2022 13:56:42 +0000 Received: from localhost ([127.0.0.1]:57195 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nOK2U-0004xM-8J for submit@debbugs.gnu.org; Sun, 27 Feb 2022 08:56:42 -0500 Received: from eggs.gnu.org ([209.51.188.92]:45230) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nOK2S-0004wy-Fb for 54170-done@debbugs.gnu.org; Sun, 27 Feb 2022 08:56:41 -0500 Received: from [2001:470:142:3::e] (port=50274 helo=fencepost.gnu.org) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nOK2M-0003Dl-RH; Sun, 27 Feb 2022 08:56:34 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=6cQ5TpQP46P/LasxInhVUSDfGS3vymuY8Hql4RuL0Ow=; b=KIq8gARxgZtjlXddCp1V IzmXEhaCMH4hPVNSqy7OhRf/P2VaHf9kREgBQL/ym7pkRY/M7ZKBxjHsuZjiG+Z9GbnrajI6OSBra jR7BBVGhDdIB71JCOrMfHzJITiOVQWJzRGEmsZjqhYFhjD7ihjH6AjNOdAE1QxkFIJJtVP+wuB6CS 8BO25bKPWYkYBEx/DRH75aqy/ZWEsQvF1DWBQhkR/gGdrC0RG+VC86Lj+DZKTtQJKy945zisSeMzJ yXzDFCeb5R7RXmzU1OGnU47cjGzUbMnYyF7vf0Mz6FrYIfYuCb0R3dupoQI2SqW8lh1f3cuTjS3nV jCvkofqk0ba2Hw==; Received: from [87.69.77.57] (port=1674 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nOK2M-0007up-7Z; Sun, 27 Feb 2022 08:56:34 -0500 Date: Sun, 27 Feb 2022 15:56:21 +0200 Message-Id: <83fso4o1kq.fsf@gnu.org> From: Eli Zaretskii To: "Florian v. Savigny" In-Reply-To: <1514624464.163789.1645969644967@office.mailbox.org> (f.savigny@mailbox.org) Subject: Re: bug#54170: 27.2; Docstring of `with-help-window' (and, in one respect, similar functions) References: <311288967.117895.1645875325962@office.mailbox.org> <83ilt1q21c.fsf@gnu.org> <1514624464.163789.1645969644967@office.mailbox.org> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 54170-done Cc: 54170-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: -3.3 (---) [Please in the future use Reply All to keep the bug tracker on the CC.] > Date: Sun, 27 Feb 2022 14:47:24 +0100 (CET) > From: "Florian v. Savigny" > > Dear Eli, > > thank you for your swift response! In short: Yes, I think adding “which see” > would be a very good idea -- and one I actually didn’t think of -- although I > would like to suggest putting it between commas, not parentheses, to hint that > having understood `with-temp-buffer-window' is essential to using > `with-help-window' correctly -- not just, say, interesting. > > Basically, anything which nudges the reader more to actually read the > documentation of `with-temp-buffer-window', would, from my perspective, be a > very good idea, but “which see” would be particularly good because it is a > familiar, standard hint in Emacs docstrings (and marks reading > `with-temp-buffer-window' as just as important as reading `help-window-setup'). > I totally agree that repetition of nontrivial explanations must be avoided; I > would even think that if one principle is used in many places, pointing users to > ONE place where it is explained is not only the obvious way to avoid such > repetition, but also has the desirable side-effect of making the programmer > aware of the general principle as such. > > If you don't mind, I will try to explain a bit why I think such details actually > matter: Of course, whether documentation is helpful is totally, totally > subjective because that depends mostly on the reader's preexisting knowledge. > > What I am suggesting here is, then, basically to accomodate the naive Elisp > programmers a bit more, and this is of course informed by my own journey through > the waters of Elisp. But I like to believe that I'm not doing this purely out of > egocentricism, but to shield fellow dabblers from some unneccessary frustration > and failed, abandoned attempts, and thus make Emacs more attractive to use and > explore by making its strengths more easily accessible. > > In a 1981 paper I just read, Richard Stallman made a very nice point: > "When large numbers of nontechnical workers are using a programmable editor, > they will he tempted constantly to begin programming in the course of > their day-to-day lives.", and he went on to suggest that this should help > improve computer literacy. I can definitely attest to that; Emacs is > very seductive in that respect! > > There's just one catch with that, one which Stallman -- perhaps not consciously > -- even hinted at by saying “in their day-to-day lives”: What tempts the > nontechnical user (in contrast to the professional programmer) to “begin > programming” (without realising it too much) is usually the desire to add > something to Emacs it can't yet do, and then use it right away. What might tempt > you to try `with-help-window', for example, might be the wish to be able to > display some quick information (gleaned from God-knows-where) in the same way > you usually read help on functions and the like with C-h f and the like. > > Very often (at least in my experience) you will want to program your new > command, get it done in ten minutes, and then go on with your work and > immediately use your new feature. (This is one thing which makes Emacs so > intriguing: The perspectives of the user and the programmer are as close as can > be.) This usually means you are very likely to completely rely on the docstrings > in such a situation, simply because this kind of help is most directly > available, and also means that if you get stuck, you’re quite likely to abandon > and even forget your attempt of making Emacs an even better place (if only for > yourself) and settle with what you already had. > > And that’s why I think cross-references in docstrings are not only one of their > very essential features, but that when one writes a docstring, attention to > nudging naive programmers to actually follow them is definitely a good idea, in > a spirit of, “We do not want to let you run into the trap of thinking that it’s > as simple as you think.” “which see” is a clear nudge, and definitely doesn’t > spoil the dabbler too much. > > Sorry for the lengthiness, but it's in fact a general thought I often have. > In short, I feel adding ", which see" after `with-temp-buffer-window' should > be perfect. Thanks, I added that on the emacs-28 branch, and I'm therefore closing this bug report. ------------=_1645970221-19090-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by debbugs.gnu.org; 26 Feb 2022 11:35:42 +0000 Received: from localhost ([127.0.0.1]:54366 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nNvMU-0000qC-6x for submit@debbugs.gnu.org; Sat, 26 Feb 2022 06:35:42 -0500 Received: from lists.gnu.org ([209.51.188.17]:52970) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nNvMS-0000q4-B5 for submit@debbugs.gnu.org; Sat, 26 Feb 2022 06:35:40 -0500 Received: from eggs.gnu.org ([209.51.188.92]:59468) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nNvMR-0005Vz-QH for bug-gnu-emacs@gnu.org; Sat, 26 Feb 2022 06:35:39 -0500 Received: from mout-p-202.mailbox.org ([80.241.56.172]:51694) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_CHACHA20_POLY1305:256) (Exim 4.90_1) (envelope-from ) id 1nNvMP-0005od-64 for bug-gnu-emacs@gnu.org; Sat, 26 Feb 2022 06:35:39 -0500 Received: from smtp2.mailbox.org (smtp2.mailbox.org [80.241.60.241]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-384) server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-202.mailbox.org (Postfix) with ESMTPS id 4K5Phf2FWTz9sGV for ; Sat, 26 Feb 2022 12:35:30 +0100 (CET) Date: Sat, 26 Feb 2022 12:35:25 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=mailbox.org; s=mail20150812; t=1645875328; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=d+WTN6szz90kiS6uInagsB1hcl7jBVsARexhtmbI0Lc=; b=qSFhfLHPNOFxfM/AalDcTvOpzhUopt/zopyh2TMI+Sn26MOwqhBi3TJMQZ8ECJ7tgvjPiF O91Ovs3J3HaBqiczE/RWU/zvNjSnaLbpNXixukDM7/90DIeSnD+m8WBcJvCn0h6WhX0bhH v9sGzZv4Q9ZI56kgJRs/bPDH9npbBTm/TB7aFNeTuHjv4E60J5BEvNThp1tdEbwHLOaP1Z ecb8iGsAaf85GJMITlMrOUwGjlEwPu116RNHbqEvddI7NNqmqCFT3YlfgSt2v93WH9DMwL vl3GcV7df+oPnlgabv0VUS4OEPifex6dUOuKwM5gm5auWYP/6Q1XKIjy06EckA== From: "Florian v. Savigny" To: "bug-gnu-emacs@gnu.org" Message-ID: <311288967.117895.1645875325962@office.mailbox.org> Subject: 27.2; Docstring of `with-help-window' (and, in one respect, similar functions) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Priority: 3 Importance: Normal Received-SPF: pass client-ip=80.241.56.172; envelope-from=f.savigny@mailbox.org; helo=mout-p-202.mailbox.org X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: -1.3 (-) 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: -2.3 (--) Dear Emacs maintainers, (`with-help-window' BUFFER-OR-NAME &rest BODY) inserts the /standard output/ of whatever BODY does into BUFFER-OR-NAME, not whatever string BODY might return, nor does `insert' insert into BUFFER-OR-NAME. This is the same behaviour as `with-temp-buffer-window', which is referred to in `with-help-window', and is thoroughly spelled out in the docstring of that latter function, and even more so in the docstring of `with-output-to-temp-buffer', which is in turn referred to from `with-temp-buffer-window' ... In the docstring of `with-help-window' itself, however, there is only a faint hint to this behaviour, namely =E2=80=9Csend output to BUFFER-OR-NAME=E2=80=9D. Although I admit that astute readers will perhaps = (or should) wonder why it does not say =E2=80=9Cinsert what BODY returns into BUFFER-OR-NAME=E2=80=9D (or =E2=80=9Cmake BUFFER-OR-NAME the current buffer= =E2=80=9D, or what other behaviours might be expected), less astute readers risk running into what looks like strange behaviour to them (namely, an empty help buffer). I would find it very helpful, and would therefore like to suggest, that the second line of the docstring, i.e. =E2=80=9CThis construct is like `with-temp-buffer-window', =E2=80=A6=E2=80=9D be somehow modified to hint t= o this behaviour more bluntly, e.g. =E2=80=9CPlease see the similar construct `with-temp-buffer-window', especially with regard to the output =E2=80=A6= =E2=80=9D, or, even more edifying, =E2=80=9CSee the similar constructs `with-temp-buffer-window' and `with-output-to-temp-buffer', especially with regard to the output =E2=80=A6=E2=80=9D Of course, this is by no means a "bug" in the documentation at all, rather a stumbling block for the unsuspecting, which, I fear, can discourage=20 or deter people from persevering. (This is because the self-documenting beh= aviour is still so cool that people tend to completely rely on it, I think.) Best regards! Florian v. Savigny Siebenpfeiffer Str. 25 66482 Zweibr=C3=BCcken 0175 - 365 24 17 06332 - 898 52 52 ------------=_1645970221-19090-1--