defcustom and the stars.

defcustom and the stars.

[Michaël Cadilhac]

[-- Attachment #1.1: Type: text/plain, Size: 1096 bytes --]

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 these lines of shell:

  mistral% cd ~/src/emacs/lisp
  mistral% echo; cat grep.awk; echo
  
  BEGIN { grepped=0 }
  /^\(defcustom/ { grepped=1 ; next }
  /^ *"[*]/ { if (grepped==1) { print (FILENAME, ":", NR) } }
  { grepped=0 }
  
  mistral% { for f (**/*.el) awk -f grep.awk $f } | wc -l
  3011
  
(this is 3011 matches of bad-style according to the doc)

Is there any reason ? I see patches like
http://thread.gmane.org/gmane.emacs.devel/38098
going to the trunk, so I don't know.

-- 
 |      Michaël `Micha' Cadilhac     |  Pour les 35-40 ans, l'humour          |
 |         Epita/LRDE Promo 2007     |       c'est une plus-value.            |
 |  http://michael.cadilhac.name     |          -- Guillaume L.               |
 `--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

Re: defcustom and the stars.

[Stefan Monnier]

> 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 these lines of shell:

>   mistral% cd ~/src/emacs/lisp
>   mistral% echo; cat grep.awk; echo
  
>   BEGIN { grepped=0 }
>   /^\(defcustom/ { grepped=1 ; next }
>   /^ *"[*]/ { if (grepped==1) { print (FILENAME, ":", NR) } }
>   { grepped=0 }
  
>   mistral% { for f (**/*.el) awk -f grep.awk $f } | wc -l
>   3011
  
> (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.


        Stefan

Re: defcustom and the stars.

[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

Re: defcustom and the stars.

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 480 bytes --]

On 1/3/07, Michaël Cadilhac <michael@cadilhac.name> wrote:

> Why slowly? :-)

Because if you change every defcustom's "*docstring" to "docstring" at
this point in time, the people painstakingly maintaining parallel
branches ready to integrate into the trunk might feel the urge to do a
little ceremony involving a doll, headless chickens and a few strands
of your hair and/or nail clippings. And needles, of course. Let's not
forget the needles.

                    /L/e/k/t/u

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

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

Re: defcustom and the stars.

[Michaël Cadilhac]

[-- Attachment #1.1: Type: text/plain, Size: 1229 bytes --]

"Juanma Barranquero" <lekktu@gmail.com> writes:

> On 1/3/07, Michaël Cadilhac <michael@cadilhac.name> wrote:
>
>> Why slowly? :-)
>
> Because if you change every defcustom's "*docstring" to "docstring" at
> this point in time, the people painstakingly maintaining parallel
> branches ready to integrate into the trunk might feel the urge to do a
> little ceremony involving a doll, headless chickens and a few strands
> of your hair and/or nail clippings. And needles, of course. Let's not
> forget the needles.

Strange thing: Guybrush T. (from Caraibe) only needed a pearly-white
bra, a bone, a spit and a toupee. And needles, of course.

Okey, so « slowly » means « when you modify some defcustom, don't
forget to do that ».

So let's consider hiding this star in C-h v, like I proposed earlier,
nop ?

PS: I'm not used to just reply `lol rofl mdr', but I wanted to. :-)

-- 
 |      Michaël `Micha' Cadilhac     |  La culture c'est comme la confiture,  |
 |         Epita/LRDE Promo 2007     |      c'est meilleur avec du pain.      |
 |  http://michael.cadilhac.name     |           -- MOI59                     |
 `--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

Re: defcustom and the stars.

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 1260 bytes --]

On 1/3/07, Michaël Cadilhac <michael@cadilhac.name> wrote:

> Strange thing: Guybrush T. (from Caraibe) only needed a pearly-white
> bra, a bone, a spit and a toupee. And needles, of course.

Same goals, different tactics :)

> Okey, so « slowly » means « when you modify some defcustom, don't
> forget to do that ».

I think that's the idea, yeah.

> So let's consider hiding this star in C-h v, like I proposed earlier,
> nop ?

That's easy enough, see the attached patch (but I have no opinion on
whether that's desirable right now or not).

                    /L/e/k/t/u

Index: lisp/help-fns.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/help-fns.el,v
retrieving revision 1.94
diff -u -2 -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 13:06:01 -0000
@@ -593,5 +593,7 @@
 			 (format "`%s'.\n" safe-var))))
 	      (princ "\nDocumentation:\n")
-              (princ (or doc "Not documented as a variable.")))
+	      (if doc
+		  (princ (replace-regexp-in-string "^\*" "" doc))
+		(princ "Not documented as a variable.")))
 	    ;; Make a link to customize if this variable can be customized.
 	    (if (custom-variable-p variable)

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

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

Re: defcustom and the stars.

[Michaël Cadilhac]

[-- Attachment #1.1: Type: text/plain, Size: 1002 bytes --]

"Juanma Barranquero" <lekktu@gmail.com> writes:

> On 1/3/07, Michaël Cadilhac <michael@cadilhac.name> wrote:
>
>> So let's consider hiding this star in C-h v, like I proposed earlier,
>> nop ?
>
> That's easy enough, see the attached patch

« Same goals, different tactics :-) ». I used substring :-)

> (but I have no opinion on whether that's desirable right now or
> not).

And what about an opinion on the rest of the patch I proposed in
Message-ID: <877iw4pdyo.fsf@lrde.org> ?

I'm a little confused about that difference between what is a user
variable in the doc and what it is regarding user-variable-p. Maybe
a doc change is also necessary.

-- 
 |      Michaël `Micha' Cadilhac     |  Mieux vaut se taire                   |
 |         Epita/LRDE Promo 2007     |   Que de parler trop fort.             |
 |  http://michael.cadilhac.name     |           -- As de trèfle              |
 `--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

Re: defcustom and the stars.

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 1324 bytes --]

On 1/3/07, Michaël Cadilhac <michael@cadilhac.name> wrote:

> « Same goals, different tactics :-) ». I used substring :-)

Sorry, I didn't see your patch.

> And what about an opinion on the rest of the patch I proposed in
> Message-ID: <877iw4pdyo.fsf@lrde.org> ?

