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

[Eli Zaretskii]

> Cc: 8275@debbugs.gnu.org, cyd@stupidchicken.com, monnier@iro.umontreal.ca,
>  jearl@notengoamigos.org
> Date: Sun, 12 Dec 2021 08:50:16 +0200
> From:  Y. E. via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> 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.

Thanks, please see some comments below.

> -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"?  The goal of this manual is not to
show actual code used by Emacs, it's to teach programming in Emacs
Lisp.  So whether this is, or was, an actual implementation is
immaterial from the didactic POV.

> -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.

> +@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.

>  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}.

I don't understand the rationale for this change.  It looks like
simple rewording of the original, with different partition into
sentences.  I see nothing wrong with the original text, so why did you
need to change it?

> -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.

So, unlike the original author, you consider it important to explain
the let* part here?  Why is 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}.

This seems to move the description of let* to an earlier part of the
manual.  Once again, I ask: what's the rationale for the change in the
order?