Re: defcustom and the stars.

[Michaël Cadilhac]

"Juanma Barranquero" <address@hidden> writes:

> On 1/3/07, Michaël Cadilhac <address@hidden> wrote:
>
>> http://permalink.gmane.org/gmane.emacs.devel/64677
>
>> And the only reference to user variable in this doc is
>> for customizable vars (AFAICS).
>
> Then yes, perhaps a doc patch would be in order.

So let's give it a try (writing doc is always funny for me as my
English is far from good).  This is to be read together with the
previous patch (if applied).

Index: man/custom.texi
===================================================================
RCS file: /sources/emacs/emacs/man/custom.texi,v
retrieving revision 1.124
diff -c -r1.124 custom.texi
*** man/custom.texi     1 Jan 2007 01:57:16 -0000       1.124
--- man/custom.texi     3 Jan 2007 14:36:31 -0000
***************
*** 807,813 ****
  Display the value and documentation of variable @var{var}
  (@code{describe-variable}).
  @item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET}
! Change the value of variable @var{var} to @var{value}.
  @end table
  
    To examine the value of a single variable, use @kbd{C-h v}
--- 807,813 ----
  Display the value and documentation of variable @var{var}
  (@code{describe-variable}).
  @item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET}
! Change the value of the user option variable @var{var} to @var{value}.
  @end table
  
    To examine the value of a single variable, use @kbd{C-h v}
***************
*** 832,838 ****
  satisfies the predicate `integerp'.
  
  Documentation:
! *Column beyond which automatic line-wrapping should happen.
  Interactively, you can set the buffer local value using C-x f.
  
  You can customize this variable.
--- 832,838 ----
  satisfies the predicate `integerp'.
  
  Documentation:
! Column beyond which automatic line-wrapping should happen.
  Interactively, you can set the buffer local value using C-x f.
  
  You can customize this variable.
***************
*** 840,848 ****
  
  @noindent
  The line that says you can customize the variable indicates that this
! variable is a user option.  (The star also indicates this, but it is
! an obsolete indicator that may eventually disappear.)  @kbd{C-h v} is
! not restricted to user options; it allows any variable name.
  
  @findex set-variable
  The most convenient way to set a specific user option variable is with
--- 840,848 ----
  
  @noindent
  The line that says you can customize the variable indicates that this
! variable is a user option, as would have indicated a line saying that
! you can change at user level the variable.  @kbd{C-h v} is not
! restricted to user options; it allows any variable name.
  
  @findex set-variable
  The most convenient way to set a specific user option variable is with
Index: man/ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/man/ChangeLog,v
retrieving revision 1.1177
diff -C0 -r1.1177 ChangeLog
*** man/ChangeLog       1 Jan 2007 22:20:46 -0000       1.1177
--- man/ChangeLog       3 Jan 2007 14:36:47 -0000
***************
*** 0 ****
--- 1,9 ----
+ 2007-01-03  Michaël Cadilhac  <address@hidden>
+ 
+       * custom.texi (Examining): Say sooner that set-variable takes only
+       user option variables.
+       Remove the leading `*' in the documentation of `fill-column' used as an
+       example.  Remove the mention on the obsolescence of this star.
+       Indicate that the line `you can change at user level the variable'
+       means that the variable is a user option.
+ 

> Regarding your patch, I'm not sure. On one hand, talking about
> set-variable in the output of describe-variable can be useful, and it
> certainly isn't like we are shy about adding useful info there (try
> with an automatically buffer-local, obsolete variable alias with a
> safe-local-variable property :)
>
> On the other hand, it is already quite crowded...

At least, it will not add any line to an automatically buffer-local,
obsolete variable alias with a safe-local-variable property WHICH IS
customizable. Only to a [...] that has a "*" and is not customizable!

-- 
 |      Michaël `Micha' Cadilhac     |    The second-degree,                  |
 |         Epita/LRDE Promo 2007     |       is kind of                       |
 |  http://michael.cadilhac.name     |   the semantic back slang.             |
 `--JID: address@hidden'                                   -  --'

pgpLvELy2SNE5.pgp
Description: PGP signature