comparison lispref/customize.texi @ 74703:be5e68ff2673

Use "option" only for user options. For the keyword values inside defcustom etc, say "keywords". For :options value's elements, say "elements". :group should not be omitted.

74702:2d3815650232

a feature such as a minor mode, and just setting the variable won't have
any effect unless the code which implements the mode is loaded.

@item :version @var{version}
@kindex version@r{, customization keyword}
This option specifies that the item was first introduced in Emacs
version @var{version}, or that its default value was changed in that
version.  The value @var{version} must be a string.

@item :package-version '(@var{package} . @var{version})
@kindex package-version@r{, customization keyword}
This option specifies that the item was first introduced in
@var{package} version @var{version}, or that its meaning or default
value was changed in that version.  The value of @var{package} is a
symbol and @var{version} is a string.

This keyword takes priority over @code{:version}.

standard value.  So be sure to use an expression which is harmless to
evaluate at any time.  We recommend avoiding backquotes in
@var{standard}, because they are not expanded when editing the value,
so list values will appear to have the wrong structure.

If you specify the @code{:set} option, to make the variable take other
special actions when set through the customization buffer, the
variable's documentation string should tell the user specifically how
to do the same job in hand-written Lisp code.

When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp

@item :type @var{type}
Use @var{type} as the data type for this option.  It specifies which
values are legitimate, and how to display the value.
@xref{Customization Types}, for more information.

@item :options @var{list}
@kindex options@r{, @code{defcustom} keyword}
Specify @var{list} as the list of reasonable values for use in this
option.  The user is not restricted to using only these values, but they
are offered as convenient alternatives.

This is meaningful only for certain types, currently including
@code{hook}, @code{plist} and @code{alist}.  See the definition of the

setting this variable until after those others have been handled.  Use
@code{:set-after} if setting this variable won't work properly unless
those other variables already have their intended values.
@end table

  The @code{:require} option is useful for an option that turns on the
operation of a certain feature.  Assuming that the package is coded to
check the value of the option, you still need to arrange for the package
to be loaded.  You can do that with @code{:require}.  @xref{Common
Keywords}.  Here is an example, from the library @file{saveplace.el}:

  :type 'boolean
  :require 'saveplace
  :group 'save-place)
@end example

If a customization item has a type such as @code{hook} or @code{alist},
which supports @code{:options}, you can add additional options to the
item, outside the @code{defcustom} declaration, by calling
@code{custom-add-option}.  For example, if you define a function
@code{my-lisp-mode-initialization} intended to be called from
@code{emacs-lisp-mode-hook}, you might want to add that to the list of
options for @code{emacs-lisp-mode-hook}, but not by editing its
definition.   You can do it thus:

