From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: RE: Improved help from minibuffer prompts Date: Mon, 19 Apr 2004 10:32:06 -0700 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" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1082397475 10940 80.91.224.253 (19 Apr 2004 17:57:55 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Mon, 19 Apr 2004 17:57:55 +0000 (UTC) Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Mon Apr 19 19:57:48 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 1BFd1f-0001bi-00 for ; Mon, 19 Apr 2004 19:57:47 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1BFd1f-0008Fd-00 for ; Mon, 19 Apr 2004 19:57:47 +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 1BFcfk-0000x8-CJ for emacs-devel@quimby.gnus.org; Mon, 19 Apr 2004 13:35:08 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.30) id 1BFcez-0000qZ-AE for emacs-devel@gnu.org; Mon, 19 Apr 2004 13:34:21 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.30) id 1BFceP-0000f7-G6 for emacs-devel@gnu.org; Mon, 19 Apr 2004 13:34:17 -0400 Original-Received: from [148.87.2.204] (helo=inet-mail4.oracle.com) by monty-python.gnu.org with esmtp (TLSv1:DES-CBC3-SHA:168) (Exim 4.30) id 1BFceO-0000eR-IE for emacs-devel@gnu.org; Mon, 19 Apr 2004 13:33:44 -0400 Original-Received: from rgmgw4.us.oracle.com (rgmgw4.us.oracle.com [138.1.191.13]) by inet-mail4.oracle.com (Switch-3.1.4/Switch-3.1.0) with ESMTP id i3JHTs6c014121 for ; Mon, 19 Apr 2004 10:29:55 -0700 (PDT) Original-Received: from rgmgw4.us.oracle.com (localhost [127.0.0.1]) by rgmgw4.us.oracle.com (Switch-2.1.5/Switch-2.1.0) with ESMTP id i3JHW8f00673 for ; Mon, 19 Apr 2004 11:32:08 -0600 (MDT) Original-Received: from dradamslap (dradams-lap.us.oracle.com [130.35.177.126]) by rgmgw4.us.oracle.com (Switch-2.1.5/Switch-2.1.0) with SMTP id i3JHW7f00643 for ; Mon, 19 Apr 2004 11:32:07 -0600 (MDT) Original-To: X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) In-Reply-To: X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2800.1409 Importance: Normal 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:21897 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:21897 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: emacs-devel-bounces+drew.adams=oracle.com@gnu.org [mailto:emacs-devel-bounces+drew.adams=oracle.com@gnu.org]On Behalf Of Stefan Reichor Sent: Monday, April 19, 2004 12:52 AM To: emacs-devel@gnu.org 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.