@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
@chapter Writing Customization Definitions
-This chapter describes how to declare customization groups, variables,
-and faces. We use the term @dfn{customization item} to include all
-three of those. This has few examples, but please look at the file
-@file{cus-edit.el}, which contains many declarations you can learn from.
+ This chapter describes how to declare user options for customization,
+and also customization groups for classifying them. We use the term
+@dfn{customization item} to include both kinds of customization
+definitions---as well as face definitions (@pxref{Defining Faces}).
@menu
* Common Keywords::
* Group Definitions::
* Variable Definitions::
-* Face Definitions::
* Customization Types::
@end menu
@node Common Keywords
-@section Common Keywords for All Kinds of Items
+@section Common Item Keywords
-All three kinds of customization declarations (for groups, variables,
-and faces) accept keyword arguments for specifying various information.
-This section describes some keywords that apply to all three.
+ All kinds of customization declarations (for variables and groups, and
+for faces) accept keyword arguments for specifying various information.
+This section describes some keywords that apply to all kinds.
-All of these keywords, except @code{:tag}, can be used more than once in
-a given item. Each use of the keyword has an independent effect. The
-keyword @code{:tag} is an exception because any given item can only
-display one name item.
+ All of these keywords, except @code{:tag}, can be used more than once
+in a given item. Each use of the keyword has an independent effect.
+The keyword @code{:tag} is an exception because any given item can only
+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.
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 URL. The
-link appears in the customization buffer as @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 most common reason to use @code{:require} is when a variable enables
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 :tag @var{name}
-Use @var{name}, a string, instead of the item's name, to label the item
-in customization menus and buffers.
@end table
@node Group Definitions
@section Defining Custom Groups
-Each Emacs Lisp package should have one main customization group which
+ Each Emacs Lisp package should have one main customization group which
contains all the options, faces and other groups in the package. If the
package has a small number of options and faces, use just one group and
put everything in it. When there are more than twelve or so options and
faces, then you should structure them into subgroups, and put the
-subgroups under the package's main customization group. It is ok to
-have some of the options and faces in the package's main group alongside
+subgroups under the package's main customization group. It is OK to
+put some of the options and faces in the package's main group alongside
the subgroups.
-The package's main or only group should be a member of one or more of
-the standard customization groups. Type press @kbd{C-h p} to display a
-list of finder keywords; them choose some of them add your group to each
-of them, using the @code{:group} keyword.
+ The package's main or only group should be a member of one or more of
+the standard customization groups. (To display the full list of them,
+use @kbd{M-x customize}.) Choose one or more of them (but not too
+many), and add your group to each of them using the @code{:group}
+keyword.
-The way to declare new customization groups is with @code{defgroup}.
+ 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
-members of the group; however, normally @var{members} is @code{nil}, and
-you specify the group's members by using the @code{:group} keyword when
-defining those members.
+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}
@end table
@end defmac
-The @code{:prefix} feature is currently turned off, which means that
-@code{:prefix} currently has no effect. We did this because we found
-that discarding the specified prefixes often led to confusing names for
-options. This happened because the people who wrote the @code{defgroup}
-definitions for various groups added @code{:prefix} keywords whenever
-they make logical sense---that is, whenever they say that there was a
-common prefix for the option names in a library.
-
-In order to obtain good results with @code{:prefix}, it is necessary to
-check the specific effects of discarding a particular prefix, given the
-specific items in a group and their names and documentation. If the
-resulting text is not clear, then @code{:prefix} should not be used in
-that case.
-
-It should be possible to recheck all the customization groups, delete
+ The prefix-discarding feature is currently turned off, which means
+that @code{:prefix} currently has no effect. We did this because we
+found that discarding the specified prefixes often led to confusing
+names for options. This happened because the people who wrote the
+@code{defgroup} definitions for various groups added @code{:prefix}
+keywords whenever they make logical sense---that is, whenever the
+variables in the library have a common prefix.
+
+ In order to obtain good results with @code{:prefix}, it would be
+necessary to check the specific effects of discarding a particular
+prefix, given the specific items in a group and their names and
+documentation. If the resulting text is not clear, then @code{:prefix}
+should not be used in that case.
+
+ It should be possible to recheck all the customization groups, delete
the @code{:prefix} specifications which give unclear results, and then
turn this feature back on, if someone would like to do the work.
@node Variable Definitions
@section Defining Customization Variables
- Use @code{defcustom} to declare user editable variables.
-
-@tindex defcustom
-@defmac defcustom option value doc [keyword value]...
-Declare @var{option} as a customizable user option variable that
-defaults to @var{value}. Do not quote @var{option}. @var{value} should
-be an expression to compute the value; it will be be evaluated on more
-than one occasion.
-
-If @var{option} is void, @code{defcustom} initializes it to @var{value}.
-
-The argument @var{doc} specifies the documentation string for the variable.
+ Use @code{defcustom} to declare user-editable variables.
+
+@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.
+
+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 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 type is @code{hook}. The
-elements of @var{list} are functions that you might likely want to use
-as elements of the hook value. The user is not actually 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
@table @code
@item custom-initialize-set
-Use the variable's @code{:set} function to initialize the variable. Do
-not reinitialize it if it is already non-void. This is the default
+Use the variable's @code{:set} function to initialize the variable, but
+do not reinitialize it if it is already non-void. This is the default
@code{:initialize} function.
@item custom-initialize-default
-Always use @code{set-default} to initialize the variable, even if some
-other @code{:set} function has been specified.
+Like @code{custom-initialize-set}, but use the function
+@code{set-default} to set the variable, instead of the variable's
+@code{:set} function. This is the usual choice for a variable whose
+@code{:set} function enables or disables a minor mode; with this choice,
+defining the variable will not call the minor mode function, but
+customizing the variable will do so.
@item custom-initialize-reset
-Even if the variable is already non-void, reset it by calling the
-@code{:set} function using the current value (returned by the
-@code{:get} method).
+Always use the @code{:set} function to initialize the variable. If the
+variable is already non-void, reset it by calling the @code{:set}
+function using the current value (returned by the @code{:get} method).
@item custom-initialize-changed
-Like @code{custom-initialize-reset}, except use @code{set-default}
-(rather than the @code{:set} function) to initialize the variable if it
-is not bound and has not been set already.
+Use the @code{:set} function to initialize the variable, if it is
+already set or has been customized; otherwise, just use
+@code{set-default}.
@end table
-@item :require @var{feature}
-If the user saves a customized value for this item, them Emacs should do
-@code{(require @var{feature})} after installing the saved value.
+@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
-The place to use this feature is for an option that turns on the
+ 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. That is what @code{:require} is for.
-@end table
-@end defmac
+to be loaded. You can do that with @code{:require}. @xref{Common
+Keywords}. Here is an example, from the library @file{paren.el}:
-@ignore
-Use @code{custom-add-option} to specify that a specific function is
-useful as an member of a hook.
+@example
+(defcustom show-paren-mode nil
+ "Toggle Show Paren mode..."
+ :set (lambda (symbol value)
+ (show-paren-mode (or value 0)))
+ :initialize 'custom-initialize-default
+ :type 'boolean
+ :group 'paren-showing
+ :require 'paren)
+@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 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,
customization buffer. The @code{saved-value} property is actually a
list whose car is an expression which evaluates to the value.
-@node Face Definitions
-@section Defining Faces
-
-Faces are declared with @code{defface}.
-
-@tindex defface
-@defmac defface face spec doc [keyword value]...
-Declare @var{face} as a customizable face that defaults according to
-@var{spec}. Do not quote the symbol @var{face}.
-
-@var{doc} is the face documentation.
-
-@var{spec} should be an alist whose elements have the form
-@code{(@var{display} @var{atts})} (see below). When @code{defface}
-executes, it defines the face according to @var{spec}, then uses any
-customizations saved in the @file{.emacs} file to override that
-specification.
-
-In each element of @var{spec}, @var{atts} is a list of face attributes
-and their values. The possible attributes are defined in the variable
-@code{custom-face-attributes}.
-
-The @var{display} part of an element of @var{spec} determines which
-frames the element applies to. If more than one element of @var{spec}
-matches a given frame, the first matching element is the only one used
-for that frame.
-
-If @var{display} is @code{t} in a @var{spec} element, that element
-matches all frames. (This means that any subsequent elements of
-@var{spec} are never used.)
-
-Alternatively, @var{display} can be an alist whose elements have the
-form @code{(@var{characteristic} @var{value}@dots{})}. Here
-@var{characteristic} specifies a way of classifying frames, and the
-@var{value}s are possible classifications which @var{display} should
-apply to. Here are the possible values of @var{characteristic}:
-
-@table @code
-@item type
-The kind of window system the frame uses---either @code{x}, @code{pc}
-(for the MS-DOS console), @code{w32} (for MS Windows 9X/NT), or
-@code{tty}.
-
-@item class
-What kinds of colors the frame supports---either @code{color},
-@code{grayscale}, or @code{mono}.
-
-@item background
-The kind of background--- either @code{light} or @code{dark}.
-@end table
-
-If an element of @var{display} specifies more than one
-@var{value} for a given @var{characteristic}, any of those values
-is acceptable. If an element of @var{display} has elements for
-more than one @var{characteristic}, then @var{each} characteristic
-of the frame must match one of the values specified for it.
-@end defmac
-
-Internally, @code{defface} uses the symbol property
-@code{face-defface-spec} to record the face attributes specified in
-@code{defface}, @code{saved-face} for the attributes saved by the user
-with the customization buffer, and @code{face-documentation} for the
-documentation string.
-
@node Customization Types
@section Customization Types
When you define a user option with @code{defcustom}, you must specify
-its @dfn{customization type}. That is a Lisp object which indictaes (1)
+its @dfn{customization type}. That is a Lisp object which describes (1)
which values are legitimate and (2) how to display the value in the
customization buffer for editing.
You specify the customization type in @code{defcustom} with the
@code{:type} keyword. The argument of @code{:type} is evaluated; since
-types that vary at run time are rarely useful, normally it is a quoted
+types that vary at run time are rarely useful, normally you use a quoted
constant. For example:
@example
(defcustom diff-command "diff"
"*The command to use to run diff."
- :type 'string
+ :type '(string)
:group 'diff)
@end example
- In general, a customization type appears is a list whose first element
-is a symbol, one of the customization type names defined in the
-following sections. After this symbol come a number of arguments,
-depending on the symbol. Some of the type symbols do not use any
-arguments; those are called @dfn{simple types}.
+ In general, a customization type is a list whose first element is a
+symbol, one of the customization type names defined in the following
+sections. After this symbol come a number of arguments, depending on
+the symbol. Between the type symbol and its arguments, you can
+optionally write keyword-value pairs (@pxref{Type Keywords}).
- In between the type symbol and its arguments, you can optionally
-write keyword-value pairs. @xref{Type Keywords}.
-
- For a simple type, if you do not use any keyword-value pairs, you can
-omit the parentheses around the type symbol. The above example does
-this, using just @code{string} as the customization type.
-But @code{(string)} would mean the same thing.
+ Some of the type symbols do not use any arguments; those are called
+@dfn{simple types}. For a simple type, if you do not use any
+keyword-value pairs, you can omit the parentheses around the type
+symbol. For example just @code{string} as a customization type is
+equivalent to @code{(string)}.
@menu
* Simple Types::
* 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
@item string
The value must be a string, and the customization buffer shows just the
-contents, with no @samp{"} characters or quoting with @samp{\}.
+contents, with no delimiting @samp{"} characters and no quoting with
+@samp{\}.
@item regexp
-The value must be a string which is a valid regular expression.
+Like @code{string} except that the string must be a valid regular
+expression.
@item character
The value must be a character code. A character code is actually an
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}.
+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
@subsection Composite Types
When none of the simple types is appropriate, you can use composite
-types, which build from simple types. Here are several ways of doing
-that:
+types, which build new types from other types. Here are several ways of
+doing that:
@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} 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)}.
-In the customization buffeer, the @sc{car} and the @sc{cdr} are
+In the customization buffer, the @sc{car} and the @sc{cdr} are
displayed and edited separately, each according to the type
that you specify for it.
three elements; the first element must be an integer, the second a
string, and the third a function.
-In the customization buffeer, 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}.
+In any alternative for which @code{nil} is not a valid value, other than
+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.
The main use of @code{const} is inside of @code{choice}. For example,
@code{(choice integer (const nil))} allows either an integer or
-@code{nil}. @code{:tag} is often used with @code{const}.
+@code{nil}.
+
+@code{:tag} is often used with @code{const}, inside of @code{choice}.
+For example,
+
+@example
+(choice (const :tag "Yes" t)
+ (const :tag "No" nil)
+ (const :tag "Ask" foo))
+@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
-displays the documentation string of the function @var{function}
-as well as its name.
+displays the documentation string as well as the function name.
+The documentation string is either the one you specify with
+@code{:doc}, or @var{function}'s own documentation string.
@item (variable-item @var{variable})
Like @code{const}, but used for values which are variable names. This
-displays the documentation string of the variable @var{variable} as well
-as its name.
+displays the documentation string as well as the variable name. The
+documentation string is either the one you specify with @code{:doc}, or
+@var{variable}'s own documentation string.
+
+@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.
-@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.
+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
@table @code
@item :value @var{default}
This is used for a type that appears as an alternative inside of
-@code{:choice}; it specifies the default value to use, at first, if and
+@code{choice}; it specifies the default value to use, at first, if and
when the user selects this alternative with the menu in the
customization buffer.
Of course, if the actual value of the option fits this alternative, it
will appear showing the actual value, not @var{default}.
+If @code{nil} is not a valid value for the alternative, then it is
+essential to specify a valid default with @code{:value}.
+
@item :format @var{format-string}
This string will be inserted in the buffer to represent the value
corresponding to the type. The following @samp{%} escapes are available
for use in @var{format-string}:
@table @samp
-@ignore
@item %[@var{button}%]
Display the text @var{button} marked as a button. The @code{:action}
attribute specifies what the button will do if the user invokes it;
the button appears in, and the event.
There is no way to specify two different buttons with different
-actions; but perhaps there is no need for one.
-@end ignore
+actions.
@item %@{@var{sample}%@}
Show @var{sample} in a special face specified by @code{:sample-face}.
Display a literal @samp{%}.
@end table
+@item :action @var{action}
+Perform @var{action} if the user clicks on a button.
+
@item :button-face @var{face}
-Use face @var{face} for text displayed with @samp{%[@dots{}%]}.
+Use the face @var{face} (a face name or a list of face names) for button
+text displayed with @samp{%[@dots{}%]}.
-@item :button-prefix
-@itemx :button-suffix
+@item :button-prefix @var{prefix}
+@itemx :button-suffix @var{suffix}
These specify the text to display before and after a button.
Each can be:
The symbol's value is used.
@end table
+@item :tag @var{tag}
+Use @var{tag} (a string) as the tag for the value (or part of the value)
+that corresponds to this type.
+
@item :doc @var{doc}
-Use @var{doc} as the documentation string for this item.
+Use @var{doc} as the documentation string for this value (or part of the
+value) that corresponds to this type. In order for this to work, you
+must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
+in that value.
-@item :tag @var{tag}
-Use @var{tag} (a string) as the tag for this item.
+The usual reason to specify a documentation string for a type is to
+provide more information about the meanings of alternatives inside a
+@code{:choice} type or the parts of some other composite 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. @var{function}
-should be a function that accepts two arguments, a widget and a value;
-it should return non-@code{nil} if the value is acceptable.
+Specify how to decide whether a value matches the type. The
+corresponding value, @var{function}, should be a function that accepts
+two arguments, a widget and a value; it should return non-@code{nil} if
+the value is acceptable.
@ignore
@item :indent @var{columns}
@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