From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Adding examples in the doc (was: Some ideas with Emacs) Date: Fri, 29 Nov 2019 14:13:25 -0500 Message-ID: References: <837e3iq0ks.fsf@gnu.org> <87h82my0fm.fsf@gmx.de> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="155925"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) Cc: Eli Zaretskii , Stefan Kangas , Anonymous , Emacs developers To: Michael Albinus Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Nov 29 20:23:57 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 1ialrt-000eKj-SA for ged-emacs-devel@m.gmane.org; Fri, 29 Nov 2019 20:23:54 +0100 Original-Received: from localhost ([::1]:34726 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ialrq-0008MJ-JY for ged-emacs-devel@m.gmane.org; Fri, 29 Nov 2019 14:23:50 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:34427) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iali3-0004QB-SK for emacs-devel@gnu.org; Fri, 29 Nov 2019 14:13:44 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ialhx-00062A-LW for emacs-devel@gnu.org; Fri, 29 Nov 2019 14:13:41 -0500 Original-Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:24863) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1ialhs-0005dg-SN; Fri, 29 Nov 2019 14:13:33 -0500 Original-Received: from pmg1.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id C5DE41009B0; Fri, 29 Nov 2019 14:13:29 -0500 (EST) Original-Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id 280F51003EC; Fri, 29 Nov 2019 14:13:28 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1575054808; bh=R2voxaPGddZJr7gpyBhqOQAEfJ/OdH8dUIKuD1WVzMU=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=mCyf0Aebs0PYo6yjEdHT8O8dKwwQVgyT82uRjMhLxwgExI65iTztO0eKsrOdhHaav 1AtdPtFAJWpGsCWdT7vvP+nDJxi187NgIwyaxoozBMr2xpxvtqL9xEd02GhTwNKXcp IU2yo8Edn56LbeloQEmPtwxB9gakApeoEsEoytO3UGTHqUfWMlPK3CtoDUHVuYbLye KidwSQy240nhAhlAZnshEtnfDuJP9baxBbJtoXDCXdRx0kLpOQXEimojvPjXqMRb8U o6MDU5NHh5YkOTXjC2x1ftoBd4TqaT7KR3wZrbPBRt5b9dsoA5P2qMJ1ypbwmluf48 VWSewmM+BRPcg== Original-Received: from pastel (unknown [45.72.134.213]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id C4789121282; Fri, 29 Nov 2019 14:13:27 -0500 (EST) In-Reply-To: <87h82my0fm.fsf@gmx.de> (Michael Albinus's message of "Fri, 29 Nov 2019 19:58:21 +0100") X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 132.204.25.50 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:242885 Archived-At: >> AFACT, currently we have some examples in the Elisp manual and very >> few examples in docstrings. >> It might be a good idea to encourage the addition of examples either in >> docstrings or in the Elisp manual (or both). > Personally, I don't like docstring to be too verbose. I tend to agree. Of course part of it is that a verbose docstring is an indication that the function is complex to use, but there's also simply the impact on the visual distance between the function header and the code. Another issue w.r.t examples is that editing Elisp code within docstrings is a PITA (you don't get the usual completion/indentation/... plus you have to be careful with escaping ' and friends so they don't get "shaped"). Also, docstrings have no formal structure and usually contain text, so if we want to add examples in docstrings, I would prefer we first design a structure to clearly distinguish text from code so we can render it more elegantly. Maybe examples should simply live *outside* of the function definition, e.g. with (defexamples ...) This might also have the benefit of being able to associate an example with several functions (when the example shows how to combine calls to various functions to get a particular result). > Usually, when a function is documented with both docstrings and > a manual, I prefer to put the examples in the manual. I find code in texi files to be less convenient to edit/use. Stefan