Re: Improved help from minibuffer prompts

[Richard Stallman <rms@gnu.org>]

    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.

    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.

    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.