@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{name}
-Use @var{name}, a string, instead of the item's name, to label the item
+@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}
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.
@tindex defgroup
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 argument @var{members} is a list specifying an initial set of
customization items to be members of the group. However, most often
@tindex defcustom
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 normally start with a @samp{*}. This
+marks the variable, for other purposes, as one that users may want to
+customize.
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.
+
+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
@code{defcustom} accepts the following additional keywords:
@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 was first introduced, or its
: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,
@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 people, each element has the form (NAME AGE MALE)."
+ :type '(alist :value-type (group age boolean)))
+
+(defcustom pets '(("brian")
+ ("dorith" "dog" "guppy")
+ ("ken" "cat"))
+ "Alist where the KEY is a person, and the VALUE is a list of 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.
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