bug#64692: Better descriptions of Cons Cells and Dotted Notation with real-life syntax

[Drew Adams]

> > Whereas the Emacs
> > Lisp Reference Manual isn't designed as a tutorial with explanations,
> > the "Introduction to Programming in Emacs Lisp" simply refers to the
> > "Emacs Lisp Reference Manual" for understanding Cons Cells and Dotted
> > Notation.
> >
> > This means that the "Introduction to Programming in Emacs Lisp" would
> > benefit from some real-life list syntax. Currently I find it short
> > and far from real-life.
> 
> The Introduction manual has a node "List diagrammed", to which you
> will get if you type "i cons cell RET", which describes that, with
> pictures.

That node doesn't explain dot notation.
It does have a link to the Elisp manual for
that.  But it doesn't even show an example
of dot notation.  A reader may well wonder
why there's a link for "Dotted Pair Notation".

It would be good to show Lisp notation for
some of the cons-cell diagrams it presents.
It does show that for (violet buttercup).
It would do well to say that this is the
same as (violet . (buttercup)) and the same
as (violet . (buttercup . nil)).  IOW, show
dot notation as a succinct version of the
cons-cell diagrams.  And say that the Lisp
reader can read this syntax:
(violet . (buttercup . nil)) is read the
same as is (violet buttercup).

This is a useful bit of Lisp knowledge, and
it's missing from the intro Elisp manual.

Nothing in the intro Elisp manual presents
dot notation.  The most it says about list
notation is that a list of items a, b, and
c is written (a b c).

The intro Elisp manual _shows_ dot notation
in passing in a couple places (e.g., custom
entry in init file), but it doesn't explain
or even mention the notation at all.  It
at least points to the existing explanation
in the Elisp manual, in its nodes Build a
List and Lists diagrammed. 

But preferably the intro manual would itself
introduce the notation briefly.

The intro manual goes into the whole cons-cell
diagramming thing.  It would do well to tie
that explanation to the Lisp notation for
lists, which includes dot notation and the
identity of (a) with (a . nil), and thus the
identity of (a b c) with (a . (b . (c . nil))).

> So I don't think we have any problems in this area, 
> and I'm therefore closing this bug.

I think this enhancement request should remain
open.  It could reasonably be on the list of
other possible improvements to the intro Elisp
manual.

A reader of the intro Elisp manual should be
exposed to this syntax, IMHO.  (a . (b . nil))
is a beautiful depiction of the corresponding
cons-cell diagram.