customize-apropos

customize-apropos

[Luc Teirlinck]

I believe that there are two things wrong with `customize-apropos'.
Do `M-x customize-apropos RET buffer-menu'.

Note that the buffer contains:

    Buffer-menu-sort-column: Hide Value nil
       State: NO CUSTOMIZATION DATA; you should not see this.

    2 for sorting by buffer names.  5 for sorting by file names. More

I believe that this should not happen.  Variables should not be
included in the customize-apropos output just because their docstring
starts with a `*'.  If a variable should appear in a customization
buffer, one should define it with defcustom.  I believe that this
"feature" is just a remnant from the early days of Custom when barely
any variable had a defcustom.  I do not believe that the whole buffer
"Reset to Current" or "Reset to Saved" whole buffer buttons can handle
this type of options.  (The "Erase Customization" whole buffer button
can handle them: it ignores them, as it should.)

As a side remark, I believe that Buffer-menu-sort-column should either
be defined with defcustom, or (more likely) its docstring should not
start with a `*'.  (Is this variable not purely internal?)

A second problem with customize-apropos is that it can list several
aliases for the same option separately.  That can lead to quite some
confusion, especially if somebody would ever try to use any of these
dubious whole buffer buttons in such a buffer.

The patch below fixes these two problems.  If people absolutely want
to list non-defcustomed variables in the Custom buffer, they still can
after my patch, by giving customize-apropos a numeric argument.

