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

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Florian v. Savigny" <f.savigny <at> mailbox.org>
Cc: 54170 <at> debbugs.gnu.org
Subject: bug#54170: 27.2; Docstring of `with-help-window' (and, in one respect, similar functions)
Date: Sat, 26 Feb 2022 13:51:11 +0200

> 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 <at> 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".

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.