From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: RE: help-fns.el patch for commands to describe options and commands Date: Sat, 20 Oct 2007 09:59:31 -0700 Message-ID: References: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="iso-8859-15" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1192899638 2880 80.91.229.12 (20 Oct 2007 17:00:38 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 20 Oct 2007 17:00:38 +0000 (UTC) Cc: emacs-devel@gnu.org To: Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Oct 20 19:00:39 2007 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1IjHgk-00072G-Rv for ged-emacs-devel@m.gmane.org; Sat, 20 Oct 2007 19:00:39 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1IjHgd-0002DS-E5 for ged-emacs-devel@m.gmane.org; Sat, 20 Oct 2007 13:00:31 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1IjHgY-0002CM-Km for emacs-devel@gnu.org; Sat, 20 Oct 2007 13:00:26 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1IjHgW-00029S-Vt for emacs-devel@gnu.org; Sat, 20 Oct 2007 13:00:26 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1IjHgW-00029H-TH for emacs-devel@gnu.org; Sat, 20 Oct 2007 13:00:24 -0400 Original-Received: from rgminet01.oracle.com ([148.87.113.118]) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1IjHgR-0005Dp-9o; Sat, 20 Oct 2007 13:00:19 -0400 Original-Received: from rgmgw1.us.oracle.com (rgmgw1.us.oracle.com [138.1.186.110]) by rgminet01.oracle.com (Switch-3.2.4/Switch-3.1.6) with ESMTP id l9KH0GAG005992; Sat, 20 Oct 2007 11:00:16 -0600 Original-Received: from acsmt351.oracle.com (acsmt351.oracle.com [141.146.40.151]) by rgmgw1.us.oracle.com (Switch-3.2.4/Switch-3.2.4) with ESMTP id l9KH0Fa7021450; Sat, 20 Oct 2007 11:00:16 -0600 Original-Received: from dhcp-amer-csvpn-gw2-141-144-74-27.vpn.oracle.com by acsmt351.oracle.com with ESMTP id 3307439861192899560; Sat, 20 Oct 2007 09:59:20 -0700 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.2900.3198 X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE X-detected-kernel: by monty-python.gnu.org: Linux 2.4-2.6 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:81308 Archived-At: > Attached is a patch for help-fns.el. It modifies > `describe-function' and `describe-variable', so that a > prefix arg means that candidates are commands > and user options, respectively. So `C-u C-h f' shows and > accepts only commands as completion candidates, and > `C-u C-h v' shows and accepts only user options for completion. > > That doesn't sound very useful to me. What is the benefit it > seeks to provide? Only to limit completion? Yes. When you are looking for a command, you don't want to see a zillion non-interactive functions as candidates. This cuts down that noise *considerably*. Users who don't fiddle with Emacs Lisp want to know about commands more often than non-interactive functions. Same thing for user options - they want to know what options might be available for controlling this or that. They don't want to see zillions of internal variable names - quel horreur ! And there are many *more* internal names than external, end-user names - double the insult. Give them only what they are interested in - less noise. (And "them" is also us. Don't you sometimes want to know about a command or option?) > I won't object to installing it, but I do not want to document it in > the Emacs Manual, because it isn't worth the paper. OK. Anyway, I guarantee it'll eventually be a faq on Emacs Wiki (and without me putting it there). One way or the other, people will find it and use it and pass the knowledge along. If they learn anything about help, this will be it. This is a stupid-simple feature, but it should have been there all along, IMO. > In addition, for convenience, two new commands are defined to > do the same thing without `C-u': `describe-command' and > `describe-option'. This is especially useful for newbies, who > might search for something that describes a command or an option. > > I don't think this is is going to be useful for newbies. They won't > learn these commands. Reason? Why not useful? Why not learnable? Will they not learn these because they are not bound to keys? How about binding them? An end user is more interested in describing commands and options than arbitrary functions and variables, so you could even argue that these deserve bindings more than `describe-function' and `describe-variable' (I don't argue that, however). I'd rather see `C-h c' for `describe-command' and `C-h o' for `describe-option'. I'd move `describe-key-briefly' to `C-u C-h k' (but, then, I never use it). [No, we need not have a war over particular bindings; I just wanted to claim that this is useful to newbies and it could warrant bindings.] We go to the trouble (since day 1, in fact) of providing a dedicated command and key binding for apropos of commands (only). How is this different? By your logic, we should remove `command-apropos' and give users just `apropos'. > If they remember anything relevant it will be > C-h f and C-h v. C-h f works with commands just as with > noninteractive functions; C-h v works with user options just as with > other variables. Which is fine if you want that generality. And not fine if you have a narrower focus. > If you are saying that you think some newbies will type M-x > describe-command to look for a command, I think that will be quite > rare. If we want to make that work, the simplest way is to alias > describe-command to describe-function. If someone wants to find a command, why would you give him only a way to find all functions? By that logic, give him only one command that describes all functions and variables, with all of their names available at once for completion. Why help the user by distinguishing which are functions and which are variables? The point is to give users a tool that narrows the possibilities, that from the beginning weeds out candidates that they know they don't want (in a particular context). If I want to know about an option, then I don't want the added noise of internal variable names. When the user has a focus, s?he wants a tool that respects that focus. The other point was that these command names say what they do, so a user looking for something that describes commands is more likely to find `describe-command' than `describe-function'. Try `M-x apropos describe command' - nada. Now try `M-x apropos describe function'. OK, try `C-h a describe function'. Repeat for `option' and `variable'. And an absolute beginner might not even imagine that an editor command is a "function" in Emacs. Open TextPad or (shudder) Notepad or another typical end-user text editor. Go into the Help and search for "function". Now search for "command". Do you see the difference in hits? Go to http://en.wikipedia.org/wiki/Text_editor and search for "function", then "command" - 2 hits vs 14, and those 2 are not really about functions that are commands. But Emacs is for programmers, you say? Go to http://en.wikipedia.org/wiki/Vi and count again: 0 hits for "function", 51 for "command". Moral: an Emacs newbie will look for commands to do things, not functions. Yes, your aliasing would take care of that part - but not the noise-reduction part.