* Small but confusing doc error in easy-menu-define
@ 2007-04-11 22:09 Lennart Borgman (gmail)
2007-04-12 19:26 ` Stefan Monnier
0 siblings, 1 reply; 13+ messages in thread
From: Lennart Borgman (gmail) @ 2007-04-11 22:09 UTC (permalink / raw
To: Emacs Devel
The doc string for easy-menu-define says that
"If SYMBOL is non-nil, store the menu keymap in the value of symbol,
and define symbol as a function to pop up the menu, with doc as its doc
string."
I looks like it is enough that SYMBOL is just a symbol name (it need not
be interned).
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Small but confusing doc error in easy-menu-define
2007-04-11 22:09 Small but confusing doc error in easy-menu-define Lennart Borgman (gmail)
@ 2007-04-12 19:26 ` Stefan Monnier
2007-04-12 19:33 ` Lennart Borgman (gmail)
0 siblings, 1 reply; 13+ messages in thread
From: Stefan Monnier @ 2007-04-12 19:26 UTC (permalink / raw
To: Lennart Borgman (gmail); +Cc: Emacs Devel
> The doc string for easy-menu-define says that
> "If SYMBOL is non-nil, store the menu keymap in the value of symbol,
> and define symbol as a function to pop up the menu, with doc as its
> doc string."
> I looks like it is enough that SYMBOL is just a symbol name (it need not be
> interned).
I'm not sure I understand: a symbol can be either interned or not.
I.e. an uninterned symbol *is a symbol*. OTOH a symbol name is *not*
a symbol: it's a string.
Stefan
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Small but confusing doc error in easy-menu-define
2007-04-12 19:26 ` Stefan Monnier
@ 2007-04-12 19:33 ` Lennart Borgman (gmail)
2007-04-12 19:46 ` Juanma Barranquero
0 siblings, 1 reply; 13+ messages in thread
From: Lennart Borgman (gmail) @ 2007-04-12 19:33 UTC (permalink / raw
To: Stefan Monnier; +Cc: Emacs Devel
Stefan Monnier wrote:
>> The doc string for easy-menu-define says that
>
>> "If SYMBOL is non-nil, store the menu keymap in the value of symbol,
>> and define symbol as a function to pop up the menu, with doc as its
>> doc string."
>
>> I looks like it is enough that SYMBOL is just a symbol name (it need not be
>> interned).
>
> I'm not sure I understand: a symbol can be either interned or not.
> I.e. an uninterned symbol *is a symbol*. OTOH a symbol name is *not*
> a symbol: it's a string.
To me it would be easier to understand if it said
"SYMBOL may be nil or a symbol name. If it is a symbol name ..."
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Small but confusing doc error in easy-menu-define
2007-04-12 19:33 ` Lennart Borgman (gmail)
@ 2007-04-12 19:46 ` Juanma Barranquero
2007-04-12 20:06 ` Lennart Borgman (gmail)
0 siblings, 1 reply; 13+ messages in thread
From: Juanma Barranquero @ 2007-04-12 19:46 UTC (permalink / raw
To: Lennart Borgman (gmail); +Cc: Stefan Monnier, Emacs Devel
On 4/12/07, Lennart Borgman (gmail) <lennart.borgman@gmail.com>
> To me it would be easier to understand if it said
>
> "SYMBOL may be nil or a symbol name. If it is a symbol name ..."
Do you mean that SYMBOL cannot be a symbol?
Juanma
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Small but confusing doc error in easy-menu-define
2007-04-12 19:46 ` Juanma Barranquero
@ 2007-04-12 20:06 ` Lennart Borgman (gmail)
2007-04-12 20:09 ` Luc Teirlinck
0 siblings, 1 reply; 13+ messages in thread
From: Lennart Borgman (gmail) @ 2007-04-12 20:06 UTC (permalink / raw
To: Juanma Barranquero; +Cc: Stefan Monnier, Emacs Devel
Juanma Barranquero wrote:
> On 4/12/07, Lennart Borgman (gmail) <lennart.borgman@gmail.com>
>
>> To me it would be easier to understand if it said
>>
>> "SYMBOL may be nil or a symbol name. If it is a symbol name ..."
>
> Do you mean that SYMBOL cannot be a symbol?
Eh, no ;-)
"SYMBOL may be nil or a symbol. If it is a symbol ..."
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Small but confusing doc error in easy-menu-define
2007-04-12 20:06 ` Lennart Borgman (gmail)
@ 2007-04-12 20:09 ` Luc Teirlinck
2007-04-12 20:19 ` Lennart Borgman (gmail)
0 siblings, 1 reply; 13+ messages in thread
From: Luc Teirlinck @ 2007-04-12 20:09 UTC (permalink / raw
To: lennart.borgman; +Cc: lekktu, monnier, emacs-devel
Lennart Borgman wrote:
"SYMBOL may be nil or a symbol. If it is a symbol ..."
nil is a symbol.
Sincerely,
Luc.
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Small but confusing doc error in easy-menu-define
2007-04-12 20:09 ` Luc Teirlinck
@ 2007-04-12 20:19 ` Lennart Borgman (gmail)
2007-04-12 21:46 ` Davis Herring
2007-04-12 22:03 ` Andreas Schwab
0 siblings, 2 replies; 13+ messages in thread
From: Lennart Borgman (gmail) @ 2007-04-12 20:19 UTC (permalink / raw
To: Luc Teirlinck; +Cc: lekktu, monnier, emacs-devel
Luc Teirlinck wrote:
> Lennart Borgman wrote:
>
> "SYMBOL may be nil or a symbol. If it is a symbol ..."
>
> nil is a symbol.
;-)
"SYMBOL should be a symbol. If it is not the symbol nil ..."
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Small but confusing doc error in easy-menu-define
2007-04-12 20:19 ` Lennart Borgman (gmail)
@ 2007-04-12 21:46 ` Davis Herring
2007-04-12 22:23 ` Lennart Borgman (gmail)
2007-04-12 22:03 ` Andreas Schwab
1 sibling, 1 reply; 13+ messages in thread
From: Davis Herring @ 2007-04-12 21:46 UTC (permalink / raw
To: Lennart Borgman (gmail); +Cc: lekktu, Luc Teirlinck, monnier, emacs-devel
The current documentation reads:
> "If SYMBOL is non-nil, store the menu keymap in the value of symbol,
> and define symbol as a function to pop up the menu, with doc as its
> doc string."
Lennart suggested:
> "SYMBOL should be a symbol. If it is not the symbol nil ..."
Obviously "If it is not the symbol nil" is the same as "If it is non-nil",
so we have the equivalent of "If SYMBOL (which should be a symbol) is
non-nil, ...". I fail to see the point in merely adding that an argument
named SYMBOL should be, um, a symbol.
Davis
--
This product is sold by volume, not by mass. If it appears too dense or
too sparse, it is because mass-energy conversion has occurred during
shipping.
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Small but confusing doc error in easy-menu-define
2007-04-12 20:19 ` Lennart Borgman (gmail)
2007-04-12 21:46 ` Davis Herring
@ 2007-04-12 22:03 ` Andreas Schwab
2007-04-12 22:20 ` Lennart Borgman (gmail)
1 sibling, 1 reply; 13+ messages in thread
From: Andreas Schwab @ 2007-04-12 22:03 UTC (permalink / raw
To: Lennart Borgman (gmail); +Cc: lekktu, Luc Teirlinck, monnier, emacs-devel
"Lennart Borgman (gmail)" <lennart.borgman@gmail.com> writes:
> "SYMBOL should be a symbol. If it is not the symbol nil ..."
What should SYMBOL be, if not a symbol?
Andreas.
--
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5
"And now for something completely different."
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Small but confusing doc error in easy-menu-define
2007-04-12 22:03 ` Andreas Schwab
@ 2007-04-12 22:20 ` Lennart Borgman (gmail)
0 siblings, 0 replies; 13+ messages in thread
From: Lennart Borgman (gmail) @ 2007-04-12 22:20 UTC (permalink / raw
To: Andreas Schwab; +Cc: lekktu, Luc Teirlinck, monnier, emacs-devel
Andreas Schwab wrote:
> "Lennart Borgman (gmail)" <lennart.borgman@gmail.com> writes:
>
>> "SYMBOL should be a symbol. If it is not the symbol nil ..."
>
> What should SYMBOL be, if not a symbol?
Yes, maybe there should be different standards for the doc string for
different usage levels, I do not know. IMO however it is never wrong
beeing as clear as possible.
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Small but confusing doc error in easy-menu-define
2007-04-12 21:46 ` Davis Herring
@ 2007-04-12 22:23 ` Lennart Borgman (gmail)
2007-04-12 23:55 ` Davis Herring
0 siblings, 1 reply; 13+ messages in thread
From: Lennart Borgman (gmail) @ 2007-04-12 22:23 UTC (permalink / raw
To: herring; +Cc: lekktu, Luc Teirlinck, monnier, emacs-devel
Davis Herring wrote:
> The current documentation reads:
>
>> "If SYMBOL is non-nil, store the menu keymap in the value of symbol,
>> and define symbol as a function to pop up the menu, with doc as its
>> doc string."
>
> Lennart suggested:
>
>> "SYMBOL should be a symbol. If it is not the symbol nil ..."
>
> Obviously "If it is not the symbol nil" is the same as "If it is non-nil",
> so we have the equivalent of "If SYMBOL (which should be a symbol) is
> non-nil, ...". I fail to see the point in merely adding that an argument
> named SYMBOL should be, um, a symbol.
It is different level of abstraction, isn't it? Does not "non-nil" in
Emacs doc usually means that a symbol value is not nil?
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Small but confusing doc error in easy-menu-define
2007-04-12 22:23 ` Lennart Borgman (gmail)
@ 2007-04-12 23:55 ` Davis Herring
2007-04-13 12:37 ` Stefan Monnier
0 siblings, 1 reply; 13+ messages in thread
From: Davis Herring @ 2007-04-12 23:55 UTC (permalink / raw
To: Lennart Borgman (gmail); +Cc: lekktu, Luc Teirlinck, monnier, emacs-devel
> It is different level of abstraction, isn't it? Does not "non-nil" in
> Emacs doc usually means that a symbol value is not nil?
Yes, yes it does. In this case, it means that the symbol named "symbol"
(described, as per usual, as SYMBOL in the doc string), which is bound to
the appropriate argument value when the function is called, has a value
that is not nil (and, by implication of the symbol's name ("symbol"), is
some other symbol instead).
Now, if you're talking about the value of the passed symbol as a variable,
I think you'd need to say something to the effect of "If SYMBOL's value as
a variable is non-nil, ...", but that's not what's meant.
Davis
--
This product is sold by volume, not by mass. If it appears too dense or
too sparse, it is because mass-energy conversion has occurred during
shipping.
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Small but confusing doc error in easy-menu-define
2007-04-12 23:55 ` Davis Herring
@ 2007-04-13 12:37 ` Stefan Monnier
0 siblings, 0 replies; 13+ messages in thread
From: Stefan Monnier @ 2007-04-13 12:37 UTC (permalink / raw
To: herring; +Cc: lekktu, Lennart Borgman (gmail), Luc Teirlinck, emacs-devel
> Yes, yes it does. In this case, it means that the symbol named "symbol"
> (described, as per usual, as SYMBOL in the doc string), which is bound to
> the appropriate argument value when the function is called, has a value
> that is not nil (and, by implication of the symbol's name ("symbol"), is
> some other symbol instead).
I think it's a much better idea to distinguish variables from symbols.
SYMBOL is a variable whose value should be a symbol. Symbols have several
different fields, including a "value" field, a "function" field and
a "property-list" field.
Stefan
^ permalink raw reply [flat|nested] 13+ messages in thread
end of thread, other threads:[~2007-04-13 12:37 UTC | newest]
Thread overview: 13+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2007-04-11 22:09 Small but confusing doc error in easy-menu-define Lennart Borgman (gmail)
2007-04-12 19:26 ` Stefan Monnier
2007-04-12 19:33 ` Lennart Borgman (gmail)
2007-04-12 19:46 ` Juanma Barranquero
2007-04-12 20:06 ` Lennart Borgman (gmail)
2007-04-12 20:09 ` Luc Teirlinck
2007-04-12 20:19 ` Lennart Borgman (gmail)
2007-04-12 21:46 ` Davis Herring
2007-04-12 22:23 ` Lennart Borgman (gmail)
2007-04-12 23:55 ` Davis Herring
2007-04-13 12:37 ` Stefan Monnier
2007-04-12 22:03 ` Andreas Schwab
2007-04-12 22:20 ` Lennart Borgman (gmail)
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).