From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2 Date: Thu, 15 Jul 2021 20:07:56 +0300 Message-ID: <83mtqn5wur.fsf@gnu.org> References: <8735shrl57.fsf@tullinup.koldfront.dk> <83v95c7v3v.fsf@gnu.org> <87bl74evd7.fsf@gnus.org> <87bl74ry2z.fsf@gnus.org> <831r7z7jgl.fsf@gnu.org> <83tukv60a2.fsf@gnu.org> <30917EA3-D0B2-40E0-AE09-0825ADB95591@traduction-libre.org> <871r7zilp0.fsf@gnus.org> <83o8b35xbe.fsf@gnu.org> <87r1fzh5or.fsf@gnus.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="2904"; mail-complaints-to="usenet@ciao.gmane.io" Cc: lists@traduction-libre.org, asjo@koldfront.dk, stefan@marxist.se, monnier@iro.umontreal.ca, emacs-devel@gnu.org To: Lars Ingebrigtsen Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Jul 15 19:08:49 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 1m44qv-0000Wg-Jt for ged-emacs-devel@m.gmane-mx.org; Thu, 15 Jul 2021 19:08:49 +0200 Original-Received: from localhost ([::1]:36858 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m44qu-0001Bg-36 for ged-emacs-devel@m.gmane-mx.org; Thu, 15 Jul 2021 13:08:48 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:60046) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m44qP-0000WZ-Nr for emacs-devel@gnu.org; Thu, 15 Jul 2021 13:08:17 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:57706) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m44qM-00044u-20; Thu, 15 Jul 2021 13:08:14 -0400 Original-Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:3112 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m44qL-0005cx-Iv; Thu, 15 Jul 2021 13:08:13 -0400 In-Reply-To: <87r1fzh5or.fsf@gnus.org> (message from Lars Ingebrigtsen on Thu, 15 Jul 2021 19:01:40 +0200) 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:271270 Archived-At: > From: Lars Ingebrigtsen > Cc: lists@traduction-libre.org, asjo@koldfront.dk, stefan@marxist.se, > monnier@iro.umontreal.ca, emacs-devel@gnu.org > Date: Thu, 15 Jul 2021 19:01:40 +0200 > > Eli Zaretskii writes: > > > The new sentence interrupts the continuity, and now "Probably > > introduced at ..." is missing the context and sounds like bad English. > > > > I think it would be better to move the reference to other functions to > > the end of the *Help* buffer text. After all, it's a kind-of "See > > also", which is normally found at the end. > > That's true, but the "probably introduced" bit is the least important > thing in the *Help* buffer, so emphasising it in the current way is > unfortunate. > > I think we should move it to the end of the buffer, or hide it by > default (with some button to reveal this and other less-than-vital > stuff). That's orthogonal. It is unreasonable to stick the reference to other functions before we describe the current function. It distracts and means the users need to read more before they get to the "meat" for which they invoked the help. Let's not go overboard with these helpers: they are just helpers, not the main part of the docs. "See also" is at the end for a reason.