From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Wording of the Elisp manuals (was: forward-comment and syntax-ppss) Date: Tue, 20 Dec 2016 18:01:51 +0200 Message-ID: <83y3za37yo.fsf@gnu.org> References: <83fd1db0-7362-6117-c5cd-715398c0dea4@gmail.com> <20161207220447.GA4503@acm.fritz.box> <20161208201517.GB3120@acm.fritz.box> <20161209190747.GC2203@acm.fritz.box> <5a70902f-882e-f616-74b2-df6eb81fc70c@yandex.ru> <20161211101715.GA14084@acm.fritz.box> <51c0554f-40d0-37a5-b134-17058343aa3f@yandex.ru> <877a8d5a-ee08-29a1-8c7e-6cc8a82dfc83@gmail.com> <4ded3b07-18ab-4864-b72d-f217a86c123d@default> <295c7d25-444d-2bf5-b649-e9eafec3bd2d@gmail.com> <08a5c56e-e942-4608-aaa9-01aa437ee438@default> <8737hn40r3.fsf@mbork.pl> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1482249745 18635 195.159.176.226 (20 Dec 2016 16:02:25 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 20 Dec 2016 16:02:25 +0000 (UTC) Cc: emacs-devel@gnu.org To: Jean-Christophe Helary Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Dec 20 17:02:08 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cJMra-0001lv-8R for ged-emacs-devel@m.gmane.org; Tue, 20 Dec 2016 17:02:02 +0100 Original-Received: from localhost ([::1]:52014 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cJMre-00054l-Px for ged-emacs-devel@m.gmane.org; Tue, 20 Dec 2016 11:02:06 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:33360) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cJMrZ-00054d-1y for emacs-devel@gnu.org; Tue, 20 Dec 2016 11:02:02 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cJMrV-0003en-67 for emacs-devel@gnu.org; Tue, 20 Dec 2016 11:02:01 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:33455) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cJMrV-0003eh-47; Tue, 20 Dec 2016 11:01:57 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:2970 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1cJMrT-0002yZ-SG; Tue, 20 Dec 2016 11:01:56 -0500 In-reply-to: (message from Jean-Christophe Helary on Tue, 20 Dec 2016 19:52:28 +0900) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 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" Xref: news.gmane.org gmane.emacs.devel:210662 Archived-At: > From: Jean-Christophe Helary > Date: Tue, 20 Dec 2016 19:52:28 +0900 > > > > On 2016 Dec 17, at 13:50, Marcin Borkowski wrote: > > > > Wouldn't it be a good idea to state clearly somewhere that ELisp Intro > > is not only about introduction to programming, but also about > > introdcution to Emacs as the Elisp environment? Narrowing is first > > mentioned in Chapter 9 of the Elisp Reference and only described in > > detail in Chapter 29 (!). > > The problem with the Elisp Intro is that it is extremely verbose and it is not really easy to find the information you're looking for. > > It also says that people who want an introduction to emacs should use the interactive tutorial so it's not really easy for people who know the basics of Emacs and of programming to find it useful before committing oneself to read a good bunch of it. I don't think we have a problem with the Introduction. It's a gentle introduction to many topics, including ELisp, and is written in a certain style that fits its purpose. The reference we have to it in the other manuals is just a reminder that it exists and could be useful for some. If people like it, fine. If they don't, they can skip it without losing anything, except perhaps some pleasure from reading a well-written document. I see no problem in the fact that narrowing is described in Chapter 29 of the ELisp manual. No one in their right minds should read that manual in its entirety in one go, top to bottom. Instead, one should look up the subject they are interested in, and then read around that. In this case, the description of point-min, reachable via index searching commands, says this right at its beginning: -- Function: point-min This function returns the minimum accessible value of point in the current buffer. This is normally 1, but if narrowing is in effect, it is the position of the start of the region that you narrowed to. (*Note Narrowing::.) And that cross-reference will get you directly to Chapter 29, without the need to read the 28 chapters preceding it. So I don't think there's any problem here we need to worry about. Thanks.