bug#8275: [PATCH] Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue

[Y. E. via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

[-- Attachment #1: Type: text/plain, Size: 3169 bytes --]

Eli Zaretskii <eliz@gnu.org> 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.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Cleanup append-to-buffer section in ELisp Intro --]
[-- Type: text/x-patch, Size: 9726 bytes --]

From e1c2f3d92ae7a82ba98b7849647bb3940afa0e8c Mon Sep 17 00:00:00 2001
From: YugaEgo <yet@ego.team>
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 <monnier@iro.umontreal.ca> 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