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: Info tutorial is out of date Date: Sat, 15 Jul 2006 07:44:42 -0700 Message-ID: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1152974761 29377 80.91.229.2 (15 Jul 2006 14:46:01 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 15 Jul 2006 14:46:01 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Jul 15 16:45:57 2006 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1G1lOy-0002yY-Op for ged-emacs-devel@m.gmane.org; Sat, 15 Jul 2006 16:45:53 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1G1lOt-0006UE-Ou for ged-emacs-devel@m.gmane.org; Sat, 15 Jul 2006 10:45:47 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1G1lOb-0006Tz-1i for emacs-devel@gnu.org; Sat, 15 Jul 2006 10:45:29 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1G1lOW-0006SV-Tb for emacs-devel@gnu.org; Sat, 15 Jul 2006 10:45:28 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1G1lOW-0006SS-PI for emacs-devel@gnu.org; Sat, 15 Jul 2006 10:45:24 -0400 Original-Received: from [141.146.126.228] (helo=agminet01.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_3DES_EDE_CBC_SHA:24) (Exim 4.52) id 1G1lQj-00058R-3z for emacs-devel@gnu.org; Sat, 15 Jul 2006 10:47:42 -0400 Original-Received: from rcsmt250.oracle.com (rcsmt250.oracle.com [148.87.90.195]) by agminet01.oracle.com (Switch-3.1.7/Switch-3.1.7) with ESMTP id k6FEjGjK027771 for ; Sat, 15 Jul 2006 09:45:16 -0500 Original-Received: from dhcp-amer-whq-csvpn-gw3-141-144-81-31.vpn.oracle.com by rcsmt251.oracle.com with ESMTP id 1570491601152974694; Sat, 15 Jul 2006 08:44:54 -0600 Original-To: "Emacs-Devel" X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) Importance: Normal X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2800.1807 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:57042 Archived-At: I just tried the beginning of the Info tutorial again, after a lapse of a couple decades (!). It doesn't seem to have changed much. I remembered it with more fondness than I felt this time around. Keep in mind that, like Info, it was created long before the Web and mice and such. Back around that campfire, it made sense to explain in detail about nodes and menus and the magic keys you used to get around. Nowadays, some of it seems quaint, some seems crippling. Here's my rant; take it for what you will. Hope it helps somehow. The start of the tutorial teaches you `n', then `p', then `m', then `C-l', and so on. Those keys should be regarded nowadays as shortcuts - quick alternatives to the obvious navigational equivalents of clicking links or using the menu-bar menu. Don't forget that the user somehow got into the Info tutorial with no help - probably by clicking the link at the `dir' node. I don't even see why `C-l' is mentioned anymore, especially at the very beginning of the tutorial. It was important back when 14K baud was a fast transmission speed and your screen got "garbaged" (to quote the tutorial) from time to time. You needed to learn `C-l' at the beginning, because if your screen got garbled then you were lost in the tutorial - that was a game in itself (much more interesting than invisible text). `C-l' is just a vestige of the bad-ole-days - lose it. With absolutely no instruction, a user will figure out immediately how to move among nodes - the equivalent of `n', `p', `u', and `m', because they *see* the corresponding links and buttons. Clicking links and buttons is a fine way to get around, to get the info you need - at least in the beginning. Teaching `n' and `p' does not need to take up the first several minutes of the tutorial - it should be presented much later, perhaps in a (brief) lesson on keyboard shortcuts. It's OK at some point to point out that, unlike Web pages but like the structure of a book, Info nodes are organized into a tree (menu): up, next, and so on. But a lite version of that explanation will suffice, nowadays. Again, all this emphasis on navigation commands is but a vestige of a time when there were no links or buttons, when the universe was still a mouseless void. What it *is* important to teach up front are the important functionalities of Info that are *not* so obvious (visible). Foremost among these are `i', `s', and `l' (and, later, `g'). The first thing the tutorial should do is take a tour of the menu-bar menu - that is, those menu items that are the most important. This is also the opportunity to point out the key bindings indicated in the menu. That is the way to introduce the shortcuts `i', `s', and `l', for instance - in passing. Touring the menu can also be used to introduce the structure of a normal Info manual. By that, I don't mean menus with up and next, so much as showing that there is a table of contents (or two or three) and an index, and how to use them effectively. And if the Info manual had a glossary (it should, especially since it has its own jargon), then that could be introduced too. Users will also find the toolbar by themselves, and they may use that first for some things (such as index lookup), because it is more obvious than the menu-bar menu. It's worth taking a tour of the menu because it shows the keyboard shortcuts, which the toolbar icons do not. Showing the menu-bar menu and its shortcuts will help wean newbies from the toolbar, at least in terms of awareness. BTW, the help text (tooltip) for the search toolbar icon should not scare people away by mentioning regular expressions. It should say simply `Search the manual'. If you don't think that's enough, then it could say `Search the manual (regexp is OK)'. None of the tooltips should use the word "file" - they should say "manual". And we should think about changing the keyword `File:' at the top of each node to `Manual:' - there is no reason that users should think in terms of files here. I'll say one more time, in passing, that an icon for deletion (X) should not be used for quitting Info - that is a bad idea. Several other possibilities were suggested previously (e.g. the international icon for an exit: arrow exiting a room), and there are lots of quit icons to choose from. But that particular X is often used for deletion, a confusion we don't want here. The Info tutorial itself should be accessible (listed) in the menu of the first node of the Info manual. Instead, it is only mentioned in the text of that node, in terms of `h'. Before entering the tutorial, we should tell users how to exit it, to get back where they were. BTW, `h' should not bring up the tutorial, it should display a mini-version of what `C-h m' shows: a short list of the main key bindings - about the same as what's in the menu-bar menu, but with some explanation. There is no need to have a key binding just to bring up the Info tutorial - people won't be doing that 30 times a day. In general (exceptions can be made), key bindings should not be introduced until much later, and then they should be introduced as shortcuts for functionalities the user already knows by then. It is the functionalities that should be on the agenda, not the keys. The emphasis is all wrong in this respect. You lose the forest of functionalities because of all the trees of keys. The node `Invisible text in Emacs Info' is incomprehensible to me ("invisible text is really a part of the text"!?). Yow! Why are we telling users about killing and yanking Info text? (I guess printing is OK.) Why is this near the beginning of the tutorial? I really, really do not get this. This node (`Help-Inv') will scare anyone away from using Info. It is worse than unneeded; it is a downright nuisance. 3/4 of it is composed of crazy disclaimers that users won't understand ("Only the invisibility property is affected by Visible mode" (yow!), and "When, in this tutorial, we refer to the `Emacs' behavior, we mean the _default_ Emacs behavior" (YOW!!)). BTW, what is the reason for the menu in this node? It doesn't seem to be used or useful or understandable. The rule in the tutorial should be that we don't tell people things - we walk them through doing things. Node `Help-Inv' is not just confusing and useless; it also violates this rule. If it were really important for users to know about `visible-mode' and such, then the tutorial should walk them through using it. But in this case, please don't; just get rid of this node! This appears to be an ugly hack to enable the same tutorial to be used in Emacs and standalone Info. Spare the user this kind of all-too-visible bandaid. In general, instead of introducing so many key bindings (e.g. `]'), the tutorial should spend the user's time taking a tour of Info *functionality*. Touring the menu-bar menu is a good way to explore the main functionalities: show what's there and what it does. In addition to the features in the menu-bar menu, teach SPC and DEL - that's about it. In the menu-bar menu, teach these first: `q', `l', `s', and `g'. Why? because they're not obvious (visible, as in links and buttons), and they're essential. Most of what is presented now in the tutorial is either obvious or arcane. The most important things to teach are index lookup and search. They should be done with care, and simple regexp search can be taught here with useful examples. It's good to teach `goto-node' (`g') too, because people will find instructions in emails and on Web sites to go to node `Blah'. Perhaps some of my remarks are inappropriate wrt the standalone reader - I don't know. I used the tutorial only inside Emacs. Adjust my remarks as needed. If the standalone Info still uses only keyboard keys, so that everything I suggested above is irrelevant, then perhaps we need two different tutorials now. HTH.