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

[Eli Zaretskii]

> Date: Mon, 17 Jul 2023 20:17:19 +0000
> From:  uzibalqa via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> Have been looking at the documentation of menu-item described as
> 
> (menu-item item-name real-binding . item-property-list)
> 
> This requires a good understanding of Cons Cells and Dotted Notation.
> But I do not see a serious attempt to explain this.

There's a node "Cons Cells" in the manual which explains that.

The cons cells are so central to Emacs Lisp that it is impractical to
explain them in each place where we use them in the manual, or even
provide a cross-reference in each such place.

> 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.

> In general, the construction of menus should be better described as it is 
> currently 
> too theoretical in the reference.

I disagree that it's "theoretical": it's quite practical, and even
includes an example.

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