From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.devel Subject: Re: Some ideas with Emacs Date: Fri, 29 Nov 2019 14:34:44 +0100 Message-ID: References: <837e3iq0ks.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="50774"; mail-complaints-to="usenet@blaine.gmane.org" Cc: Anonymous , Emacs developers To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Nov 29 14:40:54 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 1iagVw-000D5V-0y for ged-emacs-devel@m.gmane.org; Fri, 29 Nov 2019 14:40:52 +0100 Original-Received: from localhost ([::1]:59214 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iagVt-0004gS-Ka for ged-emacs-devel@m.gmane.org; Fri, 29 Nov 2019 08:40:49 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:39666) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iagQg-0000iF-Vm for emacs-devel@gnu.org; Fri, 29 Nov 2019 08:35:28 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iagQS-0000K9-FX for emacs-devel@gnu.org; Fri, 29 Nov 2019 08:35:18 -0500 Original-Received: from mail-pj1-f53.google.com ([209.85.216.53]:44641) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iagQE-000073-NU; Fri, 29 Nov 2019 08:34:59 -0500 Original-Received: by mail-pj1-f53.google.com with SMTP id w8so13282938pjh.11; Fri, 29 Nov 2019 05:34:56 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=/T471HPZy5yKNsBaxofQuX2ashm+kZAs88HQCYehZpw=; b=oE1p0b6AvWggdbXP87QS07kRzR7FamGfsa2Wnoon9muwIUVERUtrqfOaOxt5S49E4n Wx2cwblRyzFeaZEyi7R/DZbgb7ZOn+dGslS9gVP/ht8W20ONnrsDDsYwzoiGsixMWixh zZYSEHQ+2lATrfty4KefWTi53DXoK2705uHu8Haqz1QbL76X35YHAMgupV3M1ZvlMBNx 1d48EisTKp1D44pPxDm2FCijyS1jt2yoPr8iv7PE5yRtXPeC8HSQSk8QWrhxA2+GMjm0 OSGq2JjkPOOLTvnxz7j2Poy+VurSWyKnATOXING45gyFyRE23fsa+lazRynEl6teOQpQ du1A== X-Gm-Message-State: APjAAAX/xdp9Rn4eUcVthKzbOI8FSd/CBTEffOLOtx16EU1cwYVC8H67 1J8XBkk2Q/AtuaD7Han36okqEhA/doVbbKdnpOtyxHHT X-Google-Smtp-Source: APXvYqwglXXCuApgNb2TIlFQ+qiEMXs4meXIs2GvmbuZcxZBb9Dmr/t4nbL1smQc4/V3lKzJVEhyXOko5HWhnMByLY4= X-Received: by 2002:a17:90a:a40f:: with SMTP id y15mr19135725pjp.106.1575034495618; Fri, 29 Nov 2019 05:34:55 -0800 (PST) In-Reply-To: <837e3iq0ks.fsf@gnu.org> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 209.85.216.53 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:242870 Archived-At: 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'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. An example says a thousand words, as the saying goes... I think the Python documentation is very good in this regard. Here is one example: https://docs.python.org/3/library/stdtypes.html#mapping-types-dict 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). Best regards, Stefan Kangas