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

[uzibalqa via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

------- Original Message -------
On Tuesday, July 18th, 2023 at 10:53 PM, Eli Zaretskii <eliz@gnu.org> wrote:


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

The suggestion is to improve and expand the section on Cons Cells and Dotted Notation
not only in the reference manual but also in the introduction manual.  Unwillingness
to not even provide a cross-reference is a disservice.
 
> > 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.

No, I am talking about a direct discussion of Cons Cells and Dotted Notation,
not about list diagrams.  

The specification that 

 (a b c . dlist) 

results in a single list should be described rather than having everybody 
figure it out independently.  Whilst using a b c in not so bad, if I but 
such code in a package, most experienced programmers would complain that
I am being too cryptic even though they should have the ability to decipher
whatever I'm doing.   Real-life examples of interesting situations from the 
emacs code base should also be used if you want people to transition from
toy descriptions to real life work.

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

The examples are incomplete because making submenus is avoided and there are no calls
to 'define-key-after'.  And because the reference is not for examples as the experienced
ones insist, that information should be put in the 'Introduction Guide' instead.

Besides, now that it is suggested that calls be replaced with keymap-set-after and
'keymap-set', the reference and introduction must reflect the change to the new calls.

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


How very convenient when new users are telling you that the information is not
useful enough.