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

[Marcin Borkowski]

On 2016-12-17, at 03:39, Clément Pit--Claudel <address@hidden> wrote:

> On 2016-12-16 18:16, Drew Adams wrote:
>>>> "Narrowing breaks proof-general".  Really?  Narrowing did that?
>>>
>>> I mean that narrowing a buffer causes Proof General to misbehave.  That's
>>> obviously a Proof General bug; I only intended it as an example of a
>>> facility for which narrowing made things harder.
>> 
>> OK.  But that's like saying that variables break program `xyz'
>> because variables make things harder.  Yes, things that change
>> state make things harder, and that includes narrowing.  If this
>> were Haskell then things wouldn't be so hard...
>
> Yup.  I think a significant part of the issue is just that some devs forget 
> that using point-min may require widening.  I didn't know about for a while, 
> even after I started programming in ELisp.

True.  I wanted to say "Hey, that means that narrowing should be
mentioned in the Emacs Lisp Intro".  But I checked, and it is, and
fairly early for that matter.

I wonder how many things like that are waiting for the brave developer
coming from the background of some saner language/environment. ;-) (In
case someone misses it: this is of course tongue-in-cheek, I /do/ like
Emacs and Elisp.  Each language has its quirks; the point is,
E\(macs\|lisp\) have /lots/ of them because (1) history and (2) Elisp is
a text editor language, not a general purpose programming environment)

Here is, I suppose, a minor bug.  The Elisp reference says:

,----
| This manual attempts to be a full description of Emacs Lisp.  For
| a beginner’s introduction to Emacs Lisp, see ‘An Introduction to Emacs
| Lisp Programming’, by Bob Chassell, also published by the Free
| Software Foundation.  This manual presumes considerable familiarity
| with the use of Emacs for editing; see ‘The GNU Emacs Manual’ for this
| basic information.
`----

OTOH, Elisp Intro says:

,----
| Perhaps you want to understand programming; perhaps you want to
| extend Emacs; or perhaps you want to become a programmer.  This
| introduction to Emacs Lisp is designed to get you started: to guide you
| in learning the fundamentals of programming, and more importantly, to
| show you how you can teach yourself to go further.
`----

I am pretty sure that any experienced programmer who did use Emacs for
a while, after reading the above paragraph, will skip Elisp Intro
entirely ("They want to teach me conditionals and loops?  I know that
already!")

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 (!).

Just my 2 cents.

Best,

-- 
Marcin Borkowski