--- Begin Message ---
|
Subject: |
27.2; Docstring of `with-help-window' (and, in one respect, similar functions) |
|
Date: |
Sat, 26 Feb 2022 12:35:25 +0100 (CET) |
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
--- End Message ---
--- Begin Message ---
|
Subject: |
Re: bug#54170: 27.2; Docstring of `with-help-window' (and, in one respect, similar functions) |
|
Date: |
Sun, 27 Feb 2022 15:56:21 +0200 |
[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.
--- End Message ---