===File ~/cus-edit-diff=====================================
*** cus-edit.el	08 Dec 2005 15:14:58 -0600	1.245
--- cus-edit.el	09 Dec 2005 20:23:10 -0600	
***************
*** 1252,1263 ****
  
  ;;;###autoload
  (defun customize-apropos (regexp &optional all)
!   "Customize all user options matching REGEXP.
  If ALL is `options', include only options.
  If ALL is `faces', include only faces.
  If ALL is `groups', include only groups.
! If ALL is t (interactively, with prefix arg), include options which are not
! user-settable, as well as faces and groups."
    (interactive "sCustomize regexp: \nP")
    (let ((found nil))
      (mapatoms (lambda (symbol)
--- 1252,1263 ----
  
  ;;;###autoload
  (defun customize-apropos (regexp &optional all)
!   "Customize all options, faces and groups matching REGEXP.
  If ALL is `options', include only options.
  If ALL is `faces', include only faces.
  If ALL is `groups', include only groups.
! If ALL is t (interactively, with prefix arg), include variables
! that are not customizable options, as well as faces and groups."
    (interactive "sCustomize regexp: \nP")
    (let ((found nil))
      (mapatoms (lambda (symbol)
***************
*** 1270,1280 ****
  		    (push (list symbol 'custom-face) found))
  		  (when (and (not (memq all '(groups faces)))
  			     (boundp symbol)
  			     (or (get symbol 'saved-value)
  				 (custom-variable-p symbol)
! 				 (if (memq all '(nil options))
! 				     (user-variable-p symbol)
! 				   (get symbol 'variable-documentation))))
  		    (push (list symbol 'custom-variable) found)))))
      (if (not found)
  	(error "No matches")
--- 1270,1280 ----
  		    (push (list symbol 'custom-face) found))
  		  (when (and (not (memq all '(groups faces)))
  			     (boundp symbol)
+ 			     (eq (indirect-variable symbol) symbol)
  			     (or (get symbol 'saved-value)
  				 (custom-variable-p symbol)
! 				 (and (not (memq all '(nil options)))
! 				      (get symbol 'variable-documentation))))
  		    (push (list symbol 'custom-variable) found)))))
      (if (not found)
  	(error "No matches")
***************
*** 1284,1291 ****
  
  ;;;###autoload
  (defun customize-apropos-options (regexp &optional arg)
!   "Customize all user options matching REGEXP.
! With prefix arg, include options which are not user-settable."
    (interactive "sCustomize regexp: \nP")
    (customize-apropos regexp (or arg 'options)))
  
--- 1284,1291 ----
  
  ;;;###autoload
  (defun customize-apropos-options (regexp &optional arg)
!   "Customize all customizable options matching REGEXP.
! With prefix arg, include variables that are not customizable options."
    (interactive "sCustomize regexp: \nP")
    (customize-apropos regexp (or arg 'options)))
  
============================================================

Re: customize-apropos

[Luc Teirlinck]

>From my previous message:

   The patch below fixes these two problems.

I forgot to say that I could, of course, install my patch, if there are
no objections.

Sincerely,

Luc.

Re: customize-apropos

[Kim F. Storm]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> I believe that there are two things wrong with `customize-apropos'.

I can think of another thing:

customize-apropos prompts for "regexp" while all other apropos
commands prompts for "word list or regexp".

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: customize-apropos

[Luc Teirlinck]

Kim Storm wrote:

   Luc Teirlinck <teirllm@dms.auburn.edu> writes:

   > I believe that there are two things wrong with `customize-apropos'.

   I can think of another thing:

   customize-apropos prompts for "regexp" while all other apropos
   commands prompts for "word list or regexp".

All _specialized_ apropos commands prompt for a regexp.

Sincerely,

Luc.

Re: customize-apropos

[Richard M. Stallman]

       customize-apropos prompts for "regexp" while all other apropos
       commands prompts for "word list or regexp".

    All _specialized_ apropos commands prompt for a regexp.

Perhaps we should change them to take args like `apropos',
for consistency.

Re: customize-apropos

[Richard M. Stallman]

    I believe that this should not happen.  Variables should not be
    included in the customize-apropos output just because their docstring
    starts with a `*'.  If a variable should appear in a customization
    buffer, one should define it with defcustom.  I believe that this
    "feature" is just a remnant from the early days of Custom when barely
    any variable had a defcustom.

I agree.  Please install your patch.

Meanwhile, Buffer-menu-sort-column should not be a user variable
at all.  I will fix that.

RE: customize-apropos

[Drew Adams]

    Variables should not be included in the customize-apropos output
    just because their docstring starts with a `*'.  If a variable
    should appear in a customization buffer, one should define it
    with defcustom.

    The patch below fixes these two problems.  If people absolutely want
    to list non-defcustomed variables in the Custom buffer, they still can
    after my patch, by giving customize-apropos a numeric argument.

Your doc-string changes correctly reflect the current prefix-arg behavior -
the arg distinguishes customizable variables from other variables. However,
wouldn't it also be useful to be able to distinguish all user variables
(options) - whether customizable or not - from internal variables?

We have 3 sets of vars:

1. customizable user options - defined with defcustom.

2. non-customizable user options - defined with defvar, with * as first
doc-string char.

3. internal variables - defined with defvar, with no * starting doc string

The prefix arg currently distinguishes #1 from (#2 union #3). That can be
useful, but it can also be useful to distinguish variables designed to be
changed by users from those intended to be used internally: (#1 union #2) vs
#3.

I agree that customize-* commands should show customize stuff by default and
extra stuff, if at all, via prefix arg. But I think that a user will often
be more interested in seeing all user options than all variables, so some
means of showing #1 union #2 would be good to have.

Re: customize-apropos

[Luc Teirlinck]

Drew Adams wrote:

   Your doc-string changes correctly reflect the current prefix-arg behavior -
   the arg distinguishes customizable variables from other variables. However,
   wouldn't it also be useful to be able to distinguish all user variables
   (options) - whether customizable or not - from internal variables?

Yes, but is it useful to have them in a Custom buffer?

M-x apropos-variable will show all (loaded) user-options (defined with
defcustom or docstring starting with a `*') and with a numeric arg it
shows all variables.  Of course, it will not show them in a Custom buffer.

Sincerely,

Luc.

RE: customize-apropos

[Drew Adams]

       Your doc-string changes correctly reflect the current
       prefix-arg behavior -
       the arg distinguishes customizable variables from other
       variables. However,
       wouldn't it also be useful to be able to distinguish all
       user variables
       (options) - whether customizable or not - from internal variables?

    Yes, but is it useful to have them in a Custom buffer?

    M-x apropos-variable will show all (loaded) user-options (defined with
    defcustom or docstring starting with a `*') and with a numeric arg it
    shows all variables.  Of course, it will not show them in a
    Custom buffer.

I see your point, I think. But wouldn't it be at least as useful to be able
to show all user options (i.e., including those that are not customizable)
in a Custom buffer as it is to show _all_ variables in a Custom buffer
(i.e., including those that a user should not change)? IOW, your argument is
really an argument for not showing anything in a Custom buffer that is not
customizable. That might be reasonable, but it is not the current policy.

If we keep the current policy of showing stuff that cannot be customized,
then it would also be good to clearly indicate when a user option cannot be
customized and when a variable is internal and should not be changed. That
is, clearly distinguish the three classes in a Custom buffer. I believe
that, currently, user-settable user options that are not customizable are
indistinguisable from internal variables in a Custom buffer.

Instead of saying just "NO CUSTOMIZATION DATA; you should not see this"
(which is what I see, in a CVS snapshot from June), a user option should be
labeled as such, with, for example, a message/label such as "You cannot
customize this option, but you can set it with command `set-variable'. That
might be somewhat confusing, but it is more helpful than what is displayed
currently.

Re: customize-apropos

[Luc Teirlinck]

Drew Adams wrote:

   IOW, your argument is really an argument for not showing anything
   in a Custom buffer that is not customizable. That might be
   reasonable, but it is not the current policy.

I believe that it _is_ the current policy not to show any variable in
a Custom buffer that is not defined with defcustom.  That is exactly
why I installed my patch to customize-apropos.  The numeric argument
is just a way for a super-sophisticated user to override that policy.
I personally do not care about that numeric argument.  I just kept it
because it was there.  I would not have put it in myself.

   Instead of saying just "NO CUSTOMIZATION DATA; you should not see this"
   (which is what I see, in a CVS snapshot from June), a user option should be
   labeled as such, with, for example, a message/label such as "You cannot
   customize this option, but you can set it with command `set-variable'. That
   might be somewhat confusing, but it is more helpful than what is displayed
   currently.

No.  People should _really_ not see this, unless for some (strange)
reason they very explicitly asked for it.  The message is intended for
two kinds of people: the average user and the person who wrote a
defcustom and checks his work.  The "you should not see this" tells
the average person to stay away from it and, if he saw it without
doing anything unusual, file a bug report.  It tells the programmer
that there is a bug in his defcustom.

Your suggested replacement text is incorrect.  If you really know what
you are doing, you _can_, up to a point, customize these variables in
the Custom buffer.  Since some things will work and others not, I
would definitely not recommend this for the average user.  I also
believe that the usefulness of this feature for advanced users is
limited.  I have never used it except out of curiosity.

Sincerely,

Luc.

RE: customize-apropos

[Drew Adams]

       IOW, your argument is really an argument for not showing anything
       in a Custom buffer that is not customizable. That might be
       reasonable, but it is not the current policy.

    I believe that it _is_ the current policy not to show any variable in
    a Custom buffer that is not defined with defcustom.  That is exactly
    why I installed my patch to customize-apropos.  The numeric argument
    is just a way for a super-sophisticated user to override that policy.
    I personally do not care about that numeric argument.  I just kept it
    because it was there.  I would not have put it in myself.

Use of the numeric argument was precisely the point in question. Yes,
without the argument variables in Custom are customizable. But current
policy also shows non-customizable variables if you use the numeric arg.
That's the point under discussion - like it or not, that's the current
policy.

       Instead of saying just "NO CUSTOMIZATION DATA; you should
       not see this" (which is what I see, in a CVS snapshot
       from June), a user option should be labeled as such, with,
       for example, a message/label such as "You cannot
       customize this option, but you can set it with command
       `set-variable'. That might be somewhat confusing, but it
       is more helpful than what is displayed currently.

    No.  People should _really_ not see this, unless for some (strange)
    reason they very explicitly asked for it.  The message is intended for
    two kinds of people: the average user and the person who wrote a
    defcustom and checks his work.  The "you should not see this" tells
    the average person to stay away from it and, if he saw it without
    doing anything unusual, file a bug report.  It tells the programmer
    that there is a bug in his defcustom.

What do you mean by "some (strange) reason"? If we allow the numeric-arg
behavior, then we allow non-customizable stuff to be shown - that's current
policy, strange or not. If we allow numeric-arg behavior, then we want to
inform people that they cannot (or should not - see below) customize it (in
Custom). I think we agree so far (?). Where we disagree, I think, is whether
we should tell people how they _can_ change such non-defcustom options. I
think we should mention `set-variable'; you do not.

    Your suggested replacement text is incorrect.  If you really know what
    you are doing, you _can_, up to a point, customize these variables in
    the Custom buffer.

I take your word for it (but tell me how; I'm curious). Change my use of
"cannot" to "should not" in that case: these are variables that we do not
want people to try to change using Customize, right? Do we agree that Custom
buffers are not _intended_ for changing non-customizable user variables
(sorry, I mean variables not defined with defcustom).

    Since some things will work and others not, I
    would definitely not recommend this for the average user.

Not recommend what? Trying to partially customize non-defcustom stuff? Or
using the numeric arg with customize-apropos to display non-defcustom vars?

    I also believe that the usefulness of this feature for advanced users is
    limited.  I have never used it except out of curiosity.

I'm not clear on which feature you're referring to. The numeric-arg feature?
If so, I have no problem with getting rid of it. But there should be some
way for users to get the list of all user variables (defcustom or not) - do
you want another command?

And it would be preferable for those user vars that are customizable to be
shown in a Custom-buffer context, for easy customization. Would you prefer a
separate command that did both of these things? 1) showed the matching
defcustom vars in a Custom buffer, 2) listed the matching non-defcustom vars
in a *Help* buffer, with their descriptions and an intro sentence saying
that you can change them with `set-variable'. I would prefer just using
Custom and putting the message about `set-variable' there, next to each non-
defcustom var.

Re: customize-apropos

[Luc Teirlinck]

Drew Adams wrote:

   But current policy also shows non-customizable variables if you use
   the numeric arg.

I have already told you: this is not a policy, but a way to _override_
a policy.  The _default_ behavior (no numeric arg) is the policy.  (If
not, Richard can correct me.)  I kept the numeric arg just so if
anybody, for any reason whatsoever, had gotten used to it, they would
still be able to use it (although I seriously doubt that this applies
to a lot of people).  That numeric argument is an *obscure unimportant
detail*.  Let us just stop worrying about it.

       Your suggested replacement text is incorrect.  If you really know what
       you are doing, you _can_, up to a point, customize these variables in
       the Custom buffer.

   I take your word for it (but tell me how; I'm curious).

Just use the State button and then Set or Save.  Both work.

       I also believe that the usefulness of this feature for advanced users is
       limited.  I have never used it except out of curiosity.

   I'm not clear on which feature you're referring to.

The feature that you can customize any variable defined with defvar
(with or without leading `*') in a Custom buffer (although not all
usual features will work).

We are discussing the obscure fringes of Custom now.  It do not
believe that it is not worth spending a lot of time on this.

Sincerely,

Luc.

RE: customize-apropos

[Drew Adams]

       But current policy also shows non-customizable variables if you use
       the numeric arg.

    I have already told you: this is not a policy, but a way to _override_
    a policy.  The _default_ behavior (no numeric arg) is the policy.  (If
    not, Richard can correct me.)

Well, excuse me, but it is I who first used the term "current policy" in
this context - what _I_ meant was "current behavior". Whether or not you or
Richard considers the current numeric-argument behavior to be "the policy"
is irrelevant to my meaning. The context of my use of the term "current
policy" made it clear that I was referring to the numeric-argument behavior.

    I kept the numeric arg just so if
    anybody, for any reason whatsoever, had gotten used to it, they would
    still be able to use it (although I seriously doubt that this applies
    to a lot of people).  That numeric argument is an *obscure unimportant
    detail*.  Let us just stop worrying about it.

Why you kept it is irrelevant at this point also - if the behavior exists,
people can use it, and some will. _You_ went to the trouble of changing the
doc strings to clarify this "*obscure unimportant detail*". Why did you
bother? I, for one, am glad you did.

I return to my original question:

  "Wouldn't it be at least as useful to be able to show all user options
  (i.e., including those that are not customizable) in a Custom buffer
  as it is to show _all_ variables in a Custom buffer (i.e., including
  those that a user should not change)?

  If we keep the current [behavior] of showing stuff that cannot be
  customized, then it would also be good to clearly indicate when a
  user option [is not a defcustom option] and when a variable is
  internal and should not be changed. That is, clearly distinguish
  the three classes in a Custom buffer.

For "not customizable" and "cannot be customized", read "not defined with
defcustom".

Re: customize-apropos

[Luc Teirlinck]

Drew Adams wrote:

   I'm not clear on which feature you're referring to. The numeric-arg feature?
   If so, I have no problem with getting rid of it. But there should be some
   way for users to get the list of all user variables (defcustom or not) - do
   you want another command?

apropos-variable.

Sincerely,

Luc.

Re: customize-apropos

[Luc Teirlinck]

>From my previous message:

   We are discussing the obscure fringes of Custom now.  It do not
   believe that it is not worth spending a lot of time on this.

Oh no!  The pitfalls of double negation!  I meant:

   We are discussing the obscure fringes of Custom now.  It do not
   believe that it is worth spending a lot of time on this.

Sincerely,

Luc.

Re: customize-apropos

[Richard M. Stallman]

    I believe that it _is_ the current policy not to show any variable in
    a Custom buffer that is not defined with defcustom.

Not completely.  customize-variable will do so, if you specify such a
variable.  (You have to enter the argument with C-M-c, though, since
it is not a valid completion.)

I think it is fine for customize-apropos to have an option to include
non-custom variables.  We should not delete that featurelet.

       Instead of saying just "NO CUSTOMIZATION DATA; you should not see this"
       (which is what I see, in a CVS snapshot from June), a user option should be
       labeled as such, with, for example, a message/label such as "You cannot
       customize this option, but you can set it with command `set-variable'.

We might want to change that text, because it seems to suggest there
was a bug.  If it is unusual and occurs only after a special request,
that message is too alarming to fit the situation.

Re: customize-apropos

[Luc Teirlinck]

Richard Stallman wrote:

   We might want to change that text, because it seems to suggest there
   was a bug.  If it is unusual and occurs only after a special request,
   that message is too alarming to fit the situation.

What about the following (the text can barely be any longer than the
string below, or it would look very bad in the Custom buffer):

NO CUSTOMIZATION DATA; use only if you know what you are doing.

I can install this if desired.

Sincerely,

Luc.

RE: customize-apropos

[Drew Adams]

       We might want to change that text, because it seems to suggest there
       was a bug.  If it is unusual and occurs only after a special request,
       that message is too alarming to fit the situation.

    What about the following (the text can barely be any longer than the
    string below, or it would look very bad in the Custom buffer):

    NO CUSTOMIZATION DATA; use only if you know what you are doing.

I probably shouldn't jump in here, but that text tells me nothing, except to
stay away from the option in question. What's the point of scaring people?
If this is truly dangerous, then we shouldn't show it. If we show it, then
it's for people to use, not to shun.

Re: customize-apropos

[Luc Teirlinck]

Drew Adams wrote:

   I probably shouldn't jump in here, but that text tells me nothing,
   except to stay away from the option in question.

That is what it tells you _if_ you do not know what you are doing.
What else do you believe people should be doing if they did not
_deliberately_ want to override the usual Custom safeguards, but got
to see these options by accident (presumably through a bug)?

   If this is truly dangerous, then we shouldn't show it.

By default, we do not show it.

   If this is truly dangerous, then we shouldn't show it.

It is not necessarily dangerous if you know what you are doing.

Sincerely,

Luc.

RE: customize-apropos

[Drew Adams]

       I probably shouldn't jump in here, but that text tells me nothing,
       except to stay away from the option in question.

    That is what it tells you _if_ you do not know what you are doing.
    What else do you believe people should be doing if they did not
    _deliberately_ want to override the usual Custom safeguards, but got
    to see these options by accident (presumably through a bug)?

       If this is truly dangerous, then we shouldn't show it.

    By default, we do not show it.

       If this is truly dangerous, then we shouldn't show it.

    It is not necessarily dangerous if you know what you are doing.

This message is shown if someone does `C-u M-x customize-apropos' - that's
what we're discussing, right? So, you're saying that someone who does that
either must "know what he is doing" and not need and not want to know how to
change the options he explicitly asked to see, or he doesn't "know what he
is doing" and so should be scared away.

Is that a fair characterization of your position? To me, it is reasonable in
that context to remind people that they can use M-x set-variable to change a
non-defcustom user option. I wouldn't even want to scare people for internal
variables; I'd just tell them that the variable is not intended to be
changed by users. That may be what you intended, but the language you used
is too strong for that purpose.

Reminding people how to change a non-defcustom user option and reminding
them not to change internal variables is more useful than just telling them
"use only if you know what you are doing". Besides, this is not about
_using_ the variable ("use only if"); it is about changing its value.

Re: customize-apropos

[Luc Teirlinck]

   This message is shown if someone does `C-u M-x customize-apropos' - that's
   what we're discussing, right?

Yes.  Actually, it is shown in four situations:

1. As a result of a bug in some code.  (This is by far the most likely
   situation)

2. If somebody uses C-M-c in the minibuffer (RET or C-j will not work)
   to get around the minibuffer completion functions which are
   designed to prevent such variables from being shown in a Custom
   buffer, unless the user is savvy enough to know how to override
   these completion functions.

3. If the user calls M-x customize-variable or friends from Lisp
   instead of interactively, again in an attempt to override the
   completion functions.

4. If somebody uses an obscure numeric arg, meant for expert users, to
   customize-apropos.

These are all marginal situations.  We are talking about some very
marginal aspect of Custom here, that is only going to be used
_intentionally_ by experts.

Sincerely,

Luc.

RE: customize-apropos

[Drew Adams]

      This message is shown if someone does `C-u M-x
      customize-apropos' - that's what we're discussing, right?

    Yes.  Actually, it is shown in four situations:

    1. As a result of a bug in some code.  (This is by far the most likely
       situation)

    2. If somebody uses C-M-c in the minibuffer (RET or C-j will not work)
       to get around the minibuffer completion functions which are
       designed to prevent such variables from being shown in a Custom
       buffer, unless the user is savvy enough to know how to override
       these completion functions.

    3. If the user calls M-x customize-variable or friends from Lisp
       instead of interactively, again in an attempt to override the
       completion functions.

    4. If somebody uses an obscure numeric arg, meant for expert users, to
       customize-apropos.

    These are all marginal situations.  We are talking about some very
    marginal aspect of Custom here, that is only going to be used
    _intentionally_ by experts.

Using a documented `C-u' with a standard command is not some bizarre expert
behavior. If this is not intended for users, then let's get rid of the `C-u'
option. I vote to keep it and clarify the Custom-buffer messages
accordingly, but if people think this `C-u' behavior is something for
experts only, then let's get rid of it.

The other cases might well correspond to a message such as you have
provided. It's unfortunate to lump together a message that responds to
obscure bugs ("the most likely situation") with a message that responds to a
user's `C-u'.

Re: customize-apropos

[Luc Teirlinck]

Drew Adams wrote:

   Using a documented `C-u' with a standard command is not some bizarre expert
   behavior. If this is not intended for users, then let's get rid of the `C-u'
   option. I vote to keep it and clarify the Custom-buffer messages
   accordingly, but if people think this `C-u' behavior is something for
   experts only, then let's get rid of it.

Because you can use a prefix arg does not mean that you have to use
it.  Would the following patch help clear up your misconceptions?

===File ~/cus-edit-diff=====================================
*** cus-edit.el	12 Dec 2005 21:36:47 -0600	1.247
--- cus-edit.el	13 Dec 2005 23:54:56 -0600	
***************
*** 1257,1263 ****
  If ALL is `faces', include only faces.
  If ALL is `groups', include only groups.
  If ALL is t (interactively, with prefix arg), include variables
! that are not customizable options, as well as faces and groups."
    (interactive "sCustomize regexp: \nP")
    (let ((found nil))
      (mapatoms (lambda (symbol)
--- 1257,1265 ----
  If ALL is `faces', include only faces.
  If ALL is `groups', include only groups.
  If ALL is t (interactively, with prefix arg), include variables
! that are not customizable options, as well as faces and groups.
! \(In most situations, using `apropos-variable', with or without
! prefix arg, is more useful than using a prefix arg for this function.)"
    (interactive "sCustomize regexp: \nP")
    (let ((found nil))
      (mapatoms (lambda (symbol)
***************
*** 1285,1291 ****
  ;;;###autoload
  (defun customize-apropos-options (regexp &optional arg)
    "Customize all loaded customizable options matching REGEXP.
! With prefix arg, include variables that are not customizable options."
    (interactive "sCustomize regexp: \nP")
    (customize-apropos regexp (or arg 'options)))
  
--- 1287,1294 ----
  ;;;###autoload
  (defun customize-apropos-options (regexp &optional arg)
    "Customize all loaded customizable options matching REGEXP.
! With prefix arg, include variables that are not customizable options.
! \(In most situations, using `apropos-variable', with or without
! prefix arg, is more useful than using a prefix arg for this function.)"
    (interactive "sCustomize regexp: \nP")
    (customize-apropos regexp (or arg 'options)))
============================================================

RE: customize-apropos

[Drew Adams]

       Using a documented `C-u' with a standard command is not some
       bizarre expert behavior. If this is not intended for users,
       then let's get rid of the `C-u' option. I vote to keep it
       and clarify the Custom-buffer messages accordingly, but if
       people think this `C-u' behavior is something for
       experts only, then let's get rid of it.

    Because you can use a prefix arg does not mean that you have to use
    it.  Would the following patch help clear up your misconceptions?

You tell me. It is you who defines my "misconceptions". A new variant of
"Have you finally stopped beating your wife"?

Wrt the doc and C-u behavior - are we now in the game of "You can do this;
DON'T do it!!"? If so, I have nothing special to offer on how best to say
that. I would suggest, instead, to pick one or the other. Experts don't need
this (C-u) any more than regular users.

Re: customize-apropos

[Luc Teirlinck]

Drew Adams wrote:

   Wrt the doc and C-u behavior - are we now in the game of "You can do this;
   DON'T do it!!"? If so, I have nothing special to offer on how best to say
   that. I would suggest, instead, to pick one or the other. Experts don't need
   this (C-u) any more than regular users.

Richard decided to keep the numeric arg.  That is fine with me.  If
Richard changes his mind and decides to get rid of it, that is fine
with me too.  I do not care either way.  That numeric arg has been
around for quite some time and maybe somebody might have gotten used
to it.  In as far as I am concerned, that is the main argument for
keeping it.

I do not believe that the numeric arg is really useful (it is just a
confusing alternative to apropos-variable), but it does no real harm
either.  Unless somebody uses it for no other reason that they do not
know about apropos-variable.  That is why I proposed my patch pointing
out in the docstrings that in most cases using `apropos-variable' is
more useful than using the numeric arg to `customize-apropos'.

If Richard believes that this patch is a good idea, I will install
it.  Otherwise, we can just leave everything as it is right now.

Sincerely,

Luc.

RE: customize-apropos

[Drew Adams]

    I do not believe that the numeric arg is really useful (it is just a
    confusing alternative to apropos-variable), but it does no real harm
    either.  Unless somebody uses it for no other reason that they do not
    know about apropos-variable.  That is why I proposed my patch pointing
    out in the docstrings that in most cases using `apropos-variable' is
    more useful than using the numeric arg to `customize-apropos'.

One big difference between `customize-apropos-options' and
`apropos-variable' is that the former puts you in a Custom buffer, where you
can customize options and easily navigate (browse). Even if someone wants to
_see_ all matching variables, (s)he might still want to browse or customize
some customizable user options. Plus, Custom is intended to present a more
"user-friendly" face for option names, values, and value descriptions (I
won't go to the death defending the current implementation of that feature,
however).

So, I cannot agree that "in most cases using `apropos-variable' is more
useful." It is, in most use cases, _less_ useful. Everything that
`apropos-variable' gives you, `customize-apropos-options' (with prefix arg)
gives you too. And the latter gives you more, and in a more digestible
format (that's the intention, anyway).

My point was not to get rid of the C-u behavior - it was to get rid of it
_IF_ the only acceptable (to you and RMS) alternative is an end-user
description that is confusing or frightening. Fixing the language is the
other alternative.

I said: "Experts don't need this (C-u) any more than regular users."

Equivalent: Regular users need this (C-u) just as much as expert users.
Casting the C-u behavior as an expert-user feature is wrong, IMO.

The alternatives I proposed are: get rid of the C-u behavior _OR_ fix the
descriptions of non-defcustom variables, so they don't confuse and frighten.

Richard's latest proposal of wording is this:

  "NO CUSTOMIZATION DATA; set this only if you know what you are doing."

I feel that "if you know what you are doing" is confusing, unhelpful, and
frightening. Might as well say "Don't set this!" - those who do know what
they're doing will presumably know enough to ignore that admonition.

_I_ don't know what "if you know what you are doing" means (how does one
know whether one knows? what's the secret key?), so I must assume that I
don't know what I'm doing. Fair enough, I won't set the option in Custom -
but I won't learn anything about why not or about how I might legitimately
set it (`set-variable').

I will get the (false) impression that setting that option is something only
for THOSE WHO KNOW (and know that they know). And I will have no idea how to
become a member of those-who-know. I will come away thinking that Emacs is
indeed mysterious and Custom is not something for the faint of heart. I will
wonder why, if people should not set those options, setting them was
presented as a possibility (instead of simply getting rid of the State
button or editable Value field). I'll begin to wonder about a lot of things
Custom, in fact.

If we cannot distinguish the problematic (bug) cases (which Luc listed) and
the internal-variable cases from the non-defcustom user-option cases (`*' in
doc string), then I guess we are stuck with language such as that Richard
proposed.

But a better solution would be to distinguish those cases, and tell people,
in the user-option case, that they can use `set-variable' - nothing to fear
here, nothing esoteric.  For a non-defcustom user option, we could even
provide a link that called `set-variable' directly. IOW, it's better to
reserve the less-informative, more frightening language for the bug and
internal-variable cases. Better still would be to remove the State button
from variables whose value should not be changed in Custom - experts have
other ways to change them.

And, as I mentioned near the beginning of this thread, it is at least as
useful to be able to show all _user options_ (no internal variables) as it
is to show all variables (current C-u behavior). If we offered that (e.g.
via C-u `customize-apropos-options' or via `customize-apropos-variables'),
and we got rid of some of the bug cases, and we distinguished the
`set-variable' user options, then we would have no scary, abracadabra,
secret-cult language at all.

If this is too much to ask before the release, consider this a prelude to
Customize discussions to come after the release. That beast sorely needs to
be tamed.

Re: customize-apropos

[Richard M. Stallman]

Please let's stop arguing about this numeric argument.
The argument is a distraction, especially for those who
participate in it.

Re: customize-apropos

[Luc Teirlinck]

Drew Adams wrote:
   
   Besides, this is not about _using_ the variable ("use only if"); it
   is about changing its value

You should look at that text in a Custom buffer.

The text occurs _next to the State button_.  "Use only if" refers to
the State button.

Sincerely,

Luc.

RE: customize-apropos

[Drew Adams]

       Besides, this is not about _using_ the variable ("use only if"); it
       is about changing its value

    You should look at that text in a Custom buffer.

I have.

    The text occurs _next to the State button_.  "Use only if" refers to
    the State button.

OK, but the text is a bit ambiguous. In spite of its position in the buffer,
I misinterpreted it. IOW, the text could be clearer: "Change the value only
if..." or "Change the state only if..."

Re: customize-apropos

[Richard M. Stallman]

    What about the following (the text can barely be any longer than the
    string below, or it would look very bad in the Custom buffer):

    NO CUSTOMIZATION DATA; use only if you know what you are doing.

That's a good approach.  I think this variation

    NO CUSTOMIZATION DATA; set this only if you know what you are doing.

is better, because it avoids an overly broad interpretation of the
warning.  There is no harm in using the customization buffer in any
way except to set the variable.

So please install that.


    The text occurs _next to the State button_.  "Use only if" refers to
    the State button.

Actually, that isn't clear.  "NO CUSTOMIZATION DATA" refers to the
variable, not to the State button.  Thus, "use" seems to refer
to the variable, not to the State button.

Changing "use" to "set this" confirms that it refers to the variable,
removing any uncertainty, and thus prevents misunderstandings.

Re: customize-apropos

[Luc Teirlinck]

Richard Stallman wrote:

       NO CUSTOMIZATION DATA; set this only if you know what you are doing.

   is better, because it avoids an overly broad interpretation of the
   warning.  There is no harm in using the customization buffer in any
   way except to set the variable.

Not quite.  Saving and especially various forms of resetting give more
problems that the (actually relatively problem free) setting for the
current session.  What else is there?

I now believe that a better string would be:

    NO CUSTOMIZATION DATA; not intended to be customized.

I believe that this best summarizes the two involved problems.

Setting, saving and resetting _to current_ work perfectly.  The two
only problems are:

Firstly, there are some problems with the other reset operations,
because of a lack of customization data.  The first part of the
message points that out.

Secondly, by using defvar instead of defcustom, a programmer indicates
his belief that setting this variable through Custom is not advisable,
either because he considers the variable to be internal (no * in
docstring) or because he believes that setting the default value (as
opposed to buffer local values) makes no sense (* in docstring, no
defcustom).  The second part of my new proposed message points that
out to the user.

I do not believe that there are any other problems.  (But these two,
especially the second, are bad enough.)

Sincerely,

Luc.

Re: customize-apropos

[Richard M. Stallman]

	   NO CUSTOMIZATION DATA; set this only if you know what you are doing.

       is better, because it avoids an overly broad interpretation of the
       warning.  There is no harm in using the customization buffer in any
       way except to set the variable.

    Not quite.  Saving and especially various forms of resetting give more
    problems that the (actually relatively problem free) setting for the
    current session.

That doesn't make my words wrong.  Saving is something you can only do
if you set the variable.

    I now believe that a better string would be:

	NO CUSTOMIZATION DATA; not intended to be customized.

That is a good idea.

Re: customize-apropos

[Luc Teirlinck]

Richard Stallman wrote:

       I now believe that a better string would be:

	   NO CUSTOMIZATION DATA; not intended to be customized.

   That is a good idea.

Installed.

Sincerely,

Luc.