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: Info tutorial is out of date Date: Sun, 16 Jul 2006 10:33:40 -0700 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 1153071418 21980 80.91.229.2 (16 Jul 2006 17:36:58 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sun, 16 Jul 2006 17:36:58 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Jul 16 19:36:58 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 1G2AY3-0000GI-L2 for ged-emacs-devel@m.gmane.org; Sun, 16 Jul 2006 19:36:55 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1G2AY3-0006VV-2E for ged-emacs-devel@m.gmane.org; Sun, 16 Jul 2006 13:36:55 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1G2AVg-0005Uh-Gr for emacs-devel@gnu.org; Sun, 16 Jul 2006 13:34:28 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1G2AVd-0005Sz-Sw for emacs-devel@gnu.org; Sun, 16 Jul 2006 13:34:26 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1G2AVd-0005SM-0L for emacs-devel@gnu.org; Sun, 16 Jul 2006 13:34:25 -0400 Original-Received: from [148.87.113.118] (helo=rgminet01.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_3DES_EDE_CBC_SHA:24) (Exim 4.52) id 1G2AY6-0003Rf-GY for emacs-devel@gnu.org; Sun, 16 Jul 2006 13:36:58 -0400 Original-Received: from rcsmt251.oracle.com (rcsmt251.oracle.com [148.87.90.196]) by rgminet01.oracle.com (Switch-3.1.6/Switch-3.1.6) with ESMTP id k6GGsBVe005477 for ; Sun, 16 Jul 2006 11:34:22 -0600 Original-Received: from dhcp-amer-csvpn-gw1-141-144-64-45.vpn.oracle.com by rcsmt250.oracle.com with ESMTP id 1574146821153071232; Sun, 16 Jul 2006 11:33:52 -0600 Original-To: X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) Importance: Normal In-Reply-To: X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2800.1807 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:57106 Archived-At: If you want, the tutorial could be split in two: first "What Info Is" (with simple how-to, to get the points across), second "How To Use Info Efficiently". That is a good idea, in a general sense. However, I am not sure it is really necessary, for the reason below. My point is this: first things first. If I don't understand what Info is all about, why would I go through the effort of learning and practicing its key bindings? Isn't it obvious to everyone what Info is all about? It's all about browsing documentation files. What's an Info file? Info is about finding information in a manual. The most important things to teach are the structure of the manual and how to find info in it. This means, in particular, pointing out the index, TOC, history list, and glossary, and taking users through using `i', `s', `l', and `g' (whether by menu or key). It's also important to teach that you can exit with `q' and enter again (with `C-h i') exactly where you left off. This is not obvious, and it should be part of the tutorial: exit to do something, and come back, from anywhere in Emacs, with `C-h i'. It's also important to point out the difference between chronological "back" (`l') and structural "back" (e.g. up after down, previous after next). It's also important to teach the key bindings that are not in the menu-bar menu - SPC and DEL. The normal book structure (up, down, next, previous) needs to be at least mentioned, because it is not common on, e.g., the Web. If users learn what main functionalities are available (regexp search, index lookup, goto a named node, navigate through the history, TOC lookup, glossary lookup) and how to use them, they've got 90% of what we need to teach them. Menus, and moving up, moving thru a series using next and previous, are going to be obvious to anyone that has used the WWW very much. Next and previous are common on the web. The up, down, next, previous book structure of an Info manual is *not* at all common on the Web. But it is familiar from books, so it only requires pointing out and mentioning the book analogy. Thus, practically speaking, I think there isn't much to be achieved by having a separate easier section which just teaches you "what Info is all about". I don't care whether such info is in a separate section. But, to me, what Info is for and what you can do with it are what the tutorial should be all about. The extra section for "how to use keyboard shortcuts to be more efficient" is the section I would get rid of, if we got rid of one of the two proposed sections. I don't propose getting rid of it however, just moving it to the end. I also mentioned the need to have specific tutorial instruction for those keys (e.g. SPC and DEL) that are *not* so obvious. Teaching `n' right away is a waste of time, not because `n' is useless, but because there is an obvious (if perhaps somewhat slower) way to do the same thing. That might be a good point. As to the fingers-leaving-the-keyboard argument: That is not such a strong argument for Info, where people are reading, not editing. I agree, that is not a crucial issue for Info. 1) teach what Info is about, first; 2) start using the obvious how-to (e.g. links, buttons, menu-bar), to teach #1; 3) teach the non-obvious how-to (e.g. SPC, DEL) also; Those three are an idea worth trying. I have doubts that this would be much easier, but there's no harm in trying it out, and maybe the results would be good. 4) don't bother teaching the obvious, if more-efficient, how-to (e.g. `n'), except possibly as an efficiency booster, after getting the real message across. We definitely should teach these commands later on. I agree (and I use them, always). But what does "teach" mean here? I think it would be enough to 1) point them out (from the menu-bar menu), 2) recommend them, for efficiency, and 3) run through using one or two briefly. The reason for focusing on n and p rather than SPC and DEL is partly historical. Originally, SPC and DEL only moved within a node. Yes. And n and p were the only ways to get around. They are still the best ways, but it is easier to get to the important points (to teach those firt) using the menu-bar or links and navigation buttons to get there.