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 menu (was: Re: describe-bindings: ^L, bad order, naming) Date: Wed, 16 Nov 2005 15:29:57 -0800 Message-ID: References: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="ISO-8859-15" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1132183953 29400 80.91.229.2 (16 Nov 2005 23:32:33 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 16 Nov 2005 23:32:33 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Nov 17 00:32:22 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1EcWjQ-0004LD-5H for ged-emacs-devel@m.gmane.org; Thu, 17 Nov 2005 00:30:24 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1EcWjP-0000yK-Bt for ged-emacs-devel@m.gmane.org; Wed, 16 Nov 2005 18:30:23 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1EcWjF-0000y5-6M for emacs-devel@gnu.org; Wed, 16 Nov 2005 18:30:13 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1EcWjE-0000xt-FG for emacs-devel@gnu.org; Wed, 16 Nov 2005 18:30:12 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1EcWjE-0000xq-CR for emacs-devel@gnu.org; Wed, 16 Nov 2005 18:30:12 -0500 Original-Received: from [141.146.126.228] (helo=agminet01.oracle.com) by monty-python.gnu.org with esmtp (TLS-1.0:DHE_RSA_3DES_EDE_CBC_SHA:24) (Exim 4.34) id 1EcWjE-0000EK-AO for emacs-devel@gnu.org; Wed, 16 Nov 2005 18:30:12 -0500 Original-Received: from rgmsgw300.us.oracle.com (rgmsgw300.us.oracle.com [138.1.186.49]) by agminet01.oracle.com (Switch-3.1.7/Switch-3.1.7) with ESMTP id jAGNglYd019266 for ; Wed, 16 Nov 2005 17:42:48 -0600 Original-Received: from rgmsgw300.us.oracle.com (localhost [127.0.0.1]) by rgmsgw300.us.oracle.com (Switch-3.1.7/Switch-3.1.7) with ESMTP id jAGNU8xH027840 for ; Wed, 16 Nov 2005 16:30:08 -0700 Original-Received: from dradamslap (dradams-lap.us.oracle.com [130.35.177.126]) by rgmsgw300.us.oracle.com (Switch-3.1.7/Switch-3.1.7) with SMTP id jAGNU8L6027832 (version=TLSv1/SSLv3 cipher=RC4-MD5 bits=128 verify=NO) for ; Wed, 16 Nov 2005 16:30:08 -0700 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.1506 X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE 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:46130 Archived-At: The first item, "This...", lets you type a key sequence or click something (e.g. mode-line, minibuffer, Emacs-related name in a buffer, menu item), and it gives you information on that object. The info is that provided by `describe-*', plus apropos + Info doc, if appropriate. I don't see concretely how that differs from C-h k. Could you give details? Something similar was discussed a while back, I believe. I'm not sure it's worth people spending time considering now, but here's a description (below). Take it as food for thought - some parts of it might be more useful than others. The basic idea is to let users discover features of Emacs by pointing to them (or their names) individually and saying "what's this?". It emulates some UIs that provide a menu item that, when clicked, turns the mouse pointer to a question mark. The user then clicks the pointer on some object, and some info is provided on that object. In MS Windows, this is called "What's This". The emacs-devel discussion a while back turned around the question of whether or not Windows still has this feature etc. This is not something that started with Windows, BTW - it was available in applications long before Windows existed. The "What's This" feature on Windows was often poorly implemented, providing little help. However, Emacs already has online help about all of its features - this would simply help users get to that help on a feature-by-feature basis: just point and ask. In my case, I didn't change the mouse pointer to a question mark, but that would probably be a good thing to do. Also, I wanted to give a maximum of info on the object, whereas Windows "What's This" tends to give minimal, one-liner info (similar to tool-tip info). So, I combined info from the various help commands (e.g. `describe-key', `apropos') with info from the manual. I simply let the various component help sources open their own windows (frames in my case), so the user could decide which to read and which to ignore (that was also the easiest implementation for me). That is, I made no attempt to integrate the various help sources that I tapped. Emacs help is more or less detailed, depending, for example, on whether it is provided by `describe-variable', `apropos', `apropos-documentation', or `info'. Each of these (if available and appropriate) was displayed in a separate frame - the user could choose which to examine, depending on the context and the user's background. Any feature that you can designate through the UI is a candidate for explaining this way, BTW, not just UI features. For example, you can point to an Emacs name (wherever you see it) and get info about it. This was also the case for Windows' "What's This", to some extent, though often it was not clear if you were asking for help about a UI feature or about the underlying functionality. Obviously, there needs to be some hierarchy in the implementation, to guess whether the user wants info on some name or the buffer where it occurs, and so on. Anyway, here's the description (from the doc string of command `help-on-click/key': "(help-on-click/key KEY) Give help on a key/menu sequence or object clicked with the mouse. The object can be any part of an Emacs window or a name appearing in a buffer. You can do any of the following: type a key sequence (e.g. `C-M-s') choose a menu item (e.g. [menu-bar files open-file]) click on a scroll bar click on the mode line click in the minibuffer click on an Emacs-related name in a buffer: apropos is called click anywhere else in a buffer: its modes are described Help is generally provided using `describe-key' and the Emacs online manual (via `Info-goto-emacs-key-command-node'). If no entry is found in the index of the Emacs manual, then the manual is searched from the beginning for literal occurrences of KEY. For example, the KEY `C-g' is not in the index (for some reason), so the manual is searched. (Once an occurrence is found, you can repeatedly type `s' in *Info* to search for additional occurrences.) If you click on a name in a buffer, then `apropos-documentation' and `apropos' are used to find information on the name. These functions are not used when you do something besides click on a name. If you click elsewhere in a buffer other than the minibuffer, then `describe-mode' is used to describe the buffer's current mode(s)." Again, this was for Emacs 20, so this description would not be complete for Emacs 22 (there are a lot more things to point to now: fringe etc.). And the comment about `C-g' not being in the Emacs-manual index is no longer true. Nevertheless, that functionality might still be useful: search the manual text if the term to find is not in the index. The expectation, BTW, was not that users would learn about this by reading the above help - that would be confusing for someone who didn't know what a minibuffer was etc. The idea was that users would just try it (click "Describe > This..." in the menu) and find out what it is by using it. If such a feature were considered for Emacs (for after the release), these aspects could be discussed: - What info should be provided (e.g. what info sources, how much detail)? - For what objects? - How would a user designate each of those objects? This command is intended to help people to discover Emacs features. The general idea is, I think, a good one, regardless of what design might be used. Emacs is feature-rich, and its UI offers a lot that many newbies have never experienced elsewhere (it is unusual). And many of the UI features are not obvious (not to mention the non-UI features). HTH.