From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Intermediate tutorial shipped with Emacs Date: Sat, 19 Sep 2015 10:22:33 +0300 Message-ID: <834miqrhza.fsf@gnu.org> References: <87a8sjcfr6.fsf@earth.catern.com> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1442647670 27337 80.91.229.3 (19 Sep 2015 07:27:50 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 19 Sep 2015 07:27:50 +0000 (UTC) Cc: emacs-devel@gnu.org To: Spencer Baugh Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Sep 19 09:27:34 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 1ZdCYX-00005X-HH for ged-emacs-devel@m.gmane.org; Sat, 19 Sep 2015 09:27:33 +0200 Original-Received: from localhost ([::1]:44190 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZdCYW-0005OW-Se for ged-emacs-devel@m.gmane.org; Sat, 19 Sep 2015 03:27:32 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47033) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZdCTi-0006Tx-FN for emacs-devel@gnu.org; Sat, 19 Sep 2015 03:22:35 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZdCTe-0008Ky-Hh for emacs-devel@gnu.org; Sat, 19 Sep 2015 03:22:34 -0400 Original-Received: from mtaout26.012.net.il ([80.179.55.182]:40390) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZdCTe-0008Ho-4Q for emacs-devel@gnu.org; Sat, 19 Sep 2015 03:22:30 -0400 Original-Received: from conversion-daemon.mtaout26.012.net.il by mtaout26.012.net.il (HyperSendmail v2007.08) id <0NUW00H00XXFWR00@mtaout26.012.net.il> for emacs-devel@gnu.org; Sat, 19 Sep 2015 10:25:01 +0300 (IDT) Original-Received: from HOME-C4E4A596F7 ([84.94.185.246]) by mtaout26.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0NUW00FNIXXO8W20@mtaout26.012.net.il>; Sat, 19 Sep 2015 10:25:01 +0300 (IDT) In-reply-to: <87a8sjcfr6.fsf@earth.catern.com> X-012-Sender: halo1@inter.net.il X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 80.179.55.182 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:190078 Archived-At: > From: Spencer Baugh > Date: Fri, 18 Sep 2015 22:19:41 -0400 > > I think it would be good if Emacs shipped with an intermediate tutorial, > covering topics beyond the basic tutorial. It would, indeed. The problem is, as always, what does "intermediate tutorial" means for Emacs. > Topics-wise, I envision it would briefly cover things like: > - keyboard macros > - TRAMP > - the various ways to get help inside Emacs > - narrowing > - dired > - calc > - et cetera Past discussions more or less concluded that there should be a series of intermediate-level tutorials, each one covering topics in some distinct area. 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; narrowing should be in a tutorial that also explains folding, outline mode, hide-ifdef, and other similar features. Calc is a topic by itself (doesn't it include its own tutorial in its manual?), perhaps together with Calculator. Etc. etc. -- I would suggest first to come up with a list of the areas, or at least produce a couple of tutorials along these lines. > The hope would be to give users a taste of some of the more advanced > features of Emacs. Then, if they are faced with a situation that one of > those features that they read about in the intermediate tutorial would > be useful for, they'll search the help system for more information > rather than be frustrated. That's a challenge in itself: how do you give "a taste" of a feature without describing it in full, or close to that. The manual doesn't describe all of the facets of each feature it covers, only the important stuff, leaving the rest to be discovered by the user by using the help system and the source. You need some clear rules about where to stop the "give a taste" description to avoid being another version of the corresponding manual sections. > 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. 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). > 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 the > 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. More documentation is always a good idea, IMO. Thanks.