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: Intermediate tutorial shipped with Emacs Date: Sat, 19 Sep 2015 08:57:16 -0700 (PDT) Message-ID: <4ef52604-8c14-485a-94df-cabe9bc51b7e@default> References: <<87a8sjcfr6.fsf@earth.catern.com>> <<834miqrhza.fsf@gnu.org>> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1442678297 1486 80.91.229.3 (19 Sep 2015 15:58:17 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 19 Sep 2015 15:58:17 +0000 (UTC) Cc: emacs-devel@gnu.org To: Eli Zaretskii , Spencer Baugh Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Sep 19 17:58:05 2015 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1ZdKWX-0003rQ-MI for ged-emacs-devel@m.gmane.org; Sat, 19 Sep 2015 17:58:01 +0200 Original-Received: from localhost ([::1]:46710 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZdKWW-0008D2-P8 for ged-emacs-devel@m.gmane.org; Sat, 19 Sep 2015 11:58:00 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:34521) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZdKWG-0008BP-MM for emacs-devel@gnu.org; Sat, 19 Sep 2015 11:57:46 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZdKWF-0007L8-70 for emacs-devel@gnu.org; Sat, 19 Sep 2015 11:57:44 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:32978) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZdKW7-0007H1-Pq; Sat, 19 Sep 2015 11:57:35 -0400 Original-Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id t8JFvPd5025834 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sat, 19 Sep 2015 15:57:26 GMT Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserv0022.oracle.com (8.13.8/8.13.8) with ESMTP id t8JFvO16010044 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Sat, 19 Sep 2015 15:57:25 GMT Original-Received: from abhmp0014.oracle.com (abhmp0014.oracle.com [141.146.116.20]) by userv0121.oracle.com (8.13.8/8.13.8) with ESMTP id t8JFvNis003974; Sat, 19 Sep 2015 15:57:24 GMT In-Reply-To: <<834miqrhza.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9 (901082) [OL 12.0.6691.5000 (x86)] X-Source-IP: aserv0022.oracle.com [141.146.126.234] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-Received-From: 156.151.31.81 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:190102 Archived-At: > > I think it would be good if Emacs shipped with an intermediate tutorial= , > > covering topics beyond the basic tutorial. Where "beyond" just means some stuff that is not covered in the first tutorial. It need not imply "more advanced" or "more difficult". It could be good to have such tutorials shipped with Emacs, but that's not a requirement. This is something that people can easily contribute to (anywhere, in any way), and it can sometimes be helpful to point to non-vanilla extensions. > It would, indeed. The problem is, as always, what does > "intermediate tutorial" means for Emacs. >=20 > > Topics-wise, I envision it would briefly cover things like: > > - keyboard macros > > - TRAMP > > - the various ways to get help inside Emacs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Yes. And that's the reason I'm replying to this thread. And "get help" is an extensible concept. For this topic, it's about about getting help about getting help, and it goes way beyond just `C-h', `apropos', and `C-h r'. > > - narrowing > > - dired > > - calc > > - et cetera >=20 > Past discussions more or less concluded that there should be a series > of intermediate-level tutorials, each one covering topics in some > distinct area. Not necessarily "in some distinct area" (depending on what you mean by that). "Topics" need not mean separate areas of use cases or separate features. Some topics and some information can be used everywhere in Emacs. > So the topics you present above, that are unrelated to > each other and probably reflect your personal interests (or even > some random selection) are probably not the way to go. Tramp > should probably be in a tutorial dedicated to remote editing > and URL-related features;=20 > narrowing should be in a tutorial that also explains folding, > outline mode, hide-ifdef, and other similar features. Now there's a good example of what I mean by some topics being _generally_ useful. Narrowing is useful pretty much everywhere. The other ways you cite of hiding & revealing information are not. All share the characteristic of hiding and revealing (as do some other features), but from that list only narrowing is applicable everywhere. > > As an example, consider narrowing. If a user didn't already know > > narrowing existed, they probably wouldn't even bother searching for the > > feature; it isn't obvious how useful until you know about it. A user > > without knowledge of narrowing would use other hacks. >=20 > A very good example. Narrowing is described in the manual in a > 58-line section. How would you go about giving the user a "taste of" > narrowing, without essentially telling the same story in slightly > different words? It's not trivial (but not impossible, either). I would perhaps put narrowing in a tutorial that shows making use of the region in various ways. [And if this were on the wiki or otherwise outside vanilla Emacs, I would show how you can have multiple narrowings that you can flip among, and multiple regions that you can act on, together or separately. That's from my library `zones.el', but there are probably some other extensions that also let you make more use of regions and narrowings.] > > As I said earlier, I have written such a document in org, because I > > needed reference material to provide my students when I do Emacs > > workshops. (It's still mostly a draft, and it's somewhat specific to th= e > > workshops, so if you want to see it send me mail.) > > > > So, I wanted to see if emacs-devel thought this was a good idea, or a > > bad idea, or if anyone had any suggestions. I would be happy to adapt > > the document I've already written if that makes sense. >=20 > More documentation is always a good idea, IMO. OK, so some more doc might help. And certainly there are features, some of them basic or commonly used, some of them less so, that users could benefit from seeing in action (video, tutorials, etc.). Showing examples of _what you can do_ with a feature can be very helpful, and it is not really the aim of our manuals, which are mostly reference (and rightfully so). In a somewhat different direction (and the reason I'm replying to this thread), it can be helpful to show users more about how they can *ask Emacs* itself. That means a tutorial about *help*, *apropos* commands and using the *manuals* productively, sure, but also some *Lisp* basics, with emphasis on how you can use them to ask Emacs about itself - the current state, what happened, why, what you can/cannot do next, etc. This means some info about: evaluation; symbols; lists; faces; text & overlay properties; strings, including propertized; commands & other functions; startup, packages, `load-path', and Customize; defcustom, defun, etc.; key bindings, keymaps, and menus; `C-g', recursive minibuffers, and `M-:'; `debug' & backtraces; how to file a bug report; hooks & modes; and other info that many of us use everyday but that new users might have no clue is available (because it typically is not, in environments they are familiar with). The emphasis would be on knowing something about such things in order to ask Emacs questions that a non-expert (or even an expert sometimes) might have. It would also cover common misconceptions, gotchas, what you can do when you are lost, etc. Much of the power of Emacs comes from the ease with which you can dig into it to understand what is happening, including what is going "wrong" according to your expectations. Emacs is open, from top to bottom. How to open it and peer within is the fundamental Emacs question and the key to using Emacs as Emacs. The second question of the following bug report is a good example, and there are plenty of others, of how a user with just a few additional pointers could have found the info and understanding he was looking for: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D21510. (Could he have found that info in the manual? Of course. That's not the question here. Tutorials can also help.) Nothing wrong with asking on a mailing list or forum, or reporting a problem, of course - quite the contrary. But Emacs is especially easy to dig into, asking for info, and learning Emacs has a lot to do with learning how to _ask Emacs_. Knowing _that_ you can do this, and then knowing _how_ to do it, are not obvious to a newbie. Asking Emacs does involve speaking Lisp to some extent, and I think that some basic Lisp should be part of such a tutorial from the _beginning_. You need to be able to find your way around basic Lisp constructs and ask Lisp, to ask Emacs productively.