From: "Stefan Reichör" <xsteve@riic.at>
Subject: Re: Improved help from minibuffer prompts
Date: Mon, 19 Apr 2004 09:51:47 +0200 [thread overview]
Message-ID: <w4dfzb0xv58.fsf@nanni.riic.uni-linz.ac.at> (raw)
In-Reply-To: <E1BEvmK-0005YV-Db@fencepost.gnu.org> (Richard Stallman's message of "Sat, 17 Apr 2004 15:47:04 -0400")
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.
next prev parent reply other threads:[~2004-04-19 7:51 UTC|newest]
Thread overview: 59+ messages / expand[flat|nested] mbox.gz Atom feed top
2004-04-13 6:26 Improved help from minibuffer prompts Stefan Reichör
2004-04-13 6:57 ` Miles Bader
2004-04-13 10:48 ` Stefan Reichör
2004-04-14 1:22 ` Miles Bader
2004-04-14 5:35 ` Stefan Reichör
2004-04-14 6:49 ` Miles Bader
2004-04-14 10:04 ` Kim F. Storm
2004-04-14 10:39 ` Stefan Reichör
2004-04-15 16:44 ` Richard Stallman
2004-04-16 6:15 ` Stefan Reichör
2004-04-16 10:04 ` Kim F. Storm
2004-04-16 13:12 ` Kai Grossjohann
2004-04-14 22:53 ` Richard Stallman
2004-04-15 1:23 ` Kim F. Storm
2004-04-16 18:08 ` Richard Stallman
2004-04-14 3:43 ` Masatake YAMATO
2004-04-14 18:02 ` Richard Stallman
2004-04-14 18:02 ` Richard Stallman
2004-04-15 5:50 ` Stefan Reichör
2004-04-16 18:07 ` Richard Stallman
2004-04-16 21:55 ` Kim F. Storm
2004-04-17 19:47 ` Richard Stallman
2004-04-19 7:51 ` Stefan Reichör [this message]
2004-04-19 11:50 ` Kim F. Storm
2004-04-29 23:48 ` Juanma Barranquero
2004-04-30 5:32 ` Stefan Reichör
2004-04-30 9:07 ` Juanma Barranquero
2004-05-01 17:51 ` Richard Stallman
2004-05-01 18:33 ` Juanma Barranquero
2004-05-02 19:52 ` Richard Stallman
2004-05-02 22:45 ` Juanma Barranquero
2004-05-03 22:20 ` Richard Stallman
2004-05-06 1:08 ` Juanma Barranquero
2004-05-06 14:13 ` Stefan Monnier
2004-05-07 1:11 ` Juanma Barranquero
2004-05-09 2:03 ` Juanma Barranquero
2004-05-07 0:29 ` Richard Stallman
2004-04-30 10:08 ` Kim F. Storm
2004-04-30 13:39 ` Juanma Barranquero
2004-04-30 15:50 ` Kim F. Storm
2004-04-30 22:20 ` Juanma Barranquero
2004-04-30 15:57 ` Stefan Monnier
2004-04-30 21:28 ` Juanma Barranquero
2004-04-30 22:49 ` Stefan Monnier
2004-05-01 2:17 ` Juanma Barranquero
2004-05-01 20:23 ` Stefan Monnier
2004-05-02 1:52 ` Juanma Barranquero
2004-05-04 0:32 ` Juanma Barranquero
2004-05-04 20:07 ` Richard Stallman
2004-05-04 22:52 ` Juanma Barranquero
2004-04-19 17:32 ` Drew Adams
2004-04-20 20:47 ` Richard Stallman
2004-04-20 23:13 ` Drew Adams
2004-04-21 6:25 ` Eli Zaretskii
2004-04-19 18:20 ` Richard Stallman
2004-04-16 18:07 ` Richard Stallman
2004-04-15 11:42 ` Matthew Mundell
2004-04-16 6:05 ` Stefan Reichör
2004-04-18 21:47 ` Richard Stallman
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=w4dfzb0xv58.fsf@nanni.riic.uni-linz.ac.at \
--to=xsteve@riic.at \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.