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