@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1997, 1998, 1999, 2000, 2002, 2003 Free Software Foundation, Inc.
+@c Copyright (C) 1997, 1998, 1999, 2000, 2002, 2003, 2004,
+@c 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/customize
@node Customization, Loading, Macros, Top
definitions---as well as face definitions (@pxref{Defining Faces}).
@menu
-* Common Keywords::
-* Group Definitions::
-* Variable Definitions::
-* Customization Types::
+* Common Keywords:: Common keyword arguments for all kinds of
+ customization declarations.
+* Group Definitions:: Writing customization group definitions.
+* Variable Definitions:: Declaring user options.
+* Customization Types:: Specifying the type of a user option.
@end menu
@node Common Keywords
@table @code
@item :tag @var{label}
-Use @var{label}, a string, instead of the item's name, to label the item
-in customization menus and buffers.
+Use @var{label}, a string, instead of the item's name, to label the
+item in customization menus and buffers. @strong{Don't use a tag
+which is substantially different from the item's real name; that would
+cause confusion.} One legitimate case for use of @code{:tag} is to
+specify a dash where normally a hyphen would be converted to a space:
+
+@example
+(defcustom cursor-in-non-selected-windows @dots{}
+ :tag "Cursor In Non-selected Windows"
+@end example
@item :group @var{group}
Put this customization item in group @var{group}. When you use
This is a sentence containing an active field which references some
other documentation.
-There are four alternatives you can use for @var{link-data}:
+There are several alternatives you can use for @var{link-data}:
@table @code
@item (custom-manual @var{info-node})
Link to an Info node; @var{info-node} is a string which specifies the
node name, as in @code{"(emacs)Top"}. The link appears as
-@samp{[manual]} in the customization buffer.
+@samp{[Manual]} in the customization buffer and enters the built-in
+Info reader on @var{info-node}.
@item (info-link @var{info-node})
Like @code{custom-manual} except that the link appears
in the customization buffer with the Info node name.
@item (url-link @var{url})
-Link to a web page; @var{url} is a string which specifies the @acronym{URL}.
-The link appears in the customization buffer as @var{url}.
+Link to a web page; @var{url} is a string which specifies the
+@acronym{URL}. The link appears in the customization buffer as
+@var{url} and invokes the WWW browser specified by
+@code{browse-url-browser-function}.
@item (emacs-commentary-link @var{library})
Link to the commentary section of a library; @var{library} is a string
which specifies the library name.
+
+@item (emacs-library-link @var{library})
+Link to an Emacs Lisp library file; @var{library} is a string which
+specifies the library name.
+
+@item (file-link @var{file})
+Link to a file; @var{file} is a string which specifies the name of the
+file to visit with @code{find-file} when the user invokes this link.
+
+@item (function-link @var{function})
+Link to the documentation of a function; @var{function} is a string
+which specifies the name of the function to describe with
+@code{describe-function} when the user invokes this link.
+
+@item (variable-link @var{variable})
+Link to the documentation of a variable; @var{variable} is a string
+which specifies the name of the variable to describe with
+@code{describe-variable} when the user invokes this link.
+
+@item (custom-group-link @var{group})
+Link to another customization group. Invoking it creates a new
+customization buffer for @var{group}.
@end table
You can specify the text to use in the customization buffer by adding
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})
+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}.
+
+@var{package} should be the official name of the package, such as MH-E
+or Gnus. If the package @var{package} is released as part of Emacs,
+@var{package} and @var{version} should appear in the value of
+@code{customize-package-emacs-version-alist}.
@end table
+Packages distributed as part of Emacs that use the
+@code{:package-version} keyword must also update the
+@code{customize-package-emacs-version-alist} variable.
+
+@defvar customize-package-emacs-version-alist
+This alist provides a mapping for the versions of Emacs that are
+associated with versions of a package listed in the
+@code{:package-version} keyword. Its elements look like this:
+
+@example
+(@var{package} (@var{pversion} . @var{eversion})@dots{})
+@end example
+
+For each @var{package}, which is a symbol, there are one or more
+elements that contain a package version @var{pversion} with an
+associated Emacs version @var{eversion}. These versions are strings.
+For example, the MH-E package updates this alist with the following:
+
+@smallexample
+(add-to-list 'customize-package-emacs-version-alist
+ '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
+ ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
+ ("7.4" . "22.1") ("8.0" . "22.1")))
+@end smallexample
+
+The value of @var{package} needs to be unique and it needs to match
+the @var{package} value appearing in the @code{:package-version}
+keyword. Since the user might see the value in a error message, a good
+choice is the official name of the package, such as MH-E or Gnus.
+@end defvar
+
@node Group Definitions
@section Defining Custom Groups
The way to declare new customization groups is with @code{defgroup}.
-@defmac defgroup group members doc [keyword value]...
+@defmac defgroup group members doc [keyword value]@dots{}
Declare @var{group} as a customization group containing @var{members}.
Do not quote the symbol @var{group}. The argument @var{doc} specifies
-the documentation string for the group. It should not start with a
-@samp{*} as in @code{defcustom}; that convention is for variables only.
+the documentation string for the group.
The argument @var{members} is a list specifying an initial set of
customization items to be members of the group. However, most often
@defmac defcustom option default doc [keyword value]@dots{}
Declare @var{option} as a customizable user option variable. Do not
quote @var{option}. The argument @var{doc} specifies the documentation
-string for the variable. It should often start with a @samp{*} to mark
-it as a @dfn{user option} (@pxref{Defining Variables}). Do not start
-the documentation string with @samp{*} for options which cannot or
-normally should not be set with @code{set-variable}; examples of the
-former are global minor mode options such as
-@code{global-font-lock-mode} and examples of the latter are hooks.
+string for the variable. There is no need to start it with a @samp{*}
+because @code{defcustom} automatically marks @var{option} as a
+@dfn{user option} (@pxref{Defining Variables}).
If @var{option} is void, @code{defcustom} initializes it to
@var{default}. @var{default} should be an expression to compute the
Use the @code{:set} function to initialize the variable, if it is
already set or has been customized; otherwise, just use
@code{set-default}.
+
+@item custom-initialize-safe-set
+@itemx custom-initialize-safe-default
+These functions behave like @code{custom-initialize-set}
+(@code{custom-initialize-default}, respectively), but catch errors.
+If an error occurs during initialization, they set the variable to
+@code{nil} using @code{set-default}, and throw no error.
+
+These two functions are only meant for options defined in pre-loaded
+files, where some variables or functions used to compute the option's
+value may not yet be defined. The option normally gets updated in
+@file{startup.el}, ignoring the previously computed value. Because of
+this typical usage, the value which these two functions compute
+normally only matters when, after startup, one unsets the option's
+value and then reevaluates the defcustom. By that time, the necessary
+variables and functions will be defined, so there will not be an error.
@end table
@item :set-after @var{variables}
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{tooltip.el}:
+Keywords}. Here is an example, from the library @file{saveplace.el}:
@example
-(defcustom tooltip-mode nil
- "Non-nil if Tooltip mode is enabled..."
- :set (lambda (symbol value)
- (tooltip-mode (or value 0)))
- :initialize 'custom-initialize-default
+(defcustom save-place nil
+ "*Non-nil means automatically save place in each file..."
:type 'boolean
- :require 'tooltip
- :group 'tooltip)
+ :require 'saveplace
+ :group 'save-place)
@end example
If a customization item has a type such as @code{hook} or @code{alist},
Internally, @code{defcustom} uses the symbol property
@code{standard-value} to record the expression for the default value,
and @code{saved-value} to record the value saved by the user with the
-customization buffer. The @code{saved-value} property is actually a
-list whose car is an expression which evaluates to the value.
+customization buffer. Both properties are actually lists whose car is
+an expression which evaluates to the value.
@node Customization Types
@section Customization Types
symbol for the key.
@smallexample
-:options '("foo" ((function-item some-function) integer) "baz")
+:options '("foo" ((function-item some-function) integer)
+ "baz")
@end smallexample
Many alists use lists with two elements, instead of cons cells. For
@item (list @var{element-types}@dots{})
The value must be a list with exactly as many elements as the
-@var{element-types} you have specified; and each element must fit the
+@var{element-types} given; and each element must fit the
corresponding @var{element-type}.
For example, @code{(list integer string function)} describes a list of
For example, @code{(choice integer string)} allows either an
integer or a string.
-In the customization buffer, the user selects one of the alternatives
+In the customization buffer, the user selects an alternative
using a menu, and can then edit the value in the usual way for that
alternative.
most general last. Here's an example of proper usage:
@example
-(choice (const :tag "Off" nil) symbol (sexp :tag "Other"))
+(choice (const :tag "Off" nil)
+ symbol (sexp :tag "Other"))
@end example
@noindent
@code{help-echo} string and may actually be a function or form evaluated
to yield a help string. If it is a function, it is called with one
argument, the widget.
-@xref{Text help-echo}.
@item :match @var{function}
Specify how to decide whether a value matches the type. The
argument with the same syntax as the keyword argument to
@code{defcustom} with the same name. The third argument is a
documentation string for the new widget. You will be able to see that
-string with the @kbd{M-x widget-browse @key{ret} binary-tree-of-string
-@key{ret}} command.
+string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string
+@key{RET}} command.
After these mandatory arguments follow the keyword arguments. The most
important is @code{:type}, which describes the data type we want to match