A link to the archives would be helpful.

> I'm a little confused about that difference between what is a user
> variable in the doc and what it is regarding user-variable-p.

I'm not sure what doc are you referring to. In the "Defining Global
Variables" node I see this:

     If the variable is a user option that users would want to set
     interactively, you should use `*' as the first character of
     DOC-STRING.  This lets users set the variable conveniently using
     the `set-variable' command.  Note that you should nearly always
     use `defcustom' instead of `defvar' to define these variables, so
     that users can use `M-x customize' and related commands to set
     them.

I don't see contradiction. Note that you are *not* forced to use
defcustom, so "*docstring" is still relevant. The "*" is only obsolete
in defcustom's docstrings. In my .emacs, for example, I define
variables that sometimes I want to change with M-x set-variable; but
certainly I don't want to use the customize stuff for them.

                    /L/e/k/t/u

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

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

Re: defcustom and the stars.

[Michaël Cadilhac]

[-- Attachment #1.1: Type: text/plain, Size: 1237 bytes --]

"Juanma Barranquero" <lekktu@gmail.com> writes:

> On 1/3/07, Michaël Cadilhac <michael@cadilhac.name> wrote:
>
>> And what about an opinion on the rest of the patch I proposed in
>> Message-ID: <877iw4pdyo.fsf@lrde.org> ?

http://permalink.gmane.org/gmane.emacs.devel/64677

>> I'm a little confused about that difference between what is a user
>> variable in the doc and what it is regarding user-variable-p.
>
> I'm not sure what doc are you referring to. In the "Defining Global
> Variables" node I see this:

Oh, sorry. I was referring to the Emacs info file, the one I see
intended to users. ELisp reference isn't, IMO, to be consulted by
regular users. And the only reference to user variable in this doc is
for customizable vars (AFAICS).

> Note that you are *not* forced to use defcustom, so "*docstring" is
> still relevant.

I do agree, of course. That wasn't my point.

-- 
 |      Michaël `Micha' Cadilhac     |    Le copillage-collage                |
 |         Epita/LRDE Promo 2007     |       tue le programmeur.              |
 |  http://michael.cadilhac.name     |           -- Dictons LRDE              |
 `--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

Re: defcustom and the stars.

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 707 bytes --]

On 1/3/07, Michaël Cadilhac <michael@cadilhac.name> wrote:

> http://permalink.gmane.org/gmane.emacs.devel/64677

Ah, I see. Sorry. I somehow missed that message's attached patch.

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

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

                    /L/e/k/t/u

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

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

Re: defcustom and the stars.

[Michaël Cadilhac]

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

"Juanma Barranquero" <lekktu@gmail.com> writes:

> On 1/3/07, Michaël Cadilhac <michael@cadilhac.name> 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).


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

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

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


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

Re: defcustom and the stars.

[Eli Zaretskii]

> Date: Wed, 3 Jan 2007 14:08:52 +0100
> From: "Juanma Barranquero" <lekktu@gmail.com>
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel@gnu.org
> 
> --- lisp/help-fns.el	17 Dec 2006 22:14:11 -0000	1.94
> +++ lisp/help-fns.el	3 Jan 2007 13:06:01 -0000
> @@ -593,5 +593,7 @@
>  			 (format "`%s'.\n" safe-var))))
>  	      (princ "\nDocumentation:\n")
> -              (princ (or doc "Not documented as a variable.")))
> +	      (if doc
> +		  (princ (replace-regexp-in-string "^\*" "" doc))
> +		(princ "Not documented as a variable.")))
>  	    ;; Make a link to customize if this variable can be customized.
>  	    (if (custom-variable-p variable)

If this change is agreed upon, please explain the
replace-regexp-in-string trick in a comment.

Re: defcustom and the stars.

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 225 bytes --]

On 1/3/07, Eli Zaretskii <eliz@gnu.org> wrote:

> If this change is agreed upon, please explain the
> replace-regexp-in-string trick in a comment.

Michaël's patch already includes a comment.

                    /L/e/k/t/u

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

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

Re: defcustom and the stars.

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 572 bytes --]

On 1/3/07, Michaël Cadilhac <michael@cadilhac.name> wrote:

> So let's give it a try (writing doc is always funny for me as my
> English is far from good).

I'm not very good at judging English docs (and you must have a
masochistic streak: I find writing doc in English very painful
*because* my English is bad :)

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

True ;-)

                    /L/e/k/t/u

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

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

Re: defcustom and the stars.

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 319 bytes --]

On 1/3/07, Michaël Cadilhac <michael@cadilhac.name> wrote:

> So let's give it a try (writing doc is always funny for me as my
> English is far from good).

While you're at it, lispref/customize.texi contains an example of a
defcustom with docstring "*The command to use to run diff.".

                    /L/e/k/t/u

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

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

Re: defcustom and the stars.

[Michaël Cadilhac]

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

"Juanma Barranquero" <lekktu@gmail.com> writes:

> On 1/3/07, Michaël Cadilhac <michael@cadilhac.name> wrote:
>
>> So let's give it a try (writing doc is always funny for me as my
>> English is far from good).
>
> While you're at it

Oh, you know, when a student has to study for a crucial exam, he
founds plenty of time to not work :-)

> lispref/customize.texi contains an example of a defcustom with
> docstring "*The command to use to run diff.".

Good grep :-)

Let's recap the three patches as attachments!

[-- 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: custom.patch --]
[-- Type: text/x-patch, Size: 3108 bytes --]

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

