* bug#3135: 23.0.92; doc of custom-variable-documentation
@ 2009-04-27 21:16 Drew Adams
2011-07-11 14:59 ` Lars Magne Ingebrigtsen
0 siblings, 1 reply; 8+ messages in thread
From: Drew Adams @ 2009-04-27 21:16 UTC (permalink / raw)
To: emacs-pretest-bug
Doc string:
Return documentation of VARIABLE for use in Custom buffer.
Normally just return the docstring. But if VARIABLE automatically
becomes buffer local when set, append a message to that effect.
We need to make clear that VARIABLE need not be a user
variable. Especially because much of the time the doc for `custom-*'
treats a VARIABLE as a user variable.
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#3135: 23.0.92; doc of custom-variable-documentation
2009-04-27 21:16 bug#3135: 23.0.92; doc of custom-variable-documentation Drew Adams
@ 2011-07-11 14:59 ` Lars Magne Ingebrigtsen
2011-07-11 15:51 ` Drew Adams
0 siblings, 1 reply; 8+ messages in thread
From: Lars Magne Ingebrigtsen @ 2011-07-11 14:59 UTC (permalink / raw)
To: Drew Adams; +Cc: 3135
"Drew Adams" <drew.adams@oracle.com> writes:
> Doc string:
>
> Return documentation of VARIABLE for use in Custom buffer.
> Normally just return the docstring. But if VARIABLE automatically
> becomes buffer local when set, append a message to that effect.
>
> We need to make clear that VARIABLE need not be a user
> variable. Especially because much of the time the doc for `custom-*'
> treats a VARIABLE as a user variable.
In my opinion, it's clear enough as it is.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog http://lars.ingebrigtsen.no/
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#3135: 23.0.92; doc of custom-variable-documentation
2011-07-11 14:59 ` Lars Magne Ingebrigtsen
@ 2011-07-11 15:51 ` Drew Adams
2011-07-11 15:56 ` Lars Magne Ingebrigtsen
0 siblings, 1 reply; 8+ messages in thread
From: Drew Adams @ 2011-07-11 15:51 UTC (permalink / raw)
To: 'Lars Magne Ingebrigtsen'; +Cc: 3135
> > Return documentation of VARIABLE for use in Custom buffer.
> > Normally just return the docstring. But if VARIABLE automatically
> > becomes buffer local when set, append a message to that effect.
> >
> > We need to make clear that VARIABLE need not be a user
> > variable. Especially because much of the time the doc for `custom-*'
> > treats a VARIABLE as a user variable.
>
> In my opinion, it's clear enough as it is.
What makes it clear that VARIABLE is not necessarily a user variable
(`user-variable-p')?
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#3135: 23.0.92; doc of custom-variable-documentation
2011-07-11 15:51 ` Drew Adams
@ 2011-07-11 15:56 ` Lars Magne Ingebrigtsen
2011-07-11 16:24 ` Drew Adams
0 siblings, 1 reply; 8+ messages in thread
From: Lars Magne Ingebrigtsen @ 2011-07-11 15:56 UTC (permalink / raw)
To: Drew Adams; +Cc: 3135
"Drew Adams" <drew.adams@oracle.com> writes:
>> > Return documentation of VARIABLE for use in Custom buffer.
>> > Normally just return the docstring. But if VARIABLE automatically
>> > becomes buffer local when set, append a message to that effect.
>> >
>> > We need to make clear that VARIABLE need not be a user
>> > variable. Especially because much of the time the doc for `custom-*'
>> > treats a VARIABLE as a user variable.
>>
>> In my opinion, it's clear enough as it is.
>
> What makes it clear that VARIABLE is not necessarily a user variable
> (`user-variable-p')?
It says nothing about VARIABLE being a special kind of variable, so it
seems pretty obvious to me that it's talking about all kinds of
variables.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog http://lars.ingebrigtsen.no/
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#3135: 23.0.92; doc of custom-variable-documentation
2011-07-11 15:56 ` Lars Magne Ingebrigtsen
@ 2011-07-11 16:24 ` Drew Adams
2011-07-11 17:30 ` Deniz Dogan
0 siblings, 1 reply; 8+ messages in thread
From: Drew Adams @ 2011-07-11 16:24 UTC (permalink / raw)
To: 'Lars Magne Ingebrigtsen'; +Cc: 3135
> >> In my opinion, it's clear enough as it is.
> >
> > What makes it clear that VARIABLE is not necessarily a user variable
> > (`user-variable-p')?
>
> It says nothing about VARIABLE being a special kind of variable, so it
> seems pretty obvious to me that it's talking about all kinds of
> variables.
It might be clear to you, but not to users. Customize is all about user
variables (options). We should be very clear whenever we mean a variable that
is not necessarily a user variable.
What does this added clarity cost? It's about _users_; it's not about Emacs
Dev's ease in dispatching bugs summarily.
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#3135: 23.0.92; doc of custom-variable-documentation
2011-07-11 16:24 ` Drew Adams
@ 2011-07-11 17:30 ` Deniz Dogan
2011-07-12 2:57 ` Chong Yidong
2011-07-12 19:06 ` Richard Stallman
0 siblings, 2 replies; 8+ messages in thread
From: Deniz Dogan @ 2011-07-11 17:30 UTC (permalink / raw)
To: 3135
On 2011-07-11 18:24, Drew Adams wrote:
>>>> In my opinion, it's clear enough as it is.
>>>
>>> What makes it clear that VARIABLE is not necessarily a user variable
>>> (`user-variable-p')?
>>
>> It says nothing about VARIABLE being a special kind of variable, so it
>> seems pretty obvious to me that it's talking about all kinds of
>> variables.
>
> It might be clear to you, but not to users. Customize is all about user
> variables (options). We should be very clear whenever we mean a variable that
> is not necessarily a user variable.
>
For what it's worth, I'm with Lars on this one. We shouldn't have to
clarify what things are *not*, only what they are, concisely. Both
defvars and defcustoms can have docstrings and I don't think anyone is
confused by it.
> What does this added clarity cost? It's about _users_; it's not about Emacs
> Dev's ease in dispatching bugs summarily.
>
It doesn't cost many bytes, but unnecessary "clarity" is...unnecessary.
I don't see why any user would be confused by this.
Deniz
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2011-07-12 19:06 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2009-04-27 21:16 bug#3135: 23.0.92; doc of custom-variable-documentation Drew Adams
2011-07-11 14:59 ` Lars Magne Ingebrigtsen
2011-07-11 15:51 ` Drew Adams
2011-07-11 15:56 ` Lars Magne Ingebrigtsen
2011-07-11 16:24 ` Drew Adams
2011-07-11 17:30 ` Deniz Dogan
2011-07-12 2:57 ` Chong Yidong
2011-07-12 19:06 ` Richard Stallman
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).