all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* 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 external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.