From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Some ideas with Emacs Date: Fri, 29 Nov 2019 16:13:57 +0200 Message-ID: <834kympy6y.fsf@gnu.org> References: <837e3iq0ks.fsf@gnu.org> Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="79087"; mail-complaints-to="usenet@blaine.gmane.org" Cc: c4droid@foxmail.com, emacs-devel@gnu.org To: Stefan Kangas Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Nov 29 15:51:40 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iahcP-000KQD-SK for ged-emacs-devel@m.gmane.org; Fri, 29 Nov 2019 15:51:38 +0100 Original-Received: from localhost ([::1]:59890 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iahcN-0003e1-Ni for ged-emacs-devel@m.gmane.org; Fri, 29 Nov 2019 09:51:36 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:58639) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iah1x-0002g8-MV for emacs-devel@gnu.org; Fri, 29 Nov 2019 09:14:02 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:45322) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1iah1n-0003Ia-RL; Fri, 29 Nov 2019 09:13:47 -0500 Original-Received: from [176.228.60.248] (port=3964 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1iah1l-0004iN-6j; Fri, 29 Nov 2019 09:13:45 -0500 In-reply-to: (message from Stefan Kangas on Fri, 29 Nov 2019 14:34:44 +0100) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 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:242875 Archived-At: > From: Stefan Kangas > Date: Fri, 29 Nov 2019 14:34:44 +0100 > Cc: Anonymous , Emacs developers > > Eli Zaretskii writes: > > > I think if we want to have an ELisp tutorial, it should be a separate > > manual. The current ELisp manual is a reference manual, and written > > as such. > > I fail to see why a reference manual can't also include examples. I was talking about a tutorial, not about examples. We already have examples in the ELisp manual, although it isn't feasible to have an example for each possible use case. We could add more examples where the description is not self-explanatory enough, but adding too much of them would be infeasible, I think, due to size considerations. We will have to consider that on a case by case basis. > I've had to search the web to understand how to use things before, > even after having carefully read the relevant parts of the elisp > manual and the doc string. A better strategy is to search the Emacs tree, IME. > To be clear, I'm not suggesting that we should mandate that we should > include examples. But I'd suggest to optionally add them where it > makes sense, and possibly then only in the info version of the manual > (since we lack space in the print edition). We already have examples where we think it's useful.