From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Tim Cross 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 01:02:05 +1000 Message-ID: <87bl73r4p1.fsf@gmail.com> References: <8735shrl57.fsf@tullinup.koldfront.dk> <83v95c7v3v.fsf@gnu.org> <87bl74evd7.fsf@gnus.org> <87bl74ry2z.fsf@gnus.org> <831r7z7jgl.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="21143"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: mu4e 1.5.13; emacs 28.0.50 To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Jul 15 17:14:04 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 1m433s-0005Im-7D for ged-emacs-devel@m.gmane-mx.org; Thu, 15 Jul 2021 17:14:04 +0200 Original-Received: from localhost ([::1]:55982 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m433r-00059P-8d for ged-emacs-devel@m.gmane-mx.org; Thu, 15 Jul 2021 11:14:03 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:34960) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m432y-0003qS-2m for emacs-devel@gnu.org; Thu, 15 Jul 2021 11:13:08 -0400 Original-Received: from mail-pg1-x52c.google.com ([2607:f8b0:4864:20::52c]:36460) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1m432w-00010W-KX for emacs-devel@gnu.org; Thu, 15 Jul 2021 11:13:07 -0400 Original-Received: by mail-pg1-x52c.google.com with SMTP id s18so6694980pgq.3 for ; Thu, 15 Jul 2021 08:13:03 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=references:user-agent:from:to:subject:date:in-reply-to:message-id :mime-version:content-transfer-encoding; bh=ntam1tNnnazvEM0iLr00NMNfqXVRWTpn/nD09Vq5Z2A=; b=DCA5xko7Bv9Jxs+KsP90TSo+Z+ed24+C3zoJSwgkW4BGhmdB1pjQZb2dg7CImAb6Ic Lqy0HPmiQAFx+vYx4qRrLKogw3lV8ZexgX8CtxXyk3khTfKTRTbQ6XIzKWC+3SPSuuhG BCK8D4QnQ2t/toJs1WuM8m+oVQ+YIQFMz+puHAyOmtzBqdXPpWKc6Dug2prCEHfLAFH5 2nRPouYYR3mkUAy3FBGz0azJvaYbRJghs998esMH48nwu+0jnVJW4QMclDGhpX80sQSZ IbnuRE7O4XtrOzb3rUQj1zHkfDVFDEvDq9Akh34i15vUFBS1MQkv0o7ry3boUH2yZmnc Vtsg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:references:user-agent:from:to:subject:date :in-reply-to:message-id:mime-version:content-transfer-encoding; bh=ntam1tNnnazvEM0iLr00NMNfqXVRWTpn/nD09Vq5Z2A=; b=S/ndcHW+YORi/Y03KLYbEYrmANOLN7A7ui6JDLioSZTM/rE4qGLOhAaPt4j/Eo2PxG 5fp4YEqerSbYFEuEJKgzTK8Dlr5JQzKtjlBz8pw1I8bAK/ysDEmtkUNJBZKJH3J0IIzr 9zOmkIeBVKwc21u0uGr1yX3i+MGzYkT1ClzcWCvE7JlrgfX/9GU7hKq/2HTbC/1WGzhc ZF3YgT2HSMnRgqjJmxldraKy1BkZWpoIUJZskBVa7nb2T5AnhFPWTC35XtQuT5g8lLuV qqFHtNzmw0G6xTj0toeZL1jIDjghglJe+mZOlHNsY09yvkyKkxnxIsghmkrKpC7qO77f cGoA== X-Gm-Message-State: AOAM530fhQD0r0ukoYx6YC7rM4oFsOllrf7CUvLL86CCOUQbT7e51BHa 72LmMw0+rLXAoa28hLO7/ZIJB3C8QXE= X-Google-Smtp-Source: ABdhPJwTqATddBB9zf3PKUJLEbSIefyN9rPYS6OgQqXovc7Bi/020ohPA03cq5wYeJ4qDu+DHz4jcA== X-Received: by 2002:a63:b60:: with SMTP id a32mr5185310pgl.29.1626361982488; Thu, 15 Jul 2021 08:13:02 -0700 (PDT) Original-Received: from tim-desktop (106-69-147-133.dyn.iinet.net.au. [106.69.147.133]) by smtp.gmail.com with ESMTPSA id o91sm9597967pjo.15.2021.07.15.08.13.00 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 15 Jul 2021 08:13:01 -0700 (PDT) In-reply-to: <831r7z7jgl.fsf@gnu.org> Received-SPF: pass client-ip=2607:f8b0:4864:20::52c; envelope-from=theophilusx@gmail.com; helo=mail-pg1-x52c.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, 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:271250 Archived-At: Eli Zaretskii writes: >> From: Stefan Kangas >> Date: Thu, 15 Jul 2021 13:39:54 +0200 >> Cc: Eli Zaretskii , Adam Sj=C3=B8gren ,= =20 >> Emacs developers >>=20 >> In general, I think we should include more examples in our >> documentation. shortdoc.el is a step forward here, and it would be >> even better if you could see those examples when you pull up the >> docstring of a function. > > IMO, examples are for the manual, not for the doc strings. If some > parts of our manuals could benefit from more examples, patches for > that would be welcome. I tend to agree. The doc strings should be short and concise and link to the manual for more detailed explanation and examples. Things like eldoc and tooltips can become annoying or overly distracting if they have lots of text. I do understand how the doc strings for car and cdr can seem less helpful, especially as they are somewhat recursive i.e. I don't know what the function 'car' does - docstring tells me it returns the car of a list, but I still don't know what car is. However, to really understand car (or cdr), you really need a bit more understanding of lists, cons cells etc. So having a somewhat terse doc string which includes a link to the manual may be a good thing as it will encourage the user to look at the manual and possibly get some of the additional information (plus caar, caadr, cddr etc). --=20 Tim Cross