From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Richard Stallman Newsgroups: gmane.emacs.devel Subject: Re: Improved help from minibuffer prompts Date: Tue, 20 Apr 2004 16:47:54 -0400 Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: References: Reply-To: rms@gnu.org NNTP-Posting-Host: deer.gmane.org X-Trace: sea.gmane.org 1082495062 15670 80.91.224.253 (20 Apr 2004 21:04:22 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Tue, 20 Apr 2004 21:04:22 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Tue Apr 20 23:04:16 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 1BG2Pf-0006C9-00 for ; Tue, 20 Apr 2004 23:04:15 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1BG2Pf-0006C6-00 for ; Tue, 20 Apr 2004 23:04:15 +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 1BG2JM-0006Ad-8w for emacs-devel@quimby.gnus.org; Tue, 20 Apr 2004 16:57:44 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.30) id 1BG2CP-0004UT-8Q for emacs-devel@gnu.org; Tue, 20 Apr 2004 16:50:33 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.30) id 1BG2Bi-0004HF-Hz for emacs-devel@gnu.org; Tue, 20 Apr 2004 16:50:22 -0400 Original-Received: from [199.232.76.164] (helo=fencepost.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.30) id 1BG2B8-00043c-9n for emacs-devel@gnu.org; Tue, 20 Apr 2004 16:49:14 -0400 Original-Received: from rms by fencepost.gnu.org with local (Exim 4.24) id 1BG29q-0005Pj-5T; Tue, 20 Apr 2004 16:47:54 -0400 Original-To: "Drew Adams" In-reply-to: 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:21957 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:21957 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. 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. 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.