Re: defcustom and the stars.

[michael@cadilhac.name (Michaël Cadilhac)]

[-- Attachment #1.1.1: Type: text/plain, Size: 1362 bytes --]

Stefan Monnier <monnier@iro.umontreal.ca> 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.


[-- Attachment #1.1.2: help.patch --]
[-- Type: text/x-patch, Size: 3578 bytes --]

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  <michael.cadilhac@lrde.org>
+ 
+ 	* 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.
+ 

[-- Attachment #1.1.3: Type: text/plain, Size: 331 bytes --]


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

[-- Attachment #1.2: Type: application/pgp-signature, Size: 188 bytes --]

[-- Attachment #2: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel