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

[Y . E .]

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.

0001-Cleanup-append-to-buffer-section-in-ELisp-Intro.patch
Description: Cleanup append-to-buffer section in ELisp Intro