@example
(custom-add-option 'emacs-lisp-mode-hook
                   'my-lisp-mode-initialization)
@end example

@defun custom-add-option symbol option
To the customization @var{symbol}, add @var{option}.

The precise effect of adding @var{option} depends on the customization
type of @var{symbol}.
@end defun

Internally, @code{defcustom} uses the symbol property
@code{standard-value} to record the expression for the standard value,
and @code{saved-value} to record the value saved by the user with the

will always be shown in the customize buffer (together with a suitable
value), with a checkbox to include or exclude or disable the key/value
pair from the alist.  The user will not be able to edit the keys
specified by the @code{:options} keyword argument.

The argument to the @code{:options} keywords should be a list of option
specifications.  Ordinarily, the options are simply atoms, which are the
specified keys.  For example:

@smallexample
:options '("foo" "bar" "baz")
@end smallexample

@noindent
specifies that there are three ``known'' keys, namely @code{"foo"},
@code{"bar"} and @code{"baz"}, which will always be shown first.

You may want to restrict the value type for specific keys, for example,
the value associated with the @code{"bar"} key can only be an integer.
You can specify this by using a list instead of an atom in the option
specification.  The first element will specify the key, like before,
while the second element will specify the value type.

@smallexample
:options '("foo" ("bar" integer) "baz")
@end smallexample

74703:be5e68ff2673

a feature such as a minor mode, and just setting the variable won't have
any effect unless the code which implements the mode is loaded.

@item :version @var{version}
@kindex version@r{, customization keyword}
This keyword specifies that the item was first introduced in Emacs
version @var{version}, or that its default value was changed in that
version.  The value @var{version} must be a string.

@item :package-version '(@var{package} . @var{version})
@kindex package-version@r{, customization keyword}
This keyword specifies that the item was first introduced in
@var{package} version @var{version}, or that its meaning or default
value was changed in that version.  The value of @var{package} is a
symbol and @var{version} is a string.

This keyword takes priority over @code{:version}.

standard value.  So be sure to use an expression which is harmless to
evaluate at any time.  We recommend avoiding backquotes in
@var{standard}, because they are not expanded when editing the value,
so list values will appear to have the wrong structure.

Every @code{defcustom} should specify @code{:group} at least once.

If you specify the @code{:set} keyword, to make the variable take other
special actions when set through the customization buffer, the
variable's documentation string should tell the user specifically how
to do the same job in hand-written Lisp code.

When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp

@item :type @var{type}
Use @var{type} as the data type for this option.  It specifies which
values are legitimate, and how to display the value.
@xref{Customization Types}, for more information.

@item :options @var{value-list}
@kindex options@r{, @code{defcustom} keyword}
Specify the list of reasonable values for use in this
option.  The user is not restricted to using only these values, but they
are offered as convenient alternatives.

This is meaningful only for certain types, currently including
@code{hook}, @code{plist} and @code{alist}.  See the definition of the

setting this variable until after those others have been handled.  Use
@code{:set-after} if setting this variable won't work properly unless
those other variables already have their intended values.
@end table

  The @code{:require} keyword is useful for an option that turns on the
operation of a certain feature.  Assuming that the package is coded to
check the value of the option, you still need to arrange for the package
to be loaded.  You can do that with @code{:require}.  @xref{Common
Keywords}.  Here is an example, from the library @file{saveplace.el}:

  :type 'boolean
  :require 'saveplace
  :group 'save-place)
@end example

If a customization item has a type such as @code{hook} or
@code{alist}, which supports @code{:options}, you can add additional
values to the list from outside the @code{defcustom} declaration by
calling @code{custom-add-option}.  For example, if you define a
function @code{my-lisp-mode-initialization} intended to be called from
@code{emacs-lisp-mode-hook}, you might want to add that to the list of
reasonable values for @code{emacs-lisp-mode-hook}, but not by editing
its definition.  You can do it thus:

@example
(custom-add-option 'emacs-lisp-mode-hook
                   'my-lisp-mode-initialization)
@end example

@defun custom-add-option symbol value
For the customization option @var{symbol}, add @var{value} to the
list of reasonable values.

The precise effect of adding a value depends on the customization type
of @var{symbol}.
@end defun

Internally, @code{defcustom} uses the symbol property
@code{standard-value} to record the expression for the standard value,
and @code{saved-value} to record the value saved by the user with the

will always be shown in the customize buffer (together with a suitable
value), with a checkbox to include or exclude or disable the key/value
pair from the alist.  The user will not be able to edit the keys
specified by the @code{:options} keyword argument.

The argument to the @code{:options} keywords should be a list of
specifications for reasonable keys in the alist.  Ordinarily, they are
simply atoms, which stand for themselves as.  For example:

@smallexample
:options '("foo" "bar" "baz")
@end smallexample

@noindent
specifies that there are three ``known'' keys, namely @code{"foo"},
@code{"bar"} and @code{"baz"}, which will always be shown first.

You may want to restrict the value type for specific keys, for
example, the value associated with the @code{"bar"} key can only be an
integer.  You can specify this by using a list instead of an atom in
the list.  The first element will specify the key, like before, while
the second element will specify the value type.  For example:

@smallexample
:options '("foo" ("bar" integer) "baz")
@end smallexample