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