[-- Attachment #1.1.4: customize.patch --]
[-- Type: text/x-patch, Size: 1620 bytes --]

Index: lispref/customize.texi
===================================================================
RCS file: /sources/emacs/emacs/lispref/customize.texi,v
retrieving revision 1.64
diff -c -r1.64 customize.texi
*** lispref/customize.texi	24 Dec 2006 16:36:22 -0000	1.64
--- lispref/customize.texi	3 Jan 2007 21:15:56 -0000
***************
*** 409,415 ****
  
  @example
  (defcustom save-place nil
!   "*Non-nil means automatically save place in each file..."
    :type 'boolean
    :require 'saveplace
    :group 'save-place)
--- 409,415 ----
  
  @example
  (defcustom save-place nil
!   "Non-nil means automatically save place in each file..."
    :type 'boolean
    :require 'saveplace
    :group 'save-place)
***************
*** 461,467 ****
  
  @example
  (defcustom diff-command "diff"
!   "*The command to use to run diff."
    :type '(string)
    :group 'diff)
  @end example
--- 461,467 ----
  
  @example
  (defcustom diff-command "diff"
!   "The command to use to run diff."
    :type '(string)
    :group 'diff)
  @end example
Index: lispref/ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/lispref/ChangeLog,v
retrieving revision 1.802
diff -C0 -r1.802 ChangeLog
*** lispref/ChangeLog	2 Jan 2007 20:58:32 -0000	1.802
--- lispref/ChangeLog	3 Jan 2007 21:16:24 -0000
***************
*** 0 ****
--- 1,6 ----
+ 2007-01-03  Michaël Cadilhac  <michael.cadilhac@lrde.org>
+ 
+ 	* customize.texi (Customization Types): Remove the star
+ 	leading the docstring.
+ 	(Variable Definitions): Ditto.
+ 

[-- Attachment #1.1.5: Type: text/plain, Size: 329 bytes --]

-- 
 |      Michaël `Micha' Cadilhac     |  «Tu aimeras ton prochain.»            |
 |         Epita/LRDE Promo 2007     |    D'abord, Dieu ou pas,               |
 |  http://michael.cadilhac.name     |       j'ai horreur qu'on me tutoie.    |
 `--JID: michael.cadilhac@gmail.com--'           -- P. Desproges         -  --'

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

Re: defcustom and the stars.

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 397 bytes --]

On 1/3/07, Michaël Cadilhac <michael@cadilhac.name> wrote:

> Oh, you know, when a student has to study for a crucial exam, he
> founds plenty of time to not work :-)

Glad to help... :)

> Good grep :-)

Believe it or not, I was actually reading the Customization node in
the Emacs Lisp Reference (I'm simply unable to remember what to put in
these :type specs).

                    /L/e/k/t/u

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

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

Re: defcustom and the stars.

[Richard Stallman]

I fixed customize.texi.  Thanks.

Re: defcustom and the stars.

[Richard Stallman]

    ***************
    *** 832,838 ****
      satisfies the predicate `integerp'.
    =20=20
      Documentation:
    ! *Column beyond which automatic line-wrapping should happen.
      Interactively, you can set the buffer local value using C-x f.
    =20=20
      You can customize this variable.
    =2D-- 832,838 ----
      satisfies the predicate `integerp'.
    =20=20
      Documentation:
    ! Column beyond which automatic line-wrapping should happen.
      Interactively, you can set the buffer local value using C-x f.
    =20=20
      You can customize this variable.

That is incorrect, because the Documentation of fill-column
does include a star at present.

      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.

I can't understand that new text.
What is it supposed to mean?

Re: defcustom and the stars.

[Richard Stallman]

This change

    + 	      ;; If DOC starts with a `*' remove it.
    + 	      (when (eq (aref doc 0) ?*)
    + 		(setq doc (substring doc 1)))

might be ok, but I am not sure it is really right -- it seems
like a hard question.  So I would rather leave this alone, for now.

    ! 	      (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))))))

What is that meant to achieve?
What does the feature look like at user level?

Re: defcustom and the stars.

[Michaël Cadilhac]

[-- Attachment #1.1: Type: text/plain, Size: 3129 bytes --]

Richard Stallman <rms@gnu.org> writes:

>       Documentation:
>     ! *Column beyond which automatic line-wrapping should happen.
>       Interactively, you can set the buffer local value using C-x f.

>       Documentation:
>     ! Column beyond which automatic line-wrapping should happen.
>       Interactively, you can set the buffer local value using C-x f.
>
> That is incorrect, because the Documentation of fill-column
> does include a star at present.

Yes, this is to be read with the change I proposed to remove this `*' in
C-h v.

>       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.
>
> I can't understand that new text.
> What is it supposed to mean?

Again, it is with the previous patch.  With it, not only « You can
customize the variable » can appear, but also « You can change at user
level the variable », which means that you can M-x set-var this var.

Richard Stallman <rms@gnu.org> writes:

> This change
>
>     + 	      ;; If DOC starts with a `*' remove it.
>     + 	      (when (eq (aref doc 0) ?*)
>     + 		(setq doc (substring doc 1)))
>
> might be ok, but I am not sure it is really right -- it seems
> like a hard question.  So I would rather leave this alone, for now.

This is just an eye candy change for C-h v: the user doesn't need this
`*', so let's remove it before printing.  Why would it be a hard
question?

>     ! 	      (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))))))
>
> What is that meant to achieve?
> What does the feature look like at user level?

C-h v propose to change customizable vars ; this patch allows to
change all user option vars from C-h v. It looks like that :

,----[ C-h v show-paren-highlight-openparen RET ]
| show-paren-highlight-openparen is a variable defined in `paren.el'.
| Its value is t
| 
| 
| Documentation:
| Non-nil turns on openparen highlighting when matching forward.
| 
| You can change at user level this variable.
`----

« change » is a hyperlink. Following it is the same as
M-x set-variable RET s-p-h-openparen RET, so leads to:
« Set show-paren-highlight-openparen globally to value: »

-- 
 |      Michaël `Micha' Cadilhac     |  Si les religions etaient aussi tole-  |
 |         Epita/LRDE Promo 2007     |  rantes qu'elles le pretendent, il y   |
 |  http://michael.cadilhac.name     |  a longtemps qu'il n'y en aurait plus  |
 `--JID: michael.cadilhac@gmail.com--'           -- Moustic              -  --'

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

RE: defcustom and the stars.

[Drew Adams]

>     + 	      ;; If DOC starts with a `*' remove it.
>     + 	      (when (eq (aref doc 0) ?*)
>     + 		(setq doc (substring doc 1)))
>
> might be ok, but I am not sure it is really right -- it seems
> like a hard question.  So I would rather leave this alone, for now.

Yes. Here is a doc string I have, for instance.

 "**Completions* window is removed if fewer chars than this are input."

Perhaps vanilla Emacs would never have such a doc string, but why invite
trouble? Why not just leave any extra `*' there? What's the harm?

