From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Y. E. via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#8275: [PATCH] Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue Date: Tue, 14 Dec 2021 14:52:51 +0200 Message-ID: References: <871v25d4zl.fsf@notengoamigos.org> Reply-To: "Y. E." Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="28093"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 8275@debbugs.gnu.org, cyd@stupidchicken.com, stefan@marxist.se, monnier@iro.umontreal.ca, yet@ego.team, jearl@notengoamigos.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue Dec 14 13:53:18 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 1mx7Iz-00072r-Sj for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 14 Dec 2021 13:53:18 +0100 Original-Received: from localhost ([::1]:60790 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mx7Iy-0005VL-Ml for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 14 Dec 2021 07:53:16 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:45142) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mx7Ik-0005TL-Ha for bug-gnu-emacs@gnu.org; Tue, 14 Dec 2021 07:53:02 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:46239) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mx7Ij-0006CN-Pn for bug-gnu-emacs@gnu.org; Tue, 14 Dec 2021 07:53:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1mx7Ij-0001ZD-Il for bug-gnu-emacs@gnu.org; Tue, 14 Dec 2021 07:53:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Y. E. Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 14 Dec 2021 12:53: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-submit@debbugs.gnu.org id=B8275.16394863796015 (code B ref 8275); Tue, 14 Dec 2021 12:53:01 +0000 Original-Received: (at 8275) by debbugs.gnu.org; 14 Dec 2021 12:52:59 +0000 Original-Received: from localhost ([127.0.0.1]:57785 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mx7Ig-0001Yw-JN for submit@debbugs.gnu.org; Tue, 14 Dec 2021 07:52:59 -0500 Original-Received: from out2.migadu.com ([188.165.223.204]:26543) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mx7Id-0001Yl-1Y for 8275@debbugs.gnu.org; Tue, 14 Dec 2021 07:52:57 -0500 X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ego.team; s=key1; t=1639486373; h=from:from:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to; bh=QygtidfIYLWdUvBgkPlBjC64rEupd7RNBiVNDX2QPzg=; b=YzKGG4fNW2gKVvXyLum8VNWn+f4JLk/HA+jE16vMKoNDhVby40G7WDBeU6d3gsj8rBGzKm LXDcsZQ1M+7JmFrMd/Rylszfm0ueXI2Kc+noLiiFXRsPDn4W5Ttsmbed+xhoxti3Jfo4Y+ hmyvN7/mT0UxSp4P8Z6n2T1Oj4g/8wg= In-Reply-To: <83czm2p7dx.fsf@gnu.org> (message from Eli Zaretskii on Sun, 12 Dec 2021 10:14:18 +0200) X-Migadu-Flow: FLOW_OUT X-Migadu-Auth-User: yuga@ego.team 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" X-ACL-Warn: , Y. E. Xref: news.gmane.io gmane.emacs.bugs:222365 Archived-At: --=-=-= Content-Type: text/plain 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. --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0001-Cleanup-append-to-buffer-section-in-ELisp-Intro.patch Content-Description: Cleanup append-to-buffer section in ELisp Intro >From e1c2f3d92ae7a82ba98b7849647bb3940afa0e8c Mon Sep 17 00:00:00 2001 From: YugaEgo Date: Fri, 10 Dec 2021 23:29:51 +0200 Subject: [PATCH] Cleanup append-to-buffer section in ELisp Intro * doc/lispintro/emacs-lisp-intro.texi (append-to-buffer, Buffer Related Review, fwd-para let): Finalize shifting focus of the 'let*' introduction to the 'append-to-buffer' section. Improve wording, fix typos, remove redundant comments (Bug#8275). --- doc/lispintro/emacs-lisp-intro.texi | 147 ++++++++++------------------ 1 file changed, 49 insertions(+), 98 deletions(-) diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 9f1f10e8d6..43f1c2ddd5 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -4896,25 +4896,6 @@ Body of mark-whole-buffer is set at the end of the buffer. The whole buffer is, therefore, the region. -@c FIXME: the definition of append-to-buffer has been changed (in -@c 2010-03-30). -@c In Bug#8275, Stefan Monner writes: -@c >> Do you want to fix this, or shall I try? The problem is that -@c >> append-to-buffer now uses let* and with-current-buffer, so this might -@c >> break the flow of the text. At this point in the book, let* and -@c >> with-current-buffer are not yet introduced. -@c > -@c > Here are some thoughts: -@c > - I don't think it's of any importance that the example code be -@c > identical to the currently used code. -@c > - append-to-buffer might not be the best example since AFAICT copying -@c > text from one buffer to another is not a common operation and in most -@c > cases this is done via buffer-substring + insert (often with some -@c > processing on the string between the two) rather than with -@c > insert-buffer-substring which is a rarely used function. -@c > - yes, I think the text would benefit from some rethink to try and present -@c > with-current-buffer in preference to set-buffer, but it's not -@c > a simple fix. @node append-to-buffer @section The Definition of @code{append-to-buffer} @findex append-to-buffer @@ -4949,8 +4930,9 @@ append-to-buffer overview to, and the region that will be copied. @need 1250 -Here is the complete text of the function: +Here is a possible implementation of the function: +@c GNU Emacs 22 @smallexample @group (defun append-to-buffer (buffer start end) @@ -5017,7 +4999,9 @@ append interactive Since the @code{append-to-buffer} function will be used interactively, the function must have an @code{interactive} expression. (For a review of @code{interactive}, see @ref{Interactive, , Making a -Function Interactive}.) The expression reads as follows: +Function Interactive}.) + +The expression reads as follows: @smallexample @group @@ -5046,7 +5030,7 @@ append interactive The first argument to @code{other-buffer}, the exception, is yet another function, @code{current-buffer}. That is not going to be -returned. The second argument is the symbol for true, @code{t}. that +returned. The second argument is the symbol for true, @code{t}. That tells @code{other-buffer} that it may show visible buffers (except in this case, it will not show the current buffer, which makes sense). @@ -5082,33 +5066,6 @@ append interactive @node append-to-buffer body @subsection The Body of @code{append-to-buffer} -@ignore -in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el - -(defun append-to-buffer (buffer start end) - "Append to specified buffer the text of the region. -It is inserted into that buffer before its point. - -When calling from a program, give three arguments: -BUFFER (or buffer name), START and END. -START and END specify the portion of the current buffer to be copied." - (interactive - (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t)) - (region-beginning) (region-end))) - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore - The body of the @code{append-to-buffer} function begins with @code{let}. As we have seen before (@pxref{let, , @code{let}}), the purpose of a @@ -5127,7 +5084,7 @@ append-to-buffer body "@var{documentation}@dots{}" (interactive @dots{}) (let ((@var{variable} @var{value})) - @var{body}@dots{}) + @var{body}@dots{})) @end group @end smallexample @@ -5247,19 +5204,39 @@ append save-excursion @need 1200 @noindent +@anchor{let* introduced} +@findex let* In this function, the body of the @code{save-excursion} contains only one expression, the @code{let*} expression. You know about a -@code{let} function. The @code{let*} function is different. It has a -@samp{*} in its name. It enables Emacs to set each variable in its -varlist in sequence, one after another. +@code{let} function. The @code{let*} function is different. It +enables Emacs to set each variable in its varlist in sequence, one +after another; such that variables in the latter part of the varlist +can make use of the values to which Emacs set variables earlier in the +varlist. -Its critical feature is that variables later in the varlist can make -use of the values to which Emacs set variables earlier in the varlist. -@xref{fwd-para let, , The @code{let*} expression}. +Looking at the @code{let*} expression in @code{append-to-buffer}: -We will skip functions like @code{let*} and focus on two: the -@code{set-buffer} function and the @code{insert-buffer-substring} -function. +@smallexample +@group +(let* ((append-to (get-buffer-create buffer)) + (windows (get-buffer-window-list append-to t t)) + point) + BODY...) +@end group +@end smallexample + +@noindent +we see that @code{append-to} is bound to the value returned by the +@w{@code{(get-buffer-create buffer)}}. On the next line, +@code{append-to} is used as an argument to +@code{get-buffer-window-list}; this would not be possible with the +@code{let} expression. Note that @code{point} is automatically bound +to @code{nil}, the same way as it would be done in the @code{let} +statement. + +Now let's focus on the functions @code{set-buffer} and +@code{insert-buffer-substring} in the body of the @code{let*} +expression. @need 1250 In the old days, the @code{set-buffer} expression was simply @@ -5277,27 +5254,8 @@ append save-excursion @end smallexample @noindent -@code{append-to} is bound to @code{(get-buffer-create buffer)} earlier -on in the @code{let*} expression. That extra binding would not be -necessary except for that @code{append-to} is used later in the -varlist as an argument to @code{get-buffer-window-list}. - -@ignore -in GNU Emacs 22 - - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore +This is because @code{append-to} was bound to @code{(get-buffer-create +buffer)} earlier on in the @code{let*} expression. The @code{append-to-buffer} function definition inserts text from the buffer in which you are currently to a named buffer. It happens that @@ -5394,6 +5352,12 @@ Buffer Related Review @item mark-whole-buffer Mark the whole buffer as a region. Normally bound to @kbd{C-x h}. +@item let* +Declare a list of variables and give them an initial value; then +evaluate the rest of the expressions in the body of @code{let*}. The +values of the variables can be used to bind ensuing variables in the +list. + @item set-buffer Switch the attention of Emacs to another buffer, but do not change the window being displayed. Used when the program rather than a human is @@ -12896,25 +12860,12 @@ forward-paragraph in brief @node fwd-para let @unnumberedsubsec The @code{let*} expression -The next line of the @code{forward-paragraph} function begins a -@code{let*} expression. This is different from @code{let}. The -symbol is @code{let*} not @code{let}. - @findex let* -The @code{let*} special form is like @code{let} except that Emacs sets -each variable in sequence, one after another, and variables in the -latter part of the varlist can make use of the values to which Emacs -set variables in the earlier part of the varlist. - -@ignore -( refappend save-excursion, , code save-excursion in code append-to-buffer .) -@end ignore - -(@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.) - -In the @code{let*} expression in this function, Emacs binds a total of -seven variables: @code{opoint}, @code{fill-prefix-regexp}, -@code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and +The next line of the @code{forward-paragraph} function begins a +@code{let*} expression (@pxref{let* introduced,,@code{let*} +introduced}), in which Emacs binds a total of seven variables: +@code{opoint}, @code{fill-prefix-regexp}, @code{parstart}, +@code{parsep}, @code{sp-parstart}, @code{start}, and @code{found-start}. The variable @code{parsep} appears twice, first, to remove instances -- 2.34.1 --=-=-=--