From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Jean-Christophe Helary Newsgroups: gmane.emacs.devel Subject: Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2 Date: Fri, 16 Jul 2021 11:08:42 +0900 Message-ID: References: <8735shrl57.fsf@tullinup.koldfront.dk> <83v95c7v3v.fsf@gnu.org> <87bl74evd7.fsf@gnus.org> <87bl74ry2z.fsf@gnus.org> <831r7z7jgl.fsf@gnu.org> <87r1fzinu1.fsf@gnus.org> <83sg0f603p.fsf@gnu.org> Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.100.0.2.22\)) Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="1662"; mail-complaints-to="usenet@ciao.gmane.io" Cc: asjo@koldfront.dk, Eli Zaretskii , stefan@marxist.se, Lars Ingebrigtsen , emacs-devel@gnu.org To: Stefan Monnier Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Jul 16 04:09:51 2021 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1m4DIT-0000DV-T1 for ged-emacs-devel@m.gmane-mx.org; Fri, 16 Jul 2021 04:09:49 +0200 Original-Received: from localhost ([::1]:51570 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m4DIS-0001WT-IM for ged-emacs-devel@m.gmane-mx.org; Thu, 15 Jul 2021 22:09:48 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:46916) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m4DHi-0000qB-AZ for emacs-devel@gnu.org; Thu, 15 Jul 2021 22:09:02 -0400 Original-Received: from relay4-d.mail.gandi.net ([217.70.183.196]:36953) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m4DHf-0007r6-5L; Thu, 15 Jul 2021 22:09:01 -0400 Original-Received: (Authenticated sender: lists@traduction-libre.org) by relay4-d.mail.gandi.net (Postfix) with ESMTPSA id 55201E0004; Fri, 16 Jul 2021 02:08:49 +0000 (UTC) In-Reply-To: X-Mailer: Apple Mail (2.3654.100.0.2.22) Received-SPF: pass client-ip=217.70.183.196; envelope-from=lists@traduction-libre.org; helo=relay4-d.mail.gandi.net X-Spam_score_int: -25 X-Spam_score: -2.6 X-Spam_bar: -- X-Spam_report: (-2.6 / 5.0 requ) BAYES_00=-1.9, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action 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-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:271282 Archived-At: > On Jul 16, 2021, at 9:22, Stefan Monnier wrote: > >> The danger of going overboard is exactly what bothers me. Which is >> why I think examples in doc strings should be used in exceptional >> cases, where they are absolutely necessary. Not as a "why not?" >> addition. > > I don't think docstring should come with examples. Examples should be > provided separately for use by shortdoc.el and friends. Do you have a list of "friends"? What is the way to add examples to the shordoc display ? > Then `C-h f` can also show those examples, but it can place them > elsewhere (e.g. hidden by default with a button to show them or > something like that). So, that mechanism does not exist yet, correct ? -- Jean-Christophe Helary @brandelune https://mac4translators.blogspot.com https://sr.ht/~brandelune/omegat-as-a-book/