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: Sun, 12 Dec 2021 08:50:16 +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="10880"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 8275@debbugs.gnu.org, cyd@stupidchicken.com, monnier@iro.umontreal.ca, jearl@notengoamigos.org To: Stefan Kangas Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Dec 12 07:52:59 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 1mwIjC-0002cE-Ud for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 12 Dec 2021 07:52:59 +0100 Original-Received: from localhost ([::1]:39712 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mwIjB-0006Le-4A for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 12 Dec 2021 01:52:57 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:57272) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mwIhM-0006JF-8R for bug-gnu-emacs@gnu.org; Sun, 12 Dec 2021 01:51:05 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:38989) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mwIhK-000213-2h for bug-gnu-emacs@gnu.org; Sun, 12 Dec 2021 01:51:03 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1mwIhJ-0008Ql-Td for bug-gnu-emacs@gnu.org; Sun, 12 Dec 2021 01:51: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: Sun, 12 Dec 2021 06:51: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.163929182431602 (code B ref 8275); Sun, 12 Dec 2021 06:51:01 +0000 Original-Received: (at 8275) by debbugs.gnu.org; 12 Dec 2021 06:50:24 +0000 Original-Received: from localhost ([127.0.0.1]:50535 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mwIgh-0008Dd-PH for submit@debbugs.gnu.org; Sun, 12 Dec 2021 01:50:24 -0500 Original-Received: from out2.migadu.com ([188.165.223.204]:31110) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mwIge-0008DH-Up for 8275@debbugs.gnu.org; Sun, 12 Dec 2021 01:50:22 -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=1639291818; 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=B/hh0gCi9cgOSgXGitzFZLP2oW0iJ53bEN/ys4Exuq8=; b=qFDmIvp+TiT6rKFEO9JCcKrX5yLj6y8G9RNtJ+UynPvwdzUxb9ID29Nbg/wsMoIwoNXPNL Itot1y0fEQzJU1uL63yoxnwUp1rJANJIyqIQr8j2YphNZa38Pv46fCjJn7GpteeYtlLqFb FKmA2W1bjKUwP2Ay0gsR8i0EJY5Gib4= In-Reply-To: (message from Stefan Kangas on Thu, 21 Oct 2021 12:42:54 -0700) 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:222177 Archived-At: --=-=-= Content-Type: text/plain >>> Do you want to fix this, or shall I try? The problem is that >>> append-to-buffer now uses let* and with-current-buffer, so this might >>> break the flow of the text. At this point in the book, let* and >>> with-current-buffer are not yet introduced. The current version of the 'append-to-buffer' section: - Provides explanations based on the 'append-to-buffer' function definition from GNU Emacs 22, which uses 'let*' but not 'with-current-buffer'. - Already introduces 'let*'. The suggested patch improves the flow of the text by re-organizing it to correspond better the structure of the 'append-to-buffer' function and providing more details about the 'let*' expression in it. >> Here are some thoughts: >> - I don't think it's of any importance that the example code be >> identical to the currently used code. I also tend to think it should be fine to stick to some Emacs' version (22 in this case) of the code, at least at this stage. >> - append-to-buffer might not be the best example since AFAICT copying >> text from one buffer to another is not a common operation and in most >> cases this is done via buffer-substring + insert (often with some >> processing on the string between the two) rather than with >> insert-buffer-substring which is a rarely used function. >> - yes, I think the text would benefit from some rethink to try and present >> with-current-buffer in preference to set-buffer, but it's not >> a simple fix. The suggested patch concentrates on cleanups rather than rewrites, because this may be a sufficient change (at this stage, again) and an easier one to accomplish. > I've now added the above comments to a comment in the file itself. If > anyone intends to review that section, they will find the comment and a > pointer to this bug report. The patch removes the mentioned comment since the suggested changes cover fixing (or "wontfixing") the entries of the comment. A pointer to this bug report was added to the suggested commit message. --=-=-= 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 5c9495b5db9ecf168333d589260601948e26bfd8 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..737749c625 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,7 +4930,7 @@ append-to-buffer overview to, and the region that will be copied. @need 1250 -Here is the complete text of the function: +Here is the complete text of the function in GNU Emacs 22: @smallexample @group @@ -5017,7 +4998,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 +5029,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 +5065,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 +5083,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 +5203,40 @@ append save-excursion @need 1200 @noindent +@anchor{let* introduced} +@cindex @code{let*} expression +@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 --=-=-=--