@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1997, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/customize
@node Customization, Loading, Macros, Top
@end menu
@node Common Keywords
-@section Common Keywords for All Kinds of Items
+@section Common Item Keywords
All kinds of customization declarations (for variables and groups, and
for faces) accept keyword arguments for specifying various information.
display one name.
@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.
+
@item :group @var{group}
Put this customization item in group @var{group}. When you use
@code{:group} in a @code{defgroup}, it makes the new group a subgroup of
If you use this keyword more than once, you can put a single item into
more than one group. Displaying any of those groups will show this
-item. Be careful not to overdo this!
+item. Please don't overdo this, since the result would be annoying.
@item :link @var{link-data}
Include an external link after the documentation string for this item.
There are three alternatives you can use for @var{link-data}:
@table @code
-@item :tag @var{name}
-Use @var{name}, a string, instead of the item's name, to label the item
-in customization menus and buffers.
-
@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
@item (url-link @var{url})
Link to a web page; @var{url} is a string which specifies the @sc{url}.
The link appears in the customization buffer as @var{url}.
+
+@item (emacs-commentary-link @var{library})
+Link to the commentary section of a library; @var{library} is a string
+which specifies the library name.
@end table
You can specify the text to use in the customization buffer by adding
The way to declare new customization groups is with @code{defgroup}.
-@tindex defgroup
@defmac defgroup group members doc [keyword value]...
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.
+the documentation string for the group. It should not start with a
+@samp{*} as in @code{defcustom}; that convention is for variables only.
-The arguments @var{members} can be an alist whose elements specify
-customization items to be members of the group; however, normally
+The argument @var{members} is a list specifying an initial set of
+customization items to be members of the group. However, most often
@var{members} is @code{nil}, and you specify the group's members by
using the @code{:group} keyword when defining those members.
-@ignore
-@code{(@var{name} @var{widget})}. Here @var{name} is a symbol, and
-@var{widget} is a widget for editing that symbol. Useful widgets are
-@code{custom-variable} for editing variables, @code{custom-face} for
-editing faces, and @code{custom-group} for editing groups.
-@end ignore
+If you want to specify group members through @var{members}, each element
+should have the form @code{(@var{name} @var{widget})}. Here @var{name}
+is a symbol, and @var{widget} is a widget type for editing that symbol.
+Useful widgets are @code{custom-variable} for a variable,
+@code{custom-face} for a face, and @code{custom-group} for a group.
+
+When a new group is introduced into Emacs, use this keyword in
+@code{defgroup}:
+
+@table @code
+@item :version @var{version}
+This option specifies that the group was first introduced in Emacs
+version @var{version}. The value @var{version} must be a string.
+@end table
+
+Tag the group with a version like this when it is introduced, rather
+than the individual members (@pxref{Variable Definitions}).
In addition to the common keywords (@pxref{Common Keywords}), you can
-use this keyword in @code{defgroup}:
+also use this keyword in @code{defgroup}:
@table @code
@item :prefix @var{prefix}
Use @code{defcustom} to declare user-editable variables.
-@tindex defcustom
-@defmac defcustom option default doc [keyword value]...
+@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.
+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.
If @var{option} is void, @code{defcustom} initializes it to
@var{default}. @var{default} should be an expression to compute the
-value; be careful in writing it, because it can be be evaluated on more
-than one occasion.
+value; be careful in writing it, because it can be evaluated on more
+than one occasion. You should normally avoid using backquotes in
+@var{default} because they are not expanded when editing the value,
+causing list values to appear to have the wrong structure.
+
+When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
+mode (@code{eval-defun}), a special feature of @code{eval-defun}
+arranges to set the variable unconditionally, without testing whether
+its value is void. (The same feature applies to @code{defvar}.)
+@xref{Defining Variables}.
+@end defmac
-The following additional keywords are defined:
+ @code{defcustom} accepts the following additional keywords:
@table @code
@item :type @var{type}
@item :options @var{list}
Specify @var{list} as the list of reasonable values for use in this
-option.
+option. The user is not restricted to using only these values, but they
+are offered as convenient alternatives.
-Currently this is meaningful only when the type is @code{hook}. In that
-case, the elements of @var{list} should be functions that are useful as
-elements of the hook value. The user is not restricted to using only
-these functions, 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
+individual types for a description of how to use @code{:options}.
@item :version @var{version}
-This option specifies that the variable's default value was changed in
-Emacs version @var{version}. For example,
+This option specifies that the variable was first introduced, or its
+default value was changed, in Emacs version @var{version}. The value
+@var{version} must be a string. For example,
@example
(defcustom foo-max 34
already set or has been customized; otherwise, just use
@code{set-default}.
@end table
+
+@item :set-after @var{variables}
+When setting variables according to saved customizations, make sure to
+set the variables @var{variables} before this one; in other words, delay
+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
-@end defmac
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
@example
(defcustom show-paren-mode nil
- "Toggle Show Paren mode@enddots{}"
+ "Toggle Show Paren mode..."
:set (lambda (symbol value)
- (show-paren-mode (or value 0)))
+ (show-paren-mode (or value 0)))
:initialize 'custom-initialize-default
:type 'boolean
:group 'paren-showing
:require 'paren)
@end example
-@ignore
-Use @code{custom-add-option} to specify that a specific function is
-useful as an member of a hook.
+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 variable @var{symbol} add @var{option}.
+To the customization @var{symbol}, add @var{option}.
-If @var{symbol} is a hook variable, @var{option} should be a hook
-member. For other types variables, the effect is undefined."
+The precise effect of adding @var{option} depends on the customization
+type of @var{symbol}.
@end defun
-@end ignore
Internally, @code{defcustom} uses the symbol property
@code{standard-value} to record the expression for the default value,
* Type Keywords::
@end menu
+All customization types are implemented as widgets; see @ref{Top, ,
+Introduction, widget, The Emacs Widget Library} for details.
+
@node Simple Types
@subsection Simple Types
The value must be a directory name, and you can do completion with
@kbd{M-@key{TAB}}.
+@item hook
+The value must be a list of functions (or a single function, but that is
+obsolete usage). This customization type is used for hook variables.
+You can use the @code{:options} keyword in a hook variable's
+@code{defcustom} to specify a list of functions recommended for use in
+the hook; see @ref{Variable Definitions}.
+
+@item alist
+The value must be a list of cons-cells, the @sc{car} of each cell
+representing a key, and the @sc{cdr} of the same cell representing an
+associated value. The user can add and delete key/value pairs, and
+edit both the key and the value of each pair.
+
+You can specify the key and value types like this:
+
+@smallexample
+(alist :key-type @var{key-type} :value-type @var{value-type})
+@end smallexample
+
+@noindent
+where @var{key-type} and @var{value-type} are customization type
+specifications. The default key type is @code{sexp}, and the default
+value type is @code{sexp}.
+
+The user can add any key matching the specified key type, but you can
+give some keys a preferential treatment by specifying them with the
+@code{:options} (see @ref{Variable Definitions}). The specified keys
+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
+
+Finally, you may want to change how the key is presented. By default,
+the key is simply shown as a @code{const}, since the user cannot change
+the special keys specified with the @code{:options} keyword. However,
+you may want to use a more specialized type for presenting the key, like
+@code{function-item} if you know it is a symbol with a function binding.
+This is done by using a customization type specification instead of a
+symbol for the key.
+
+@smallexample
+:options '("foo" ((function-item some-function) integer) "baz")
+@end smallexample
+
+Many alists use lists with two elements, instead of cons cells. For
+example,
+
+@smallexample
+(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
+ "Each element is a list of the form (KEY VALUE).")
+@end smallexample
+
+@noindent
+instead of
+
+@smallexample
+(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
+ "Each element is a cons-cell (KEY . VALUE).")
+@end smallexample
+
+Because of the way lists are implemented on top of cons cells, you can
+treat @code{list-alist} in the example above as a cons cell alist, where
+the value type is a list with a single element containing the real
+value.
+
+@smallexample
+(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
+ "Each element is a list of the form (KEY VALUE)."
+ :type '(alist :value-type (group integer)))
+@end smallexample
+
+The @code{group} widget is used here instead of @code{list} only because
+the formatting is better suited for the purpose.
+
+Similarily, you can have alists with more values associated with each
+key, using variations of this trick:
+
+@smallexample
+(defcustom person-data '(("brian" 50 t)
+ ("dorith" 55 nil)
+ ("ken" 52 t))
+ "Alist of basic info about people.
+Each element has the form (NAME AGE MALE-FLAG)."
+ :type '(alist :value-type (group age boolean)))
+
+(defcustom pets '(("brian")
+ ("dorith" "dog" "guppy")
+ ("ken" "cat"))
+ "Alist of people's pets.
+In an element (KEY . VALUE), KEY is the person's name,
+and the VALUE is a list of that person's pets."
+ :type '(alist :value-type (repeat string)))
+@end smallexample
+
+@item plist
+The @code{plist} custom type is similar to the @code{alist} (see above),
+except that the information is stored as a property list, i.e. a list of
+this form:
+
+@smallexample
+(@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})
+@end smallexample
+
+The default @code{:key-type} for @code{plist} is @code{symbol},
+rather than @code{sexp}.
+
@item symbol
The value must be a symbol. It appears in the customization buffer as
the name of the symbol.
The value must be a variable name, and you can do completion with
@kbd{M-@key{TAB}}.
+@item face
+The value must be a symbol which is a face name, and you can do
+completion with @kbd{M-@key{TAB}}.
+
@item boolean
The value is boolean---either @code{nil} or @code{t}. Note that by
using @code{choice} and @code{const} together (see the next section),
you can specify that the value must be @code{nil} or @code{t}, but also
specify the text to describe each value in a way that fits the specific
meaning of the alternative.
+
+@item coding-system
+The value must be a coding-system name, and you can do completion with
+@kbd{M-@key{TAB}}.
+
+@item color
+The value must be a valid color name, and you can do completion with
+@kbd{M-@key{TAB}}. A sample is provided,
@end table
@node Composite Types
@table @code
@item (restricted-sexp :match-alternatives @var{criteria})
The value may be any Lisp object that satisfies one of @var{criteria}.
-@var{criteria} should be a list, and each elements should be
+@var{criteria} should be a list, and each element should be
one of these possibilities:
@itemize @bullet
@item
-A predicate---that is, a function of one argument that returns non-@code{nil}
-if the argument fits a certain type. This means that objects of that type
-are acceptable.
+A predicate---that is, a function of one argument that has no side
+effects, and returns either @code{nil} or non-@code{nil} according to
+the argument. Using a predicate in the list says that objects for which
+the predicate returns non-@code{nil} are acceptable.
@item
-A quoted constant---that is, @code{'@var{object}}. This means that
-@var{object} itself is an acceptable value.
+A quoted constant---that is, @code{'@var{object}}. This sort of element
+in the list says that @var{object} itself is an acceptable value.
@end itemize
For example,
@example
-(restricted-sexp :match-alternatives (integerp 't 'nil))
+(restricted-sexp :match-alternatives
+ (integerp 't 'nil))
@end example
@noindent
@item (cons @var{car-type} @var{cdr-type})
The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
-its @sc{cdr} must fit @var{cdr-type}. For example, @code{(const string
+its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string
symbol)} is a customization type which matches values such as
@code{("foo" . foo)}.
three elements; the first element must be an integer, the second a
string, and the third a function.
-In the customization buffer, the each element is displayed and edited
+In the customization buffer, each element is displayed and edited
separately, according to the type specified for it.
@item (vector @var{element-types}@dots{})
Like @code{list} except that the value must be a vector instead of a
list. The elements work the same as in @code{list}.
-@item (choice @var{alternative-types}...)
+@item (choice @var{alternative-types}@dots{})
The value must fit at least one of @var{alternative-types}.
For example, @code{(choice integer string)} allows either an
integer or a string.
an integer stands for a number of spaces, while a string is text to use
verbatim, you might write the customization type this way,
-@smallexample
+@example
(choice (integer :tag "Number of spaces")
(string :tag "Literal text"))
-@end smallexample
+@end example
@noindent
so that the menu offers @samp{Number of spaces} and @samp{Literal Text}.
a @code{const}, you should specify a valid default for that alternative
using the @code{:value} keyword. @xref{Type Keywords}.
+@item (radio @var{element-types}@dots{})
+This is similar to @code{choice}, except that the choices are displayed
+using `radio buttons' rather than a menu. This has the advantage of
+displaying documentation for the choices when applicable and so is often
+a good choice for a choice between constant functions
+(@code{function-item} customization types).
+
@item (const @var{value})
The value must be @var{value}---nothing else is allowed.
@code{:tag} is often used with @code{const}, inside of @code{choice}.
For example,
-@smallexample
+@example
(choice (const :tag "Yes" t)
(const :tag "No" nil)
(const :tag "Ask" foo))
-@end smallexample
+@end example
+
+@noindent
+describes a variable for which @code{t} means yes, @code{nil} means no,
+and @code{foo} means ``ask.''
+
+@item (other @var{value})
+This alternative can match any Lisp value, but if the user chooses this
+alternative, that selects the value @var{value}.
+
+The main use of @code{other} is as the last element of @code{choice}.
+For example,
+
+@example
+(choice (const :tag "Yes" t)
+ (const :tag "No" nil)
+ (other :tag "Ask" foo))
+@end example
+
+@noindent
+describes a variable for which @code{t} means yes, @code{nil} means no,
+and anything else means ``ask.'' If the user chooses @samp{Ask} from
+the menu of alternatives, that specifies the value @code{foo}; but any
+other value (not @code{t}, @code{nil} or @code{foo}) displays as
+@samp{Ask}, just like @code{foo}.
@item (function-item @var{function})
Like @code{const}, but used for values which are functions. This
documentation string is either the one you specify with @code{:doc}, or
@var{variable}'s own documentation string.
-@item (set @var{elements}@dots{})
-The value must be a list and each element of the list must be one of the
-@var{elements} specified. This appears in the customization buffer as a
-checklist.
+@item (set @var{types}@dots{})
+The value must be a list, and each element of the list must match one of
+the @var{types} specified.
+
+This appears in the customization buffer as a checklist, so that each of
+@var{types} may have either one corresponding element or none. It is
+not possible to specify two different elements that match the same one
+of @var{types}. For example, @code{(set integer symbol)} allows one
+integer and/or one symbol in the list; it does not allow multiple
+integers or multiple symbols. As a result, it is rare to use
+nonspecific types such as @code{integer} in a @code{set}.
+
+Most often, the @var{types} in a @code{set} are @code{const} types, as
+shown here:
+
+@example
+(set (const :bold) (const :italic))
+@end example
+
+Sometimes they describe possible elements in an alist:
+
+@example
+(set (cons :tag "Height" (const height) integer)
+ (cons :tag "Width" (const width) integer))
+@end example
+
+@noindent
+That lets the user specify a height value optionally
+and a width value optionally.
@item (repeat @var{element-type})
The value must be a list and each element of the list must fit the type
@item :help-echo @var{motion-doc}
When you move to this item with @code{widget-forward} or
-@code{widget-backward}, it will display the string @var{motion-doc}
-in the echo area.
+@code{widget-backward}, it will display the string @var{motion-doc} in
+the echo area. In addition, @var{motion-doc} is used as the mouse
+@code{help-echo} string and may actually be a function or form evaluated
+to yield a help string as for @code{help-echo} text properties.
+@c @xref{Text help-echo}.
@item :match @var{function}
Specify how to decide whether a value matches the type. The
@end enumerate
@item :parent
-The parent of a nested widget (e.g. a @code{menu-choice} item or an
+The parent of a nested widget (e.g., a @code{menu-choice} item or an
element of a @code{editable-list} widget).
@item :sibling-args