RE: defcustom and the stars.

[Drew Adams]

> Again, it is with the previous patch.  With it, not only « You can
> customize the variable » can appear, but also « You can change at user
> level the variable », which means that you can M-x set-var this var.

If that's what you mean, then that's what should be said: "You can use
command `set-variable' to change the value". This is confusing: "change at
user level".

> | You can change at user level this variable.
> « change » is a hyperlink. Following it is the same as
> M-x set-variable

I'd rather we just mentioned `set-variable' explicitly, to teach about it.
No need to use `C-h v' each time if you know you want to change the value
and you know about `set-variable'.

"You can change at user level" doesn't teach anything. It says less (because
it is confusing) than just "You can change this variable" (with a link on
"change").

It's actually the value that is changed, so "You can change the value" is
better, but still not as good as "You can use command `set-variable' to
change the value".

Re: defcustom and the stars.

[Juanma Barranquero]

Not to defend modifying describe-variable right now, but this:

> Yes. Here is a doc string I have, for instance.
>
>  "**Completions* window is removed if fewer chars than this are input."

is basically incorrect, in the sense that

  (defvar my-var nil "*Completions* window blah blah.")

is wrong; it makes my-var a user variable, when it isn't intended to.
Seems like a docstring payload (taking out the possible initial "*")
should not start with an asterisk...

                    /L/e/k/t/u

RE: defcustom and the stars.

[Drew Adams]

> Not to defend modifying describe-variable right now, but this:
> 
> > Yes. Here is a doc string I have, for instance.
> >
> >  "**Completions* window is removed if fewer chars than this are input."
> 
> is basically incorrect, in the sense that
> 
>   (defvar my-var nil "*Completions* window blah blah.")
> 
> is wrong; it makes my-var a user variable, when it isn't intended to.
> Seems like a docstring payload (taking out the possible initial "*")
> should not start with an asterisk...

Sorry, I don't understand. The variable with that doc string (beginning "**") _is_ a user variable. It is intended to be a user variable.

You raise, I imagine, a different issue: how to prevent a variable from becoming a user variable (changeable with `set-variable') if its doc string begins with `*', as in your defvar: "*Completions* window blah blah.".

It's possible I misunderstand you. But if that is the issue you want to raise, then I think it is not worth pursuing: people can rephrase the text to avoid starting with `*' if they don't want `*' to indicate a user variable. (In my case, I _do_ want it to indicate a user variable.)

Re: defcustom and the stars.

[Juanma Barranquero]

On 1/4/07, Drew Adams <drew.adams@oracle.com> wrote:

> Sorry, I don't understand. The variable with that doc string (beginning "**") _is_ a user variable. It is intended to be a user variable.

Yes, I know.

> You raise, I imagine, a different issue: how to prevent a variable from becoming a user variable (changeable with `set-variable') if its doc string begins with `*', as in your defvar: "*Completions* window blah blah.".

No, I'm raising the fact that we have a convention that says: a
variable whose docstring starts with "*" is a user variable. So for
consistency, the docstring (without the asterisk) should *not* start
with an asterisk. Otherwise, you have:

  (defvar my-var nil "**This* is a user variable.")

and some day you hurriedly modify it to:

  (defvar my-var nil "*This* is not a user variable.")

and get an unwanted result. I'm not talking about programming now, but
about docstring conventions.

> then I think it is not worth pursuing

Not worth pursuing, how? As a convention, in elisp code, or how exactly?

> people can rephrase the text to avoid starting with `*' if they don't want `*' to indicate a user variable.

Yes, that's what I'm saying, only I'm adding that we should perhaps
explain in the docs: "Please take care the docstring *contents* does
not start with an asterisk."

> (In my case, I _do_ want it to indicate a user variable.)

I understood it the first time. In fact, I understood it on your
previous message. I usually have no trouble understanding your
messages. Pity the reverse is not true. Not your fault, of course.

                    /L/e/k/t/u

RE: defcustom and the stars.

[Drew Adams]

> the docstring (without the asterisk) should *not* start with an
asterisk....
> Otherwise, you have:
>   (defvar my-var nil "**This* is a user variable.")
> and some day you hurriedly modify it to:
>   (defvar my-var nil "*This* is not a user variable.")
> and get an unwanted result.

OK, yes, that is something different from what I wrote about.

I don't see such carelessness as a problem that can or should be cured by
program or convention. If you are saying that anyone who starts a doc string
with two asterisks, and later wants to change the var to a non-user variable
by deleting the leading asterisk, risks forgetting to remove both leading
asterisks, then I would say that that is a problem we should not worry
about.

We should not worry about it because 1) it is unlikely to occur and 2) if it
occurs, the consequences are not great and the effect will be seen soon
enough.

> > people can rephrase the text to avoid starting with `*' if they
> don't want `*' to indicate a user variable.
>
> Yes, that's what I'm saying, only I'm adding that we should perhaps
> explain in the docs: "Please take care the docstring *contents* does
> not start with an asterisk."

I don't think that's necessary, and it could even introduce confusion.

