Re: Wording of the Elisp manuals (was: forward-comment and syntax-ppss)

[Eli Zaretskii <eliz@gnu.org>]

> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
> Date: Tue, 20 Dec 2016 19:52:28 +0900
> 
> 
> > On 2016 Dec 17, at 13:50, Marcin Borkowski <mbork@mbork.pl> wrote:
> > 
> > Wouldn't it be a good idea to state clearly somewhere that ELisp Intro
> > is not only about introduction to programming, but also about
> > introdcution to Emacs as the Elisp environment?  Narrowing is first
> > mentioned in Chapter 9 of the Elisp Reference and only described in
> > detail in Chapter 29 (!).
> 
> The problem with the Elisp Intro is that it is extremely verbose and it is not really easy to find the information you're looking for.
> 
> It also says that people who want an introduction to emacs should use the interactive tutorial so it's not really easy for people who know the basics of Emacs and of programming to find it useful before committing oneself to read a good bunch of it.

I don't think we have a problem with the Introduction.  It's a gentle
introduction to many topics, including ELisp, and is written in a
certain style that fits its purpose.  The reference we have to it in
the other manuals is just a reminder that it exists and could be
useful for some.  If people like it, fine.  If they don't, they can
skip it without losing anything, except perhaps some pleasure from
reading a well-written document.

I see no problem in the fact that narrowing is described in Chapter 29
of the ELisp manual.  No one in their right minds should read that
manual in its entirety in one go, top to bottom.  Instead, one should
look up the subject they are interested in, and then read around
that.  In this case, the description of point-min, reachable via index
searching commands, says this right at its beginning:

   -- Function: point-min
       This function returns the minimum accessible value of point in the
       current buffer.  This is normally 1, but if narrowing is in effect,
       it is the position of the start of the region that you narrowed to.
       (*Note Narrowing::.)

And that cross-reference will get you directly to Chapter 29, without
the need to read the 28 chapters preceding it.

So I don't think there's any problem here we need to worry about.

Thanks.