Re: Improved help from minibuffer prompts

[Stefan Reichör]

Hi Richard!

>     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.

* Look at the following (randomly) choosen functions and their documentations:

--------------------------------------------------------------------------------
grep-find is an interactive autoloaded Lisp function in `grep'.
(grep-find COMMAND-ARGS)

Run grep via find, with user-specified args COMMAND-ARGS.
Collect output in a buffer.
While find runs asynchronously, you can use the C-x ` command
to find the text that grep hits refer to.

This command uses a special history list for its arguments, so you can
easily repeat a find command.

--------------------------------------------------------------------------------
find-dired is an interactive autoloaded Lisp function in `find-dired'.
(find-dired DIR ARGS)

Run `find' and go into Dired mode on a buffer of the output.
The command run (after changing into DIR) is

    find . \( ARGS \) -ls

except that the variable `find-ls-option' specifies what to use
as the final argument.
--------------------------------------------------------------------------------

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.

-- 
  Stefan.