Unless we're worrying about modifying doc strings by program, which you said
you're not talking about here, I don't think there is a problem with saying
only that any doc string that starts with an asterisk indicates a
`set-variable' target.

> > (In my case, I _do_ want it to indicate a user variable.)
>
> I understood it the first time. In fact, I understood it on your
> previous message. I usually have no trouble understanding your
> messages. Pity the reverse is not true. Not your fault, of course.

It could be my fault, or, rather, it is at least partly my responsibility.

When I was 13, my math teacher taught us not to accept anything on guzzle
(i.e. without understanding). What he meant was that if I can't get someone
to understand, then it is mainly my fault: the main burden of teaching is on
the teacher (or arguer, prover), who needs to find some way to get the point
across. His immediate point was about formal proof, but the lesson was a
wider one.

Language is a hard nut to crack, however. Students (like me, here) also need
to try to understand. The burden-of-proof-is-on-the-teacher argument is best
viewed at the level of ideas (logic, arguments), not just at the level of
language.

I.e., I need to try to understand what you are saying, and it is what you
mean that needs to be convincing to me, not just the words you use to convey
it. I will try better to get your meaning.

BTW, I learned from a Japanese user of one of my libraries that Lisp code
can be a good way to get around the English barrier sometimes. Quite a bit
can be communicated using just sexps with end-line comments that indicate
results:

 (toto)    ; => 43
 (foo bar) ; => t (EXPECTED nil)

That's obvious, perhaps, but I never imagined that an entire conversation
could be conducted that way. Lisp cum lingua franca!

Re: defcustom and the stars.

[Michaël Cadilhac]

[-- Attachment #1.1: Type: text/plain, Size: 2331 bytes --]

Hi Drew!

Please, do not remove me from the list of Cc as I don't scrupulously
read Emacs Devel usually.

"Drew Adams" <drew.adams@oracle.com> writes:

>>     + 	      ;; If DOC starts with a `*' remove it.
>>     + 	      (when (eq (aref doc 0) ?*)
>>     + 		(setq doc (substring doc 1)))
>>
>> might be ok, but I am not sure it is really right -- it seems
>> like a hard question.  So I would rather leave this alone, for now.
>
> Yes. Here is a doc string I have, for instance.
>
>  "**Completions* window is removed if fewer chars than this are input."

I don't see your point.  Maybe this has been discussed with Juanma, but
what's the harm removing the first * ?

> Why not just leave any extra `*' there?

Because it's confusing and somewhat useless for the user.

>> Again, it is with the previous patch.  With it, not only « You can
>> customize the variable » can appear, but also « You can change at user
>> level the variable », which means that you can M-x set-var this var.
>
> If that's what you mean, then that's what should be said: "You can use
> command `set-variable' to change the value". This is confusing: "change at
> user level".

> "You can change at user level" doesn't teach anything. It says less (because
> it is confusing) than just "You can change this variable" (with a link on
> "change").

« You can change this variable » can lead the user to think that the
only variables s?he can change are those ones, whereas `setq' can
change nearly everything. But I do agree that « at user level » is
confusing.

What about « You can change this variable using `set-variable' » with
a link on « change » ?

It would show up as:

,----[ C-h v show-paren-highlight-openparen RET ]
| show-paren-highlight-openparen is a variable defined in `paren.el'.
| Its value is t
| 
| 
| Documentation:
| Non-nil turns on openparen highlighting when matching forward.
| 
| You can change this variable using `set-variable'.
`----

-- 
 |      Michaël `Micha' Cadilhac     |  «Tu aimeras ton prochain.»            |
 |         Epita/LRDE Promo 2007     |    D'abord, Dieu ou pas,               |
 |  http://michael.cadilhac.name     |       j'ai horreur qu'on me tutoie.    |
 `--JID: michael.cadilhac@gmail.com--'           -- P. Desproges         -  --'

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

Re: defcustom and the stars.

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 1641 bytes --]

On 1/4/07, Drew Adams <drew.adams@oracle.com> wrote:

> We should not worry about it because 1) it is unlikely to occur

Agreed.

> and 2) if it
> occurs, the consequences are not great

Agreed.

> and the effect will be seen soon enough.

Not agreed (it's not always evident that a variable is a user
variable, unless you look for it).

> Unless we're worrying about modifying doc strings by program, which you said
> you're not talking about here, I don't think there is a problem with saying
> only that any doc string that starts with an asterisk indicates a
> `set-variable' target.

I'm not talking about modifying docstrings by program, right now. But
I think the gist of Michaël's idea is good (for post-22.1): that
describe-variable should remove the asterisk (that's an implementation
artifact, and has no place in documentation), and indicate when a
variable is a user variable; it already says "You can customize this
variable" for defcustoms, doesn't it?

So, it's not only about "**text*..." cases, but also "*text*..." where
the user-variable'ness is unintended.

> I.e., I need to try to understand what you are saying, and it is what you
> mean that needs to be convincing to me, not just the words you use to convey
> it. I will try better to get your meaning.

Well, don't take too seriously my previous comment, please. :)

> That's obvious, perhaps, but I never imagined that an entire conversation
> could be conducted that way. Lisp cum lingua franca!

I'm not surprised Lisp is useful for that. It's the most expressive
programming language I've ever used (and comments do help... :)

                    /L/e/k/t/u

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

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

RE: defcustom and the stars.

[Drew Adams]

Hi Michael,

> Please, do not remove me from the list of Cc as I don't scrupulously
> read Emacs Devel usually.

OK; sorry about that. I know I don't like getting two copies of everything,
so I tend to think others too might want just the list copy. I realize this
is an incorrect assumption.

> > Yes. Here is a doc string I have, for instance.
> >  "**Completions* window is removed if fewer chars than this are input."
>
> I don't see your point.  Maybe this has been discussed with Juanma, but
> what's the harm removing the first * ?

The doc string that the user sees then reads "Completions* window...", which
is not good - the text should say *Completions*.

> > Why not just leave any extra `*' there?
>
> Because it's confusing and somewhat useless for the user.

The user doesn't see the first `*'. How is it confusing to the user?

> What about « You can change this variable using `set-variable' » with
> a link on « change » ?

Yes, that's OK by me.
(<nitpick>Though it's really the value that is changed...</nitpick>)

RE: defcustom and the stars.

[Drew Adams]

> > and the effect will be seen soon enough.
> 
> Not agreed (it's not always evident that a variable is a user
> variable, unless you look for it).

I guess you're right about that. But trying `set-variable' or `customize-option' will point out the problem - that's what I meant.

Wrt your point: That's why I define a command `apropos-option' in one of my libraries. I think we should have commands `apropos-option' and `describe-option', which are limited to user options. Just as we intentionally bind `C-h a' to `apropos-command', not to `apropos', so we would privilege `describe-option' over `describe-variable' in the user doc. We might even want to bind `C-h o' to it, and advertise that instead of (i.e. more than) `C-h v'.

