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

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]

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

For instance, whilst it cam became natural for users to make menus. it would be 
difficult for them to understand that 

(menu-item item-name real-binding . item-property-list)

describes how "item-property-list" would not produce a list inside a list, but a 
single "(menu-item ..." list.

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

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

[Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors]

uzibalqa <uzibalqa@proton.me> writes:

> 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.  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.
>
> For instance, whilst it cam became natural for users to make menus. it would be 
> difficult for them to understand that 
>
> (menu-item item-name real-binding . item-property-list)
>
> describes how "item-property-list" would not produce a list inside a list, but a 
> single "(menu-item ..." list.
>
> In general, the construction of menus should be better described as it is currently 
> too theoretical in the reference.

The node containing your example is located in the Emacs Lisp reference
manual, which contains two adequate descriptions of both dotted lists
and dotted pair notation.  I see no problem here; closing.

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

[Ihor Radchenko]

Po Lu via "Bug reports for GNU Emacs, the Swiss army knife of text
editors" <bug-gnu-emacs@gnu.org> writes:

>> In general, the construction of menus should be better described as it is currently 
>> too theoretical in the reference.
>
> The node containing your example is located in the Emacs Lisp reference
> manual, which contains two adequate descriptions of both dotted lists
> and dotted pair notation.  I see no problem here; closing.

The problem is for new users who see no need to lookup Emacs Lisp
reference.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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

[Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Ihor Radchenko <yantar92@posteo.net> writes:

> The problem is for new users who see no need to lookup Emacs Lisp
> reference.

If they are reading the documentation mentioned in the bug report, they
are _already_ reading the Lisp reference manual.

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

[Christopher Dimech]

> Sent: Wednesday, July 19, 2023 at 12:42 AM
> From: "Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> To: "Ihor Radchenko" <yantar92@posteo.net>
> Cc: 64692@debbugs.gnu.org, "uzibalqa" <uzibalqa@proton.me>
> Subject: bug#64692: Better descriptions of Cons Cells and Dotted Notation with real-life syntax
>
> Ihor Radchenko <yantar92@posteo.net> writes:
>
> > The problem is for new users who see no need to lookup Emacs Lisp
> > reference.
>
> If they are reading the documentation mentioned in the bug report, they
> are _already_ reading the Lisp reference manual.

Reading it does not mean understanding it !

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

[Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Christopher Dimech <dimech@gmx.com> writes:

> Reading it does not mean understanding it !

There is no space in any Emacs manual to repeatedly explain basic Lisp
reader syntax every time it is used.

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

[Drew Adams]

> The node containing your example is located in the Emacs Lisp reference
> manual, which contains two adequate descriptions of both dotted lists
> and dotted pair notation.  

Yes, it does.
But a reader of this menu-syntax node
won't have a clue about that.  Please
provide a cross-reference to it.

Defining menus is one of the first
places a new Elisp user will run into
dot-notation syntax.

Another is the complex syntax for
font-lock.  There too a reader will
need to understand dot notation to
make sense of the syntax spec.

> I see no problem here; closing.

That's too bad.

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]

------- Original Message -------
On Wednesday, July 19th, 2023 at 5:20 AM, Drew Adams <drew.adams@oracle.com> wrote:


> > The node containing your example is located in the Emacs Lisp reference
> > manual, which contains two adequate descriptions of both dotted lists
> > and dotted pair notation.
> 
> 
> Yes, it does.
> But a reader of this menu-syntax node
> won't have a clue about that. Please
> provide a cross-reference to it.
> 
> Defining menus is one of the first
> places a new Elisp user will run into
> dot-notation syntax.
> 
> Another is the complex syntax for
> font-lock. There too a reader will
> need to understand dot notation to
> make sense of the syntax spec.
> 
> > I see no problem here; closing.
> 
> That's too bad.

It is too bad for us.  With people who should know better barking orders
from their lofty place that everything is fine.  Same as the socialist 
politburo  in the late 80's.  A system fucked up beyond all recognition.

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.

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]

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

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.