RE: Improved help from minibuffer prompts

[Drew Adams]

Nothing wrong with a new convention to delimit help for each arg.

I've thought for a while that relying on just an UPPERCASE convention for
documenting arguments and their structural parts could be improved upon
somehow. (Did someone say XML doc strings? Elisp schemas? JavaDoc keywords?
:)) A more clearly defined doc-string convention (structure, order, style)
might be a start.

However:

1) As others have pointed out, functions looking for this delimiter stuff
couldn't do anything with older doc strings that lacked it. And updating all
the doc strings of the predefined functions would be OK, but it wouldn't
affect outside, contributed packages.

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.

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? Yes,
the user would have to start the command over after reading the doc, but is
that such a bad thing?

5) Often, a prefix arg (present/absent; positive, negative, zero; other
specific values) is very important to a command's functioning. It would not
be explained by the proposed arg help; 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.

6) I'm not convinced of the utility of extra help for prompted parameters at
command call. I tend to think: a) the *prompt* itself should be able to do
the job, and b) if it cannot, the user should consult the doc string with
`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. Delimiting arg help might be a good idea for other possible
uses (apropos? JavaDoc-style doc?), but I'm not sure that dynamic help on
args is really needed/helpful. But then again, I haven't tried it...

 - Drew

-----Original Message-----
From: address@hidden
[mailto:address@hidden Behalf Of
Stefan Reichor
Sent: Monday, April 19, 2004 12:52 AM
To: address@hidden
Subject: Re: Improved help from minibuffer prompts
...
>     The doc string is supposed to describe the arguments, so it is more
>     useful than no help.
>
> That is true--but its description of the arguments is often not
> very helpful for a situation like this.
>
> Here is a new idea.  We can develop a convention for delimiting, in
> the doc string, the help about each argument.  Then the help facility
> for entering an argument could look thru the doc string for the part
> that refers to the current argument.

That is a nice idea. Here are my thoughts:
* Often you are prompted for an argument in the minibuffer.
  - A specific help for this argument would be sometimes very nice,
    because the prompt is to short to provide all the information
  - Often you want to about the function that is actually in progress
    You want to get the "big picture". In this case the whole
    documentation would be nicer.

* The convention for delimiting the doc strings would require a
  rewrite of many docstrings.
  Many source code documentation tools solve it by putting an extra
  \param section for every parameter.

...
Consider the find-dired example. When asked for dir or args
I would like to get the whole docstring, because it covers the things
I need to know.

I am not sure about the benefit of stripping the information down for
every argument.