bug#54170: 27.2; Docstring of `with-help-window' (and, in one respect, similar functions)

[Florian v. Savigny]

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