* bug#54170: 27.2; Docstring of `with-help-window' (and, in one respect, similar functions)
@ 2022-02-26 11:35 Florian v. Savigny via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-02-26 11:51 ` Eli Zaretskii
0 siblings, 1 reply; 3+ messages in thread
From: Florian v. Savigny via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2022-02-26 11:35 UTC (permalink / raw)
To: 54170
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 “send output to
BUFFER-OR-NAME”. Although I admit that astute readers will perhaps (or should)
wonder why it does not say “insert what BODY returns into
BUFFER-OR-NAME” (or “make BUFFER-OR-NAME the current buffer”, 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. “This construct is like
`with-temp-buffer-window', …” be somehow modified to hint to this
behaviour more bluntly, e.g. “Please see the similar construct
`with-temp-buffer-window', especially with regard to the output …”,
or, even more edifying, “See the similar constructs
`with-temp-buffer-window' and `with-output-to-temp-buffer', especially
with regard to the output …”
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
or deter people from persevering. (This is because the self-documenting behaviour
is still so cool that people tend to completely rely on it, I think.)
Best regards!
Florian v. Savigny
Siebenpfeiffer Str. 25
66482 Zweibrücken
0175 - 365 24 17
06332 - 898 52 52
^ permalink raw reply [flat|nested] 3+ messages in thread
* bug#54170: 27.2; Docstring of `with-help-window' (and, in one respect, similar functions)
2022-02-26 11:35 bug#54170: 27.2; Docstring of `with-help-window' (and, in one respect, similar functions) Florian v. Savigny via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2022-02-26 11:51 ` Eli Zaretskii
[not found] ` <1514624464.163789.1645969644967@office.mailbox.org>
0 siblings, 1 reply; 3+ messages in thread
From: Eli Zaretskii @ 2022-02-26 11:51 UTC (permalink / raw)
To: Florian v. Savigny; +Cc: 54170
> 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" <bug-gnu-emacs@gnu.org>
>
> (`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".
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2022-02-27 13:56 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-02-26 11:35 bug#54170: 27.2; Docstring of `with-help-window' (and, in one respect, similar functions) Florian v. Savigny via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-02-26 11:51 ` Eli Zaretskii
[not found] ` <1514624464.163789.1645969644967@office.mailbox.org>
2022-02-27 13:56 ` Eli Zaretskii
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).