Re: defcustom and the stars.

[Michaël Cadilhac]

Stefan Monnier <address@hidden> writes:

>> Since I started Elisp programming, I've always wondered why there is
>> an opposition between the following lines of the manual:
>
>>  -- Macro: defcustom option standard doc [keyword value]...
>>      [...]There is no need to start [the docstring] with a `*'
>
>> [and]
>> (this is 3011 matches of bad-style according to the doc)
>
>> Is there any reason ?
>
> History.  The * used to be necessary for M-x set-variable to be usable.
> Now the * in defcustoms is just a relic and should slowly disappear.

Why slowly? :-) Don't you think it can be disturbing for new users to
see that star, and after a little search on the (info "(emacs)") to
read:
     (it is an obsolete indicator that may eventually disappear.)

And, reading that part of the manual, there is:

  The line that says you can customize the variable indicates that
  this variable is a user option.

So the only documentation for `user options' is that some of them are
customizable variable.  Don't we want to talk about (defvar)s with
a docstring starting by "*"?  Won't the user be surprised to see that
the completion list for M-x set-variable and M-x customize-variable
aren't the same?

Apart from that, why don't we propose in C-h v to modify user
variables ((defvar)s with "*")?  I propose the following change, if
the idea is ok.

Index: lisp/help-mode.el
===================================================================
RCS file: /sources/emacs/emacs/lisp/help-mode.el,v
retrieving revision 1.50
diff -c -r1.50 help-mode.el
*** lisp/help-mode.el   21 Jul 2006 22:54:40 -0000      1.50
--- lisp/help-mode.el   3 Jan 2007 11:00:09 -0000
***************
*** 139,144 ****
--- 139,154 ----
                   (customize-variable v))
    'help-echo (purecopy "mouse-2, RET: customize variable"))
  
+ (define-button-type 'help-change-variable
+   :supertype 'help-xref
+   'help-function (lambda (v)
+                  (let ((read-variable (symbol-function 'read-variable)))
+                    (fset 'read-variable (lambda (prompt &optional d-v)
+                                           (fset 'read-variable read-variable)
+                                           v))
+                    (call-interactively 'set-variable)))
+   'help-echo (purecopy "mouse-2, RET: change user variable"))
+ 
  (define-button-type 'help-customize-face
    :supertype 'help-xref
    'help-function (lambda (v)
Index: lisp/help-fns.el
===================================================================
RCS file: /sources/emacs/emacs/lisp/help-fns.el,v
retrieving revision 1.94
diff -c -r1.94 help-fns.el
*** lisp/help-fns.el    17 Dec 2006 22:14:11 -0000      1.94
--- lisp/help-fns.el    3 Jan 2007 11:00:09 -0000
***************
*** 573,578 ****
--- 573,581 ----
                   (safe-var (get variable 'safe-local-variable))
                     (doc (or (documentation-property variable 
'variable-documentation)
                              (documentation-property alias 
'variable-documentation))))
+             ;; If DOC starts with a `*' remove it.
+             (when (eq (aref doc 0) ?*)
+               (setq doc (substring doc 1)))
                (unless (eq alias variable)
                  (princ (format "\nThis variable is an alias for `%s'.\n" 
alias)))
              (if (or obsolete safe-var)
***************
*** 603,609 ****
                    (save-excursion
                      (re-search-backward
                       (concat "\\(" customize-label "\\)") nil t)
!                     (help-xref-button 1 'help-customize-variable variable)))))
            (print-help-return-message)
            (save-excursion
              (set-buffer standard-output)
--- 606,623 ----
                    (save-excursion
                      (re-search-backward
                       (concat "\\(" customize-label "\\)") nil t)
!                     (help-xref-button 1 'help-customize-variable variable))))
!             (if (user-variable-p variable)
!                 (let ((change-label "change"))
!                   (terpri)
!                   (terpri)
!                   (princ (concat "You can " change-label
!                                  " at user level this variable."))
!                   (with-current-buffer standard-output
!                     (save-excursion
!                       (re-search-backward
!                        (concat "\\(" change-label "\\)") nil t)
!                       (help-xref-button 1 'help-change-variable variable))))))
            (print-help-return-message)
            (save-excursion
              (set-buffer standard-output)
Index: lisp/ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/lisp/ChangeLog,v
retrieving revision 1.10518
diff -C0 -r1.10518 ChangeLog
*** lisp/ChangeLog      2 Jan 2007 10:16:04 -0000       1.10518
--- lisp/ChangeLog      3 Jan 2007 11:00:33 -0000
***************
*** 0 ****
--- 1,9 ----
+ 2007-01-03  Michaël Cadilhac  <address@hidden>
+ 
+       * help-mode.el (help-change-variable): New.  Call `set-variable' with
+       the variable name (first argument) fixed.
+ 
+       * help-fns.el (describe-variable): If the docstring starts with a star,
+       then remove it.
+       Propose the user to change (with `set-variable') user variables.
+ 

-- 
 |      Michaël `Micha' Cadilhac     |  Un certain Blaise Pascal              |
 |         Epita/LRDE Promo 2007     |    etc... etc...                       |
 |  http://michael.cadilhac.name     |  -- Prévert (Les paris stupides)       |
 `--JID: address@hidden'                                   -  --'

pgporejL7Pp5y.pgp
Description: PGP signature