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.bugs Subject: bug#8275: [PATCH] Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue Date: Sat, 18 Dec 2021 16:27:40 +0200 Message-ID: <83zgoy9eeb.fsf@gnu.org> References: Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="34866"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 8275-done@debbugs.gnu.org, cyd@stupidchicken.com, stefan@marxist.se, monnier@iro.umontreal.ca, jearl@notengoamigos.org To: Y. E. Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Dec 18 15:29:12 2021 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1myahz-0008mZ-1f for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 18 Dec 2021 15:29:11 +0100 Original-Received: from localhost ([::1]:55424 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1myahx-0005d3-2q for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 18 Dec 2021 09:29:09 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:38530) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1myahq-0005cn-CU for bug-gnu-emacs@gnu.org; Sat, 18 Dec 2021 09:29:02 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:58232) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1myahq-0002Rv-3t for bug-gnu-emacs@gnu.org; Sat, 18 Dec 2021 09:29:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1myahp-0000dj-Su for bug-gnu-emacs@gnu.org; Sat, 18 Dec 2021 09:29:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 18 Dec 2021 14:29:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 8275 X-GNU-PR-Package: emacs Original-Received: via spool by 8275-done@debbugs.gnu.org id=D8275.16398376852395 (code D ref 8275); Sat, 18 Dec 2021 14:29:01 +0000 Original-Received: (at 8275-done) by debbugs.gnu.org; 18 Dec 2021 14:28:05 +0000 Original-Received: from localhost ([127.0.0.1]:41544 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1myagq-0000cM-B9 for submit@debbugs.gnu.org; Sat, 18 Dec 2021 09:28:05 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:37616) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1myagn-0000c9-Rp for 8275-done@debbugs.gnu.org; Sat, 18 Dec 2021 09:27:58 -0500 Original-Received: from [2001:470:142:3::e] (port=52654 helo=fencepost.gnu.org) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1myagh-0002Ng-Qk; Sat, 18 Dec 2021 09:27:51 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=IDHNpBu/FjqaLpeYahpqzdAaNxhK6jMEhrKAvjkLy74=; b=PUpfB1VTxrWj LmVJMkdEzg/wAS0ELigsb9cUkQT76TR5kkWLxOYWonFCArkCm3EgcwXO1U8qjNLEujxnQQymimqqY p8CtMuGQxziqS/HhxbePv/Cs4ibusMO9iO2KRIEHrZsIhMGiBmrpz4QiuL5X8yVqNX3f6uE4DEgpH ywM9+v7745KSPBOLiz4VUWooZCh5vp5U3S+3xDNXHZQenjii/TFZVGu9v4lw1O2Xe4Qgth4WuU0Vb TUi96q9QfmZihNwkUOyPwDrJjDCeUDHfN7oC1BY5G9/rsuLLHQ5veXoCV2Npz9RlpW0HjtSeoO20b V/e429wDUIJs6Sl5uzQzAA==; Original-Received: from [87.69.77.57] (port=4938 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 1myagh-0006r7-Io; Sat, 18 Dec 2021 09:27:51 -0500 In-Reply-To: (message from Y. E. on Tue, 14 Dec 2021 14:52:51 +0200) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:222611 Archived-At: > From: Y. E. > Cc: yet@ego.team, stefan@marxist.se, 8275@debbugs.gnu.org, > cyd@stupidchicken.com, > monnier@iro.umontreal.ca, jearl@notengoamigos.org > Date: Tue, 14 Dec 2021 14:52:51 +0200 > > Eli Zaretskii writes: > >> -Here is the complete text of the function: > >> +Here is the complete text of the function in GNU Emacs 22: > > > > Instead of alluding to a past version of Emacs, how about saying > > something more vague, like "a variant of the function", or "a possible > > implementation of the function"? > > Done. > > Note that the style of the patch was based on the existing texts. Should > I create a bug report (maybe with a patch) asking to replace other 'In > GNU Emacs 22' phrases used in the same context? > > ________________ > > > The goal of this manual is not to > > show actual code used by Emacs, it's to teach programming in Emacs > > Lisp. > If this is true, then the manual has to be re-written very deeply. > Currently, the manual promises (and often does) to show actual code > usage. Citing `(eintr) On Reading this Text': > > > Much of this introduction is dedicated to walkthroughs or guided > > tours of code used in GNU Emacs. These tours are designed for two > > purposes: first, to give you familiarity with real, working code (code > > you use every day); and, second, to give you familiarity with the way > > Emacs works. > > [I personally prefer what the manual promises (mostly does) now.] > > ________________ > > >> -returned. The second argument is the symbol for true, @code{t}. that > >> +returned. The second argument is the symbol for true: @code{t}, that > > > > I think the correct fix here is to capitalize "That" (and add a > > space), so that it's the next separate sentence. > > Done. > > ________________ > > > >> +@anchor{let* introduced} > >> +@cindex @code{let*} expression > >> +@findex let* > > > > It isn't useful to have several index entries that begin with the same > > text and point to the same place. This manual has just one index, > > where all the index entries are placed together. So I suggest > > removing one of these two index entries. > > Thanks, removed. > > ________________ > > > This seems to move the description of let* to an earlier part of the > > manual. > The description of 'let*' is *already* in the earlier part of the > manual. (The patch is based on the current version.) > > > Once again, I ask: what's the rationale for the change in the > > order? > > The following is the order of the occurrences of 'let*' in the manual: > > 1. 'let*' is defined in `(eintr) append-to-buffer overview', > > 2. Then it's mentioned in the code and text of the `(eintr) kill-append > function', > > 3. Then it's mentioned in the intro text of `(eintr) forward-paragraph', > > 4. Then it's defined for the second time in `(eintr) fwd-para let', > using the same words and phrases as in the 1st occurrence. > > Therefore, it seems to be more comprehensible for a reader to be > introduced to 'let*' (in a more clear manner than it is now) on the 1st > of the listed occurrences, rather than on the 4th. > > > Anyway, if there's a strong opinion 'let*' has to be introduced in > `(eintr) fwd-para let' and not earlier, then I'd suggest scratching out > the mentions of 'let*' from all the earlier parts altogether (or limit > them to a bare minimum and reference to the definition). > > I'm fine with either (or any other) as long as the text of the manual > reads smoothly and doesn't contain unnecessary duplications. Thanks, I installed this on the master branch, and I'm closing this bug.