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: Tue, 20 Apr 2004 16:13:04 -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="iso-8859-1" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1082505610 3108 80.91.224.253 (21 Apr 2004 00:00:10 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 21 Apr 2004 00:00:10 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Wed Apr 21 01:59:58 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 1BG59i-0001Im-00 for ; Wed, 21 Apr 2004 01:59:58 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1BG59h-0000I5-00 for ; Wed, 21 Apr 2004 01:59:57 +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 1BG55l-0007yz-Gf for emacs-devel@quimby.gnus.org; Tue, 20 Apr 2004 19:55:53 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.30) id 1BG55W-0007xV-9a for emacs-devel@gnu.org; Tue, 20 Apr 2004 19:55:38 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.30) id 1BG54y-0007sM-TP for emacs-devel@gnu.org; Tue, 20 Apr 2004 19:55:36 -0400 Original-Received: from [141.146.126.230] (helo=agminet03.oracle.com) by monty-python.gnu.org with esmtp (TLSv1:DES-CBC3-SHA:168) (Exim 4.30) id 1BG52Q-0006xs-Dw; Tue, 20 Apr 2004 19:52:26 -0400 Original-Received: from agminet03.oracle.com (localhost [127.0.0.1]) by agminet03.oracle.com (Switch-3.1.2/Switch-3.1.0) with ESMTP id i3KNnBFS018881; Tue, 20 Apr 2004 16:52:10 -0700 Original-Received: from rgmgw1.us.oracle.com (rgmgw1.us.oracle.com [138.1.191.10]) by agminet03.oracle.com (Switch-3.1.2/Switch-3.1.0) with ESMTP id i3KND9A2021103; Tue, 20 Apr 2004 16:14:07 -0700 Original-Received: from rgmgw1.us.oracle.com (localhost [127.0.0.1]) by rgmgw1.us.oracle.com (Switch-3.1.4/Switch-3.1.0) with ESMTP id i3KNDAda009464; Tue, 20 Apr 2004 17:13:10 -0600 Original-Received: from dradamslap (dhcp-amer-vpn-gw2-east-141-144-68-111.vpn.oracle.com [141.144.68.111]) by rgmgw1.us.oracle.com (Switch-3.1.4/Switch-3.1.0) with SMTP id i3KND7AM009400; Tue, 20 Apr 2004 17:13:10 -0600 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: Importance: Normal X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2800.1409 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:21971 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:21971 below -----Original Message----- From: Richard Stallman [mailto:rms@gnu.org] Sent: Tuesday, April 20, 2004 1:48 PM To: Drew Adams Cc: emacs-devel@gnu.org Subject: Re: Improved help from minibuffer prompts 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. > I agree completely. Anyone who has signed papers, please rewrite > doc strings in these ways whenever you feel you need a break > from fixing bugs. 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? > That would be very inconvenient in practical use. We're considering > other suggestions that are much easier to use. I don't see them as . "much easier to use" or . very useful. We're considering the benefits of a help-key when prompted for an input arg to a command; the key would call up some help on the arg. Bringing up the entire doc string was mentioned as one possibility. If the doc string is not well written, then the solution is to rewrite it. If the doc string is well written, I don't see much utility in the arg-prompt help. If it just brings up the doc string, I suppose that's OK, but in that case it would be sufficient for it to serve as a reminder (esp. to newbies) that the args are described via `C-h f'. My point here was that the key sequence that calls up help when inputting an arg could just (generically) echo "Use `C-h f ' for more information". If you need to read the doc string to continue inputting an arg, I think you can exit the command, read it, then execute the command again. How hard is it to re-execute a command? I don't see much utility in *temporarily* leaving the arg-input process to consult the help, then continuing where you left off, inputting. That kind of thing is OK for query-replace, but it's not very useful in this context, IMO. As I said, however, I have not tried the proposed help, so this is just a prejudice. I try to imagine the new feature, and I don't see it helping. Those who have used it apparently find it helpful. 5) Often, a prefix arg (present/absent; positive, negative, zero; other specific values) is very important to a command's functioning. > That is true. However,... It would not be explained by the proposed arg help; > Maybe so, but I don't follow your point. We're talking about offering > help for how to enter a minibuffer argument. Could you explain > precisely how the prefix arg relates to this? 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. > So what? We're talking about getting help for entering a minibuffer > argument. My point here is that if the input-arg help does *not* include the whole doc string, then it only goes so far toward helping you use & learn about the command. That's OK as far as it goes, but you might get the impression that you've learned it all, and miss out on some important functionality. If, on the other hand, the prompt help just says `Use `C-h f' for more information' (or if it showed you the entire doc string directly), then you might learn more. In sum: 1. If the arg-input help does *not* give you the whole doc string (directly or indirectly), then: . It's not worth it. . It might lead you to miss out on important info in the doc string. 2. If the arg-input help gives you the whole doc string *directly*, then: . It's not worth it. A reminder about `C-h f' is as good. In fact, it's better that folks get in the habit of using `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. > Someone saw room for improvement, but I don't want to say I am certain > it is important. Perhaps things are good enough as they are. IMO, they are. #2 and #3 at the top are key: good doc strings, good prompts (and commands that don't require understanding complex input args). There is still the question of the utility of (somehow) structuring doc strings - that is, making them doc structures, not just strings. Any juice there? - Drew