* bug#64693: Documentation for the definition of a Menu Item
@ 2023-07-17 20:44 uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-18 11:03 ` Eli Zaretskii
0 siblings, 1 reply; 4+ messages in thread
From: uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-07-17 20:44 UTC (permalink / raw
To: 64693
Have been looking at the documentation for 'DEF' in 'define-key'.
(define-key KEYMAP KEY DEF &optional REMOVE)
DEF, the definition of a Menu Item is described in form as
(menu-item item-name binding . item-property-list)
Note that DEF constitutes a single list. The special
dotted notation indicates that 'item-property-list' is not
a separate list but rather enables any number of property
elements in the form of ':keyword value' within the same
list structure.
But such detail is not properly described. Pointing out how
the description of 'Cons Cells' and 'Dotted Notation' is sketchy
at best in the 'Elisp Reference Manual', and non-existent in
the 'Introduction to Programming in Emacs Lisp', the aforementioned
description should be added in the documentation of 'define-key'.
Furthermore, a more comprehensive explanation of Cons Cells, Dotted
Notation, and Backquote Construct, should be introduced and backed up
with real-life syntax such as the one described here.
^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#64693: Documentation for the definition of a Menu Item
2023-07-17 20:44 bug#64693: Documentation for the definition of a Menu Item uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2023-07-18 11:03 ` Eli Zaretskii
2023-07-18 11:35 ` uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 4+ messages in thread
From: Eli Zaretskii @ 2023-07-18 11:03 UTC (permalink / raw
To: uzibalqa; +Cc: 64693-done
> Date: Mon, 17 Jul 2023 20:44:04 +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 for 'DEF' in 'define-key'.
>
> (define-key KEYMAP KEY DEF &optional REMOVE)
>
> DEF, the definition of a Menu Item is described in form as
>
> (menu-item item-name binding . item-property-list)
>
> Note that DEF constitutes a single list. The special
> dotted notation indicates that 'item-property-list' is not
> a separate list but rather enables any number of property
> elements in the form of ':keyword value' within the same
> list structure.
>
> But such detail is not properly described.
If you type "i property list RET" in Info, you will land in the
"Property Lists" node, which starts by saying:
A “property list” (“plist” for short) is a list of paired elements.
Each of the pairs associates a property name (usually a symbol) with a
property or value.
So I think when the manual says that item-property-list is a property
list, it does a good job.
> Furthermore, a more comprehensive explanation of Cons Cells, Dotted
> Notation, and Backquote Construct, should be introduced and backed up
> with real-life syntax such as the one described here.
This is all properly done elsewhere in the manual; see my response to
your report in bug#64692.
So I'm closing this bug.
^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#64693: Documentation for the definition of a Menu Item
2023-07-18 11:03 ` Eli Zaretskii
@ 2023-07-18 11:35 ` uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-18 12:58 ` Eli Zaretskii
0 siblings, 1 reply; 4+ messages in thread
From: uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-07-18 11:35 UTC (permalink / raw
To: Eli Zaretskii; +Cc: 64693-done
------- Original Message -------
On Tuesday, July 18th, 2023 at 11:03 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> > Date: Mon, 17 Jul 2023 20:44:04 +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 for 'DEF' in 'define-key'.
> >
> > (define-key KEYMAP KEY DEF &optional REMOVE)
> >
> > DEF, the definition of a Menu Item is described in form as
> >
> > (menu-item item-name binding . item-property-list)
Looking at "23.17.1.1 Simple Menu Items" nowhere does it say that
the vector of symbols is equivalent to the sequence of keystrokes
when using keyboard bindings (key sequences).
> > Note that DEF constitutes a single list. The special
> > dotted notation indicates that 'item-property-list' is not
> > a separate list but rather enables any number of property
> > elements in the form of ':keyword value' within the same
> > list structure.
> >
> > But such detail is not properly described.
>
>
> If you type "i property list RET" in Info, you will land in the
> "Property Lists" node, which starts by saying:
>
> A “property list” (“plist” for short) is a list of paired elements.
> Each of the pairs associates a property name (usually a symbol) with a
> property or value.
Provide a cross-reference to 'property list' in "23.17.1.2 Extended Menu Items".
> So I think when the manual says that item-property-list is a property
> list, it does a good job.
>
> > Furthermore, a more comprehensive explanation of Cons Cells, Dotted
> > Notation, and Backquote Construct, should be introduced and backed up
> > with real-life syntax such as the one described here.
>
>
> This is all properly done elsewhere in the manual; see my response to
> your report in bug#64692.
>
> So I'm closing this bug.
>
^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#64693: Documentation for the definition of a Menu Item
2023-07-18 11:35 ` uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2023-07-18 12:58 ` Eli Zaretskii
0 siblings, 0 replies; 4+ messages in thread
From: Eli Zaretskii @ 2023-07-18 12:58 UTC (permalink / raw
To: uzibalqa; +Cc: 64693-done
> Date: Tue, 18 Jul 2023 11:35:27 +0000
> From: uzibalqa <uzibalqa@proton.me>
> Cc: 64693-done@debbugs.gnu.org
>
> > A “property list” (“plist” for short) is a list of paired elements.
> > Each of the pairs associates a property name (usually a symbol) with a
> > property or value.
>
> Provide a cross-reference to 'property list' in "23.17.1.2 Extended Menu Items".
Done, thanks.
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2023-07-18 12:58 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-07-17 20:44 bug#64693: Documentation for the definition of a Menu Item uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-18 11:03 ` Eli Zaretskii
2023-07-18 11:35 ` uzibalqa via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-18 12:58 ` Eli Zaretskii
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).