> I'm not talking about modifying docstrings by program, right now. But
> I think the gist of Michaël's idea is good (for post-22.1): that
> describe-variable should remove the asterisk (that's an implementation
> artifact, and has no place in documentation), and indicate when a
> variable is a user variable; it already says "You can customize this
> variable" for defcustoms, doesn't it?

I agree that the first `*' has no place appearing in displayed documentation. I didn't think it did appear to users, but I guess I was mistaken about that. (It should appear in the doc string accessed by programs, however.) I support stripping it from what is shown to the user. I thought this was about "fixing" defcustom doc strings that didn't need an initial `*' by removing it definitively, not just for display. I think I misunderstood the question.

I also agree that `describe-variable' should indicate that an option is an option. I think I said that. I support that change.

> So, it's not only about "**text*..." cases, but also "*text*..." where
> the user-variable'ness is unintended.
> 
> > I.e., I need to try to understand what you are saying, and it 
> > is what you mean that needs to be convincing to me, not just
> > the words you use to convey it. I will try better to get your meaning.
> 
> Well, don't take too seriously my previous comment, please. :)

Not to worry ;-).

Re: defcustom and the stars.

[Richard Stallman]

    >     ! variable is a user option, as would have indicated a line saying th=
    at
    >     ! you can change at user level the variable.  @kbd{C-h v} is not
    >     ! restricted to user options; it allows any variable name.
    >
    > I can't understand that new text.
    > What is it supposed to mean?

    Again, it is with the previous patch.  With it, not only =AB You can
    customize the variable =BB can appear, but also =AB You can change at user
    level the variable =BB, which means that you can M-x set-var this var.

The proposed text (quoted above) doesn't say that clearly.
I find it very hard to understand.

Anyway, my decision is not to add that new feature now.

RE: defcustom and the stars.

[Drew Adams]

I said:

> Wrt your point: That's why I define a command `apropos-option' in 
> one of my libraries. I think we should have commands 
> `apropos-option' and `describe-option', which are limited to user 
> options. Just as we intentionally bind `C-h a' to 
> `apropos-command', not to `apropos', so we would privilege 
> `describe-option' over `describe-variable' in the user doc. We 
> might even want to bind `C-h o' to it, and advertise that instead 
> of (i.e. more than) `C-h v'.

I had forgotten that `apropos-variable' is limited to user options (without `C-u'). My version is different: `apropos-option' is limited to options, and `apropos-variable' gives all vars.

Sorry about this confusion.

RE: defcustom and the stars.

[Stuart D. Herring]

>> Please, do not remove me from the list of Cc as I don't scrupulously
>> read Emacs Devel usually.
>
> OK; sorry about that. I know I don't like getting two copies of
> everything,
> so I tend to think others too might want just the list copy. I realize
> this
> is an incorrect assumption.

Do you actually get two copies of anything (e.g., this)?  AFAIK the list
does not forward copies to people who are named as targets in the original
mail's headers.

Davis

-- 
This product is sold by volume, not by mass.  If it appears too dense or
too sparse, it is because mass-energy conversion has occurred during
shipping.

RE: defcustom and the stars.

[Drew Adams]

> > OK; sorry about that. I know I don't like getting two copies of
> > everything, so I tend to think others too might want just the list
> > copy. I realize this is an incorrect assumption.
>
> Do you actually get two copies of anything (e.g., this)?  AFAIK the list
> does not forward copies to people who are named as targets in the original
> mail's headers.

Yes, I do:

> -----Original Message-----
> From: Stuart D. Herring [mailto:herring@lanl.gov]
> Sent: Thursday, January 04, 2007 2:50 PM
> To: Drew Adams
> Cc: Michaël Cadilhac; emacs-devel@gnu.org
> Subject: RE: defcustom and the stars.

> -----Original Message-----
> From: emacs-devel-bounces+drew.adams=oracle.com@gnu.org
> [mailto:emacs-devel-bounces+drew.adams=oracle.com@gnu.org]On Behalf Of
> Stuart D. Herring
> Sent: Thursday, January 04, 2007 2:50 PM
> To: Drew Adams
> Cc: Michaël Cadilhac; emacs-devel@gnu.org
> Subject: RE: defcustom and the stars.

Re: defcustom and the stars.

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 707 bytes --]

On 1/4/07, Drew Adams <drew.adams@oracle.com> wrote:


> I support stripping it from what is shown to the user.

That's what Michaël proposed, and I agreed.

> I thought this was about "fixing" defcustom doc strings that
> didn't need an initial `*' by removing it definitively, not
> just for display.

Not programmatically, no; though Michaël also talked about removing
them definitely (and slowly: remember the needles) from defcustoms,
*by hand*.

> I also agree that `describe-variable' should indicate that an
> option is an option. I think I said that. I support that change.

Let's try to remember revisiting the issue after the release.

> Not to worry ;-).

Cool.
                    /L/e/k/t/u

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

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

RE: defcustom and the stars.

[Drew Adams]

> > I support stripping it from what is shown to the user.
> 
> That's what Michaël proposed, and I agreed.

I probably just misunderstood.
 
> > I thought this was about "fixing" defcustom doc strings that
> > didn't need an initial `*' by removing it definitively, not
> > just for display.
> 
> Not programmatically, no; though Michaël also talked about removing
> them definitely (and slowly: remember the needles) from defcustoms,
> *by hand*.

I agree with removing them from defcustoms (but not defvars) by hand, progressively. I must have misunderstood.

> > I also agree that `describe-variable' should indicate that an
> > option is an option. I think I said that. I support that change.
> 
> Let's try to remember revisiting the issue after the release.

Re: defcustom and the stars.

[Juanma Barranquero]

On 1/5/07, Drew Adams <drew.adams@oracle.com> wrote:

> I probably just misunderstood.

We were discussing it in the context of `describe-variable'.

> I agree with removing them from defcustoms (but not defvars)

Of course. The asterisk is not obsolete on defvars.

                    /L/e/k/t/u

Re: defcustom and the stars.

[Michaël Cadilhac]

