RE: Improved help from minibuffer prompts

["Drew Adams" <drew.adams@oracle.com>]

below

-----Original Message-----
From: Richard Stallman [mailto:rms@gnu.org]
Sent: Tuesday, April 20, 2004 1:48 PM
To: Drew Adams
Cc: emacs-devel@gnu.org
Subject: Re: Improved help from minibuffer prompts

    2) More importantly, we should make an effort (progressively) to create
doc
    strings that describe arguments first in a *user-centric* fashion.
Nerdier
    nitty-gritty explanations can be included in a doc string (if really
    necessary - rare IMO), but they should come after a high-level,
    user-understandable explanation. This effort would go a long way to
solving
    the perceived problem.

    3) *Improve the prompts* for input arguments. A good prompt goes a long
way
    to helping users understand. I realize that some input args are so
complex
    that a user may need to understand more than can be put in a prompt, but
    this can sometimes be an indicator that the command UI is in fact
    ill-defined.

> I agree completely.  Anyone who has signed papers, please rewrite
> doc strings in these ways whenever you feel you need a break
> from fixing bugs.

    4) Keeping in mind #2 & #3, I agree with some others that it can be
useful
    for a user to get to the whole doc string. Wouldn't it be sufficient to
    remind a user about `C-h f' at the point of the argument "help" call?

> That would be very inconvenient in practical use.  We're considering
> other suggestions that are much easier to use.

I don't see them as
 . "much easier to use" or
 . very useful.

We're considering the benefits of a help-key when prompted for an input arg
to a command; the key would call up some help on the arg. Bringing up the
entire doc string was mentioned as one possibility.

If the doc string is not well written, then the solution is to rewrite it.

If the doc string is well written, I don't see much utility in the
arg-prompt help. If it just brings up the doc string, I suppose that's OK,
but in that case it would be sufficient for it to serve as a reminder (esp.
to newbies) that the args are described via `C-h f'.

My point here was that the key sequence that calls up help when inputting an
arg could just (generically) echo "Use `C-h f <command-name-here>' for more
information".

If you need to read the doc string to continue inputting an arg, I think you
can exit the command, read it, then execute the command again. How hard is
it to re-execute a command?

I don't see much utility in *temporarily* leaving the arg-input process to
consult the help, then continuing where you left off, inputting. That kind
of thing is OK for query-replace, but it's not very useful in this context,
IMO.

As I said, however, I have not tried the proposed help, so this is just a
prejudice. I try to imagine the new feature, and I don't see it helping.
Those who have used it apparently find it helpful.

    5) Often, a prefix arg (present/absent; positive, negative, zero; other
    specific values) is very important to a command's functioning.

> That is true.  However,...

    It would not be explained by the proposed arg help;

> Maybe so, but I don't follow your point.  We're talking about offering
> help for how to enter a minibuffer argument.  Could you explain
> precisely how the prefix arg relates to this?

    users would have to consult the doc
    string to get that info anyway. If they came to rely on the proposed arg
    help, thinking they were getting the whole story that way, they would
miss a
    lot.

> So what?  We're talking about getting help for entering a minibuffer
> argument.

My point here is that if the input-arg help does *not* include the whole doc
string, then it only goes so far toward helping you use & learn about the
command. That's OK as far as it goes, but you might get the impression that
you've learned it all, and miss out on some important functionality.

If, on the other hand, the prompt help just says `Use `C-h f' for more
information' (or if it showed you the entire doc string directly), then you
might learn more.

In sum:

1. If the arg-input help does *not* give you the whole doc string (directly
or indirectly), then:

 . It's not worth it.
 . It might lead you to miss out on important info in the doc string.

2. If the arg-input help gives you the whole doc string *directly*, then:

 . It's not worth it. A reminder about `C-h f' is as good. In fact, it's
better that folks get in the habit of using `C-h f'.

    7) In sum, I like the *solution* (delimit parts of doc strings, or
otherwise
    structure them), but I am not sure of the importance of the *problem* it
    tries to solve.

> Someone saw room for improvement, but I don't want to say I am certain
> it is important.  Perhaps things are good enough as they are.

IMO, they are. #2 and #3 at the top are key: good doc strings, good prompts
(and commands that don't require understanding complex input args).


There is still the question of the utility of (somehow) structuring doc
strings - that is, making them doc structures, not just strings. Any juice
there?


 - Drew