doc problems with defcustom

doc problems with defcustom

[Werner LEMBERG]

[CVS 2004-05-30]

Neither in emacs.info nor elisp.info it is described how to customize
a variable defined with defcustom in a non-interactive way, this is,
how to configure it the `.emacs' file instead of using the `customize'
feature -- at least there isn't a link from the defcustom description
to such a place if it exists.

For example, I would like to make my users add `CJKinclude' to
reftex-include-file-commands, defined in reftex-vars.el.  For me, the
easiest way is to write

  (add-to-list 'reftex-include-file-commands "CJKinclude")

in `.emacs' (and this is what I recommend my users).

If such a solution is deprecated or should be avoided, please say so
in the documentation.


    Werner

Re: doc problems with defcustom

[Miles Bader]

Werner LEMBERG <wl@gnu.org> writes:
> Neither in emacs.info nor elisp.info it is described how to customize
> a variable defined with defcustom in a non-interactive way, this is,
> how to configure it the `.emacs' file instead of using the `customize'
> feature

Perhaps that's because it's the same as it has always been -- just use
setq, or add-to-list, or whatever you like.
Werner LEMBERG <wl@gnu.org> writes:

> For me, the easiest way is to write
>
>   (add-to-list 'reftex-include-file-commands "CJKinclude")
>
> in `.emacs' (and this is what I recommend my users).

That should be fine.

Actually for lists, customize's behavior is kind of non-optimal anyway,
because one can't just _add_ to a list with customize, you have to
explicitly set the whole thing, which can interact badly with upgrades
&c.

Personally I use a mixture of explicit .emacs settings and customize,
whatever is most convenient for the task at hand (for complicated data
structures, customize can be nice because it often provides little
mini-editors for the data structure).

-Miles
-- 
"Though they may have different meanings, the cries of 'Yeeeee-haw!' and
 'Allahu akbar!' are, in spirit, not actually all that different."

Re: doc problems with defcustom

[Werner LEMBERG]

> > Neither in emacs.info nor elisp.info it is described how to
> > customize a variable defined with defcustom in a non-interactive
> > way, this is, how to configure it the `.emacs' file instead of
> > using the `customize' feature
> 
> Perhaps that's because it's the same as it has always been -- just
> use setq, or add-to-list, or whatever you like.

I think it would be a good idea to mention this somewhere...


    Werner

Re: doc problems with defcustom

[Kim F. Storm]

Werner LEMBERG <wl@gnu.org> writes:

> > > Neither in emacs.info nor elisp.info it is described how to
> > > customize a variable defined with defcustom in a non-interactive
> > > way, this is, how to configure it the `.emacs' file instead of
> > > using the `customize' feature
> > 
> > Perhaps that's because it's the same as it has always been -- just
> > use setq, or add-to-list, or whatever you like.
> 
> I think it would be a good idea to mention this somewhere...

It should mention that it is not always safe to do this.

There are some defcustom variables which have no (or incorrect) effect
if you set them with setq -- such variables typically have a :set
action which must be called for the setting to take effect.

For example pc-selection-mode and global-reveal-mode.

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

Re: doc problems with defcustom

[Juanma Barranquero]

> There are some defcustom variables which have no (or incorrect) effect
> if you set them with setq -- such variables typically have a :set
> action which must be called for the setting to take effect.

Which is the right way to set such a variable in .emacs (for those of us
who don't want to use customize)?

 (customize-set-variable 'pc-selection-mode t)

perhaps?

                                                                Juanma

Re: doc problems with defcustom

[Miles Bader]

Juanma Barranquero <jmbarranquero@wke.es> writes:
> Which is the right way to set such a variable in .emacs (for those of us
> who don't want to use customize)?
>
>  (customize-set-variable 'pc-selection-mode t)

No, just use the associated function, e.g., (pc-selection-mode t)

The issue is really independent of customize; some modes need setup to
be done, and the way you do it these days is by calling the mode function.

-Miles
-- 
"1971 pickup truck; will trade for guns"

Re: doc problems with defcustom

[David Kastrup]

Miles Bader <miles@lsi.nec.co.jp> writes:

> Juanma Barranquero <jmbarranquero@wke.es> writes:
> > Which is the right way to set such a variable in .emacs (for those of us
> > who don't want to use customize)?
> >
> >  (customize-set-variable 'pc-selection-mode t)
> 
> No, just use the associated function, e.g., (pc-selection-mode t)
> 
> The issue is really independent of customize; some modes need setup
> to be done, and the way you do it these days is by calling the mode
> function.

Which customize-set-variable does just fine.  The problem is that if
you use customize-set-variable, customize is of the opinion that it
is able to manage the variable settings itself, and it isn't.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: doc problems with defcustom

[Per Abrahamsen]

Juanma Barranquero <jmbarranquero@wke.es> writes:

>> There are some defcustom variables which have no (or incorrect) effect
>> if you set them with setq -- such variables typically have a :set
>> action which must be called for the setting to take effect.
>
> Which is the right way to set such a variable in .emacs (for those of us
> who don't want to use customize)?

There are supposed to be a "setter" function for such variables (in
fact, the varable often only exists because Customize can't call
setter functions directy, it always need to go through a variable), and
the doc string of the variable is supposed to mention the name of the
setter function.  If it doesn't, report it as a bug.

Re: doc problems with defcustom

[Kenichi Handa]

In article <20040608101857.9673.JMBARRANQUERO@wke.es>, Juanma Barranquero <jmbarranquero@wke.es> writes:
> Which is the right way to set such a variable in .emacs (for those of us
> who don't want to use customize)?

>  (customize-set-variable 'pc-selection-mode t)

Oops, I didn't know about this function.

By the way, the docstring contains this sentence:
	value is a Lisp object.
but I think it's not necessary because we can't have
anything other than Lisp object.

Miles Bader <miles@lsi.nec.co.jp> writes:
> No, just use the associated function, e.g., (pc-selection-mode t)

> The issue is really independent of customize; some modes need setup to
> be done, and the way you do it these days is by calling the mode function.

For minor-mode variables, what's the difference between
customize-set-variable and the associated function?

---
Ken'ichi HANDA
handa@m17n.org

Re: doc problems with defcustom

[Kenichi Handa]

In article <m3brjuscoe.fsf@kfs-l.imdomain.dk>, storm@cua.dk (Kim F. Storm) writes:
> There are some defcustom variables which have no (or incorrect) effect
> if you set them with setq -- such variables typically have a :set
> action which must be called for the setting to take effect.

> For example pc-selection-mode and global-reveal-mode.

Isn't it possible to have a function, say
custom-set-variable, that sets a value and calls :set action
if necessary.
	Ex: (custom-set-variable 'pc-selection-mode t)

I'm now working on utf-translate-cjk-mode and want to check
the result of setting/unsetting it repeatedly, but it's
quite annoying to do that via *Customize Option* buffer.

---
Ken'ichi HANDA
handa@m17n.org

Re: doc problems with defcustom

[Stephan Stahl]

Hi.

Kenichi Handa said:

> Isn't it possible to have a function, say
> custom-set-variable, that sets a value and calls :set action

There is:

customize-set-variable is an interactive compiled Lisp function in
`cus-edit'.
(customize-set-variable variable value &optional comment)

Set the default for variable to value, and return value.
value is a Lisp object.

If variable has a `custom-set' property, that is used for setting
variable, otherwise `set-default' is used.

The `customized-value' property of the variable will be set to a list
with a quoted value as its sole list member.

If variable has a `variable-interactive' property, that is used as if
it were the arg to `interactive' (which see) to interactively read the value.

If variable has a `custom-type' property, it must be a widget and the
`:prompt-value' property of that widget will be used for reading the value.

If given a prefix (or a comment argument), also prompt for a comment.

-- 
Stephan Stahl

Re: doc problems with defcustom

[Miles Bader]

Kenichi Handa <handa@m17n.org> writes:
> I'm now working on utf-translate-cjk-mode and want to check
> the result of setting/unsetting it repeatedly, but it's
> quite annoying to do that via *Customize Option* buffer.

Um, `M-x utf-translate-cjk-mode RET' ...

-Miles
-- 
We live, as we dream -- alone....

Re: doc problems with defcustom

[Richard Stallman]

    There are some defcustom variables which have no (or incorrect) effect
    if you set them with setq -- such variables typically have a :set
    action which must be called for the setting to take effect.

    For example pc-selection-mode and global-reveal-mode.

In such cases, the variable's doc string should always say so.
We should try to minimize the number of such cases.

Re: doc problems with defcustom

[Richard Stallman]

    > Perhaps that's because it's the same as it has always been -- just
    > use setq, or add-to-list, or whatever you like.

    I think it would be a good idea to mention this somewhere...

Can you find a place in the manual that would be a good place to say
this?

Re: doc problems with defcustom

[Werner LEMBERG]

>     > Perhaps that's because it's the same as it has always been -- just
>     > use setq, or add-to-list, or whatever you like.
> 
>     I think it would be a good idea to mention this somewhere...
> 
> Can you find a place in the manual that would be a good place to say
> this?

In the documentation section for defcustom (in elisp.info) , and in
the `Init File' section (of emacs.info).


    Werner

Re: doc problems with defcustom

[Richard Stallman]

    > Can you find a place in the manual that would be a good place to say
    > this?

    In the documentation section for defcustom (in elisp.info) , and in
    the `Init File' section (of emacs.info).

I will add text there.  Thanks.