[-- Attachment #1.1: Type: text/plain, Size: 2451 bytes --]

"Drew Adams" <drew.adams@oracle.com> writes:

> Hi Michael,
>
>> Please, do not remove me from the list of Cc as I don't scrupulously
>> read Emacs Devel usually.
>
> OK; sorry about that. I know I don't like getting two copies of everything,
> so I tend to think others too might want just the list copy. I realize this
> is an incorrect assumption.

In fact, I read e-devel through GMane and quickly kill the threads
I take part in.

>> > Yes. Here is a doc string I have, for instance.
>> >  "**Completions* window is removed if fewer chars than this are input."
>>
>> I don't see your point.  Maybe this has been discussed with Juanma, but
>> what's the harm removing the first * ?
>
> The doc string that the user sees then reads "Completions* window...", which
> is not good - the text should say *Completions*.

There must be a misunderstanding here.
(defvar foo nil "**scratch* me I'm famous.")
with the change I proposed now shows

,----[ C-h v foo RET ]
| foo is a variable defined in `~/etc/emacs.d/gnus/News/drafts/drafts/13'.
| Its value is nil
| 
| 
| Documentation:
| *scratch* me I'm famous.
| 
| You can change this variable using `set-variable'.
`----

Only "^\*" is deleted, not "^\**".

>> > Why not just leave any extra `*' there?
>>
>> Because it's confusing and somewhat useless for the user.
>
> The user doesn't see the first `*'. How is it confusing to the user?

Okey, there must be another strong misunderstanding here :-)

$ emacs -Q
C-h v show-paren-highlight-openparen RET

,----[ C-h v show-paren-highlight-openparen RET ]
| show-paren-highlight-openparen is a variable defined in `paren.el'.
| Its value is t
| 
| 
| Documentation:
| *Non-nil turns on openparen highlighting when matching forward.
`----
  ^ Here, there's the useless star. And the user sees it.

>> What about « You can change this variable using `set-variable' » with
>> a link on « change » ?
>
> Yes, that's OK by me.
> (<nitpick>Though it's really the value that is changed...</nitpick>)

« You can change variable's value using `set-variable' » ?

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

RE: defcustom and the stars.

[Drew Adams]

Michael - I misunderstood what you were proposing, and I thought that the
first * was already being removed for display to the user (I didn't notice
it). So, yes, what you want to do is a good idea. Sorry about the confusion.

RE: defcustom and the stars.

[Stuart D. Herring]

>> Do you actually get two copies of anything (e.g., this)?  AFAIK the
list
>> does not forward copies to people who are named as targets in the original
>> mail's headers.
>
> Yes, I do:

How odd!  I didn't get two of your reply, and it quite clearly named me as
To: and the list as Cc:...

I'll attempt to remember not to double-write you, but I don't know how to
mentally keep up with which people are on the list and get doubled (like
you: omit), are on the list and don't (like me: doesn't matter), and which
aren't on the list (like Linus: include).

Davis

-- 
This product is sold by volume, not by mass.  If it appears too dense or
too sparse, it is because mass-energy conversion has occurred during
shipping.

Re: defcustom and the stars.

[Michaël Cadilhac]

[-- Attachment #1.1: Type: text/plain, Size: 979 bytes --]

"Stuart D. Herring" <herring@lanl.gov> writes:

>>> Do you actually get two copies of anything (e.g., this)?  AFAIK the
> list
>>> does not forward copies to people who are named as targets in the original
>>> mail's headers.
>>
>> Yes, I do:
>
> How odd!  I didn't get two of your reply, and it quite clearly named me as
> To: and the list as Cc:...
>
> I'll attempt to remember not to double-write you

I may be Drew's personal problem in fact. He should probably set the
Header « Reply-to » to something that doesn't name him, nop?  But
I don't know if Outlook can do that.

See http://www.ietf.org/rfc/rfc0822.txt of course.

-- 
 |      Michaël `Micha' Cadilhac     |  «Tu aimeras ton prochain.»            |
 |         Epita/LRDE Promo 2007     |    D'abord, Dieu ou pas,               |
 |  http://michael.cadilhac.name     |       j'ai horreur qu'on me tutoie.    |
 `--JID: michael.cadilhac@gmail.com--'           -- P. Desproges         -  --'

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

RE: defcustom and the stars.

[Drew Adams]

> >> Do you actually get two copies of anything (e.g., this)?  AFAIK the
> >> list does not forward copies to people who are named as targets in
> >> the original mail's headers.
> >
> > Yes, I do:
>
> How odd!  I didn't get two of your reply, and it quite clearly named me as
> To: and the list as Cc:...
>
> I'll attempt to remember not to double-write you, but I don't know how to
> mentally keep up with which people are on the list and get doubled (like
> you: omit), are on the list and don't (like me: doesn't matter), and which
> aren't on the list (like Linus: include).

I have no idea what causes two messages to be sent to me (but not to you),
or whether a filter is supposed to prevent that at the mailing-list end. Do
you think this is a bug?

RE: defcustom and the stars.

[Drew Adams]

> >>> Do you actually get two copies of anything (e.g., this)?  AFAIK the
> > list
> >>> does not forward copies to people who are named as targets in
> the original
> >>> mail's headers.
> >>
> >> Yes, I do:
> >
> > How odd!  I didn't get two of your reply, and it quite clearly
> named me as
> > To: and the list as Cc:...
> >
> > I'll attempt to remember not to double-write you
>
> I may be Drew's personal problem in fact. He should probably set the
> Header « Reply-to » to something that doesn't name him, nop?  But
> I don't know if Outlook can do that.

No, you are certainly not one of my personal problems (but "it" might be).
;-)

I don't see a means in Outlook to do that, even for each individual message.
If someone knows a way to configure that generally for mail from a given
mailing list, please share the knowledge.

Re: defcustom and the stars.

[Michaël Cadilhac]

[-- Attachment #1.1: Type: text/plain, Size: 1581 bytes --]

"Drew Adams" <drew.adams@oracle.com> writes:

>> > How odd! I didn't get two of your reply, and it quite clearly
>> > named me as To: and the list as Cc:...
>> >
>> > I'll attempt to remember not to double-write you
>>
>> I may be Drew's personal problem in fact. He should probably set the
>> Header « Reply-to » to something that doesn't name him, nop?  But
>> I don't know if Outlook can do that.
>
> No, you are certainly not one of my personal problems

Not for NOW! :-) Well, I meant « it »

