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
[Message part 1 (text/plain, inline)]
Your bug report
#54170: 27.2; Docstring of `with-help-window' (and, in one respect, similar functions)
which was filed against the emacs package, has been closed.
The explanation is attached below, along with your original report.
If you require more details, please reply to 54170 <at> debbugs.gnu.org.
--
54170: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=54170
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems
[Message part 2 (message/rfc822, inline)]
[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 <at> 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.
[Message part 3 (message/rfc822, inline)]
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
This bug report was last modified 3 years and 140 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.