From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: =?iso-8859-1?q?Stefan_Reich=F6r?= Newsgroups: gmane.emacs.devel Subject: Re: Improved help from minibuffer prompts Date: Mon, 19 Apr 2004 09:51:47 +0200 Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: References: NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1082361305 8484 80.91.224.253 (19 Apr 2004 07:55:05 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Mon, 19 Apr 2004 07:55:05 +0000 (UTC) Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Mon Apr 19 09:54:54 2004 Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1BFTcE-0002Vm-00 for ; Mon, 19 Apr 2004 09:54:54 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1BFTcE-0008NV-00 for ; Mon, 19 Apr 2004 09:54:54 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.30) id 1BFTZy-0000w4-G4 for emacs-devel@quimby.gnus.org; Mon, 19 Apr 2004 03:52:34 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.30) id 1BFTZq-0000ve-16 for emacs-devel@gnu.org; Mon, 19 Apr 2004 03:52:26 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.30) id 1BFTZJ-0000pR-3B for emacs-devel@gnu.org; Mon, 19 Apr 2004 03:52:24 -0400 Original-Received: from [140.78.161.123] (helo=proxy.riic.at) by monty-python.gnu.org with esmtp (TLSv1:DES-CBC3-SHA:168) (Exim 4.30) id 1BFTZI-0000op-LH for emacs-devel@gnu.org; Mon, 19 Apr 2004 03:51:52 -0400 Original-Received: from nanni.riic.uni-linz.ac.at.riic.at (nanni.riic.uni-linz.ac.at [140.78.161.79]) by proxy.riic.at (8.12.7/8.12.7/SuSE Linux 0.6) with ESMTP id i3J7pl8a015559 for ; Mon, 19 Apr 2004 09:51:47 +0200 Original-To: emacs-devel@gnu.org In-Reply-To: (Richard Stallman's message of "Sat, 17 Apr 2004 15:47:04 -0400") User-Agent: Gnus/5.110002 (No Gnus v0.2) Emacs/21.3.50 (berkeley-unix) X-Virus-Scanned: by AMaViS - amavis-milter (http://www.amavis.org/) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.4 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:21871 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:21871 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.