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

[Eli Zaretskii]

> From: Y. E. <yet@ego.team>
> 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 <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.

Thanks, I installed this on the master branch, and I'm closing this
bug.