Small but confusing doc error in easy-menu-define

Small but confusing doc error in easy-menu-define

[Lennart Borgman (gmail)]

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

Re: Small but confusing doc error in easy-menu-define

[Stefan Monnier]

> 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

Re: Small but confusing doc error in easy-menu-define

[Lennart Borgman (gmail)]

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

Re: Small but confusing doc error in easy-menu-define

[Juanma Barranquero]

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

Re: Small but confusing doc error in easy-menu-define

[Lennart Borgman (gmail)]

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

Re: Small but confusing doc error in easy-menu-define

[Luc Teirlinck]

Lennart Borgman wrote:

   "SYMBOL may be nil or a symbol. If it is a symbol ..."

nil is a symbol.

Sincerely,

Luc.

Re: Small but confusing doc error in easy-menu-define

[Lennart Borgman (gmail)]

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

Re: Small but confusing doc error in easy-menu-define

[Davis Herring]

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.

Re: Small but confusing doc error in easy-menu-define

[Lennart Borgman (gmail)]

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?

Re: Small but confusing doc error in easy-menu-define

[Davis Herring]

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

Re: Small but confusing doc error in easy-menu-define

[Stefan Monnier]

> 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

Re: Small but confusing doc error in easy-menu-define

[Andreas Schwab]

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

Re: Small but confusing doc error in easy-menu-define

[Lennart Borgman (gmail)]

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.