From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Marcin Borkowski Newsgroups: gmane.emacs.devel Subject: Wording of the Elisp manuals (was: forward-comment and syntax-ppss) Date: Sat, 17 Dec 2016 05:50:56 +0100 Message-ID: <8737hn40r3.fsf@mbork.pl> 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> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1481950306 10311 195.159.176.226 (17 Dec 2016 04:51:46 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 17 Dec 2016 04:51:46 +0000 (UTC) User-Agent: mu4e 0.9.17; emacs 26.0.50.1 Cc: Drew Adams , emacs-devel@gnu.org To: =?utf-8?Q?Cl=C3=A9ment?= Pit--Claudel Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Dec 17 05:51:40 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 1cI6yC-0001ag-8b for ged-emacs-devel@m.gmane.org; Sat, 17 Dec 2016 05:51:40 +0100 Original-Received: from localhost ([::1]:35316 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cI6yG-0000we-E9 for ged-emacs-devel@m.gmane.org; Fri, 16 Dec 2016 23:51:44 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54149) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cI6xc-0000rX-LJ for emacs-devel@gnu.org; Fri, 16 Dec 2016 23:51:05 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cI6xZ-0006vD-Ig for emacs-devel@gnu.org; Fri, 16 Dec 2016 23:51:04 -0500 Original-Received: from mail.mojserwer.eu ([195.110.48.8]:56375) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cI6xZ-0006tk-9L for emacs-devel@gnu.org; Fri, 16 Dec 2016 23:51:01 -0500 Original-Received: from localhost (localhost [127.0.0.1]) by mail.mojserwer.eu (Postfix) with ESMTP id 0BA02E62D5; Sat, 17 Dec 2016 05:50:33 +0100 (CET) X-Virus-Scanned: Debian amavisd-new at mail.mojserwer.eu Original-Received: from mail.mojserwer.eu ([127.0.0.1]) by localhost (mail.mojserwer.eu [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id RTAO2DOExN_6; Sat, 17 Dec 2016 05:50:30 +0100 (CET) Original-Received: from localhost (static-dwadziewiec-jedenpiec7.echostar.pl [109.232.29.157]) by mail.mojserwer.eu (Postfix) with ESMTPSA id 31195E6264; Sat, 17 Dec 2016 05:50:30 +0100 (CET) In-reply-to: X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x [fuzzy] X-Received-From: 195.110.48.8 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:210570 Archived-At: On 2016-12-17, at 03:39, Cl=C3=A9ment Pit--Claudel wrote: > On 2016-12-16 18:16, Drew Adams wrote: >>>> "Narrowing breaks proof-general". Really? Narrowing did that? >>> >>> I mean that narrowing a buffer causes Proof General to misbehave. Th= at's >>> obviously a Proof General bug; I only intended it as an example of a >>> facility for which narrowing made things harder. >>=20 >> OK. But that's like saying that variables break program `xyz' >> because variables make things harder. Yes, things that change >> state make things harder, and that includes narrowing. If this >> were Haskell then things wouldn't be so hard... > > Yup. I think a significant part of the issue is just that some devs fo= rget that using point-min may require widening. I didn't know about for = a while, even after I started programming in ELisp. True. I wanted to say "Hey, that means that narrowing should be mentioned in the Emacs Lisp Intro". But I checked, and it is, and fairly early for that matter. I wonder how many things like that are waiting for the brave developer coming from the background of some saner language/environment. ;-) (In case someone misses it: this is of course tongue-in-cheek, I /do/ like Emacs and Elisp. Each language has its quirks; the point is, E\(macs\|lisp\) have /lots/ of them because (1) history and (2) Elisp is a text editor language, not a general purpose programming environment) Here is, I suppose, a minor bug. The Elisp reference says: ,---- | This manual attempts to be a full description of Emacs Lisp. For | a beginner=E2=80=99s introduction to Emacs Lisp, see =E2=80=98An Introd= uction to Emacs | Lisp Programming=E2=80=99, by Bob Chassell, also published by the Free | Software Foundation. This manual presumes considerable familiarity | with the use of Emacs for editing; see =E2=80=98The GNU Emacs Manual=E2= =80=99 for this | basic information. `---- OTOH, Elisp Intro says: ,---- | Perhaps you want to understand programming; perhaps you want to | extend Emacs; or perhaps you want to become a programmer. This | introduction to Emacs Lisp is designed to get you started: to guide you | in learning the fundamentals of programming, and more importantly, to | show you how you can teach yourself to go further. `---- I am pretty sure that any experienced programmer who did use Emacs for a while, after reading the above paragraph, will skip Elisp Intro entirely ("They want to teach me conditionals and loops? I know that already!") 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 (!). Just my 2 cents. Best, --=20 Marcin Borkowski