From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: "Florian v. Savigny" via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#54170: 27.2; Docstring of `with-help-window' (and, in one respect, similar functions) Date: Sat, 26 Feb 2022 12:35:25 +0100 (CET) Message-ID: <311288967.117895.1645875325962@office.mailbox.org> Reply-To: "Florian v. Savigny" Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="1507"; mail-complaints-to="usenet@ciao.gmane.io" To: 54170@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Feb 26 12:36:19 2022 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nNvN4-0000CX-US for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 26 Feb 2022 12:36:19 +0100 Original-Received: from localhost ([::1]:34820 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nNvN3-0005u5-SL for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 26 Feb 2022 06:36:17 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:59546) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nNvMq-0005r1-0V for bug-gnu-emacs@gnu.org; Sat, 26 Feb 2022 06:36:04 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:60469) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nNvMo-00067t-SF for bug-gnu-emacs@gnu.org; Sat, 26 Feb 2022 06:36:03 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1nNvMo-0000qs-Nt for bug-gnu-emacs@gnu.org; Sat, 26 Feb 2022 06:36:02 -0500 X-Loop: help-debbugs@gnu.org 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-Debbugs-Original-To: "bug-gnu-emacs@gnu.org" Original-Received: via spool by submit@debbugs.gnu.org id=B.16458753423240 (code B ref -1); Sat, 26 Feb 2022 11:36:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 26 Feb 2022 11:35:42 +0000 Original-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 Original-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 Original-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 Original-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 Original-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) 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== 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-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list 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-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:227671 Archived-At: 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