@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 default value was
+changed in that version. This keyword takes priority over :version.
+The value of @var{package} is a symbol and @var{version} is a string.
+The @var{package} and @var{version} must appear in the alist
+@code{customize-package-emacs-version-alist}. Since @var{package} must
+be unique and the user might see it in an error message, a good choice
+is the official name of the package, such as MH-E or Gnus.
+
@end table
+Packages 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}
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
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