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

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]

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

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

[Eli Zaretskii]

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

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

[Eli Zaretskii]

[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" <f.savigny@mailbox.org>
> 
> 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.