bug#3135: 23.0.92; doc of custom-variable-documentation

bug#3135: 23.0.92; doc of custom-variable-documentation

[Drew Adams]

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.
 
 
 

bug#3135: 23.0.92; doc of custom-variable-documentation

[Lars Magne Ingebrigtsen]

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

bug#3135: 23.0.92; doc of custom-variable-documentation

[Drew Adams]

> >  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')?

bug#3135: 23.0.92; doc of custom-variable-documentation

[Lars Magne Ingebrigtsen]

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

bug#3135: 23.0.92; doc of custom-variable-documentation

[Drew Adams]

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

bug#3135: 23.0.92; doc of custom-variable-documentation

[Deniz Dogan]

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

bug#3135: 23.0.92; doc of custom-variable-documentation

[Chong Yidong]

Deniz Dogan <deniz@dogan.se> writes:

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

Indeed.  Closing.

bug#3135: 23.0.92; doc of custom-variable-documentation

[Richard Stallman]

    It doesn't cost many bytes, but unnecessary "clarity" is...unnecessary. 
      I don't see why any user would be confused by this.

If there is any sign that some users misunderstand a point,
that's enough reason to make a small effort to clarify it
with a small amount of text.


-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use free telephony http://directory.fsf.org/category/tel/