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.