[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: defcustom and the stars.
From: |
Michaël Cadilhac |
Subject: |
Re: defcustom and the stars. |
Date: |
Wed, 03 Jan 2007 12:05:51 +0100 |
User-agent: |
Gnus/5.110006 (No Gnus v0.6) Emacs/22.0.92 (gnu/linux) |
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
- defcustom and the stars., Michaël Cadilhac, 2007/01/02
- Re: defcustom and the stars., Stefan Monnier, 2007/01/02
- Re: defcustom and the stars.,
Michaël Cadilhac <=
- Re: defcustom and the stars., Juanma Barranquero, 2007/01/03
- Re: defcustom and the stars., Michaël Cadilhac, 2007/01/03
- Re: defcustom and the stars., Juanma Barranquero, 2007/01/03
- Re: defcustom and the stars., Michaël Cadilhac, 2007/01/03
- Re: defcustom and the stars., Juanma Barranquero, 2007/01/03
- Re: defcustom and the stars., Michaël Cadilhac, 2007/01/03
- Re: defcustom and the stars., Juanma Barranquero, 2007/01/03
- Re: defcustom and the stars., Michaël Cadilhac, 2007/01/03
- Re: defcustom and the stars., Juanma Barranquero, 2007/01/03
- Re: defcustom and the stars., Juanma Barranquero, 2007/01/03