> I don't see a means in Outlook to do that, even for each individual message.
> If someone knows a way to configure that generally for mail from a given
> mailing list, please share the knowledge.

Switch to Gnus (there must be someone in the list to say that).

> I have no idea what causes two messages to be sent to me (but not to you),
> or whether a filter is supposed to prevent that at the mailing-list end. Do
> you think this is a bug?

I think the bug is in Stuart's side :-) You get two copies because:
- One is sent directly to you,
- One is sent to the ML which has the task to send you a copy.

When I was subscribed to the ML (as opposed to reading it in
nntp://gmane), I got two mails too for that case.

-- 
 |      Michaël `Micha' Cadilhac     |  Mieux vaut se taire                   |
 |         Epita/LRDE Promo 2007     |   Que de parler trop fort.             |
 |  http://michael.cadilhac.name     |           -- As de trèfle              |
 `--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

Re: defcustom and the stars.

[Chris Moore]

michael@cadilhac.name (Michaël Cadilhac) writes:

> I think the bug is in Stuart's side :-) You get two copies because:
> - One is sent directly to you,
> - One is sent to the ML which has the task to send you a copy.

I only get one copy of each mail, too.  If I am addressed personally,
I don't get a copy from the list.

Could it be that the list doesn't forward mail to you if it can see
that you're already getting a copy directly?  And could it also be
that when people were mailing you directly, they were using a
different address than the mailing list had for you?

RE: defcustom and the stars.

[Drew Adams]

> Could it be that the list doesn't forward mail to you if it can see
> that you're already getting a copy directly?  

Dunno

> And could it also be
> that when people were mailing you directly, they were using a
> different address than the mailing list had for you?

No. I have only one address.

Re: defcustom and the stars.

[Chris Moore]

"Drew Adams" <drew.adams@oracle.com> writes:

>> Could it be that the list doesn't forward mail to you if it can see
>> that you're already getting a copy directly?  
>
> Dunno
>
>> And could it also be
>> that when people were mailing you directly, they were using a
>> different address than the mailing list had for you?
>
> No. I have only one address.

Interestingly, the address you just used to reply to me isn't signed
up to this mailing list and yet I still only received one copy of your
reply.

Mails to my 'dooglus' email address (which is on the mailing list) get
forwarded to my full.name email address - but there's no way the
mailing list software can know that.

So I think the only explanation is that gmail itself is seeing 2
messages which it determines are 'the same' in some way (maybe by
comparing Message-ID headers, for example) and deciding to only keep
one of them.

If this is what's happening, then it's already OK to CC replies to
people who are using a gmail address, since they'll only see one copy
of the mail anyway.

RE: defcustom and the stars.

[Drew Adams]

> >> Could it be that the list doesn't forward mail to you if it can see
> >> that you're already getting a copy directly?
> >
> > Dunno
> >
> >> And could it also be
> >> that when people were mailing you directly, they were using a
> >> different address than the mailing list had for you?
> >
> > No. I have only one address.
>
> Interestingly, the address you just used to reply to me isn't signed
> up to this mailing list

Huh? Again, I have only one address, so I don't see how I could be signed up
with a different address. My only address is drew.adams@oracle.com. What do
you see me signed up as, and where do you see that? What address do you see
on the mail you receive from me directly?

> and yet I still only received one copy of your reply.
>
> Mails to my 'dooglus' email address (which is on the mailing list) get
> forwarded to my full.name email address - but there's no way the
> mailing list software can know that.
>
> So I think the only explanation is that gmail itself is seeing 2
> messages which it determines are 'the same' in some way (maybe by
> comparing Message-ID headers, for example) and deciding to only keep
> one of them.

I see.

> If this is what's happening, then it's already OK to CC replies to
> people who are using a gmail address, since they'll only see one copy
> of the mail anyway.

Re: defcustom and the stars.

[Chris Moore]

"Drew Adams" <drew.adams@oracle.com> writes:

>> Interestingly, the address you just used to reply to me isn't signed
>> up to this mailing list
>
> Huh? Again, I have only one address,

I wasn't very clear.  I mean that the address which you replied to
isn't signed up to the list.  The list sends to a different account
which is forwarded to the account you replied to.

RE: defcustom and the stars.

[Drew Adams]

> >> Interestingly, the address you just used to reply to me isn't signed
> >> up to this mailing list
> >
> > Huh? Again, I have only one address,
>
> I wasn't very clear.  I mean that the address which you replied to
> isn't signed up to the list.  The list sends to a different account
> which is forwarded to the account you replied to.

Sorry, I still don't get it.  What address did I reply to? Do you mean your
address? And how would the address that I reply to affect any emails that I
receive?

Could you be specific? What are the two different addresses you are
referring to, one that is signed up to the list and the other that I "reply
to". Thx.

Re: defcustom and the stars.

[Chris Moore]

"Drew Adams" <drew.adams@oracle.com> writes:

> Sorry, I still don't get it.  What address did I reply to? Do you
> mean your address? And how would the address that I reply to affect
> any emails that I receive?

I subscribe to this list using email address dooglus@gmail.com.

dooglus@gmail.com is set to forward all incoming mail to
christopher.ian.moore@gmail.com.

I posted a message to this list using the
christopher.ian.moore@gmail.com account.  It had to be manually
approved by the list owner since the sender wasn't subscribed.  You
sent a reply to christopher.ian.moore@gmail.com, and CCed the mailing
list.

The mailing list doesn't know any christopher.ian.moore@gmail.com, so
even if it did try to avoid sending messages to people who were
addressed directly, it wouldn't know not to send me a copy.

But I only received 1 copy of the mail (the one you sent directly to
me; I never received a copy from the list).  There's no reason for the
list not to have sent me a copy, so I can only surmise that gmail.com
saw that the 2 messages it received were the same, and deleted one of
them.

Even when I downloaded mail using POP3, only one copy arrived.

RE: defcustom and the stars.

[Drew Adams]

OK, thx. Now I understand you.