+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@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 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::
-* Customization Types::
-@end menu
-
-@node Common Keywords
-@section Common Item Keywords
-
- 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.
-
-@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
-@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. 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.
-This is a sentence containing an active field which references some
-other documentation.
-
-There are three 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.
-
-@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 @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
-@code{:tag @var{name}} after the first element of the @var{link-data};
-for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
-the Emacs manual which appears in the buffer as @samp{foo}.
-
-An item can have more than one external link; however, most items have
-none at all.
-
-@item :load @var{file}
-Load file @var{file} (a string) before displaying this customization
-item. Loading is done with @code{load-library}, and only if the file is
-not already loaded.
-
-@item :require @var{feature}
-Require feature @var{feature} (a symbol) when installing a value for
-this item (an option or a face) that was saved using the customization
-feature. This is done by calling @code{require}.
-
-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.
-@end table
-
-@node Group Definitions
-@section Defining Custom Groups
-
- 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
-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. (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}.
-
-@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. 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
-@var{members} is @code{nil}, and you specify the group's members by
-using the @code{:group} keyword when defining those members.
-
-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
-also use this keyword in @code{defgroup}:
-
-@table @code
-@item :prefix @var{prefix}
-If the name of an item in the group starts with @var{prefix}, then the
-tag for that item is constructed (by default) by omitting @var{prefix}.
-
-One group can have any number of prefixes.
-@end table
-@end defmac
-
- 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.
-
-@defmac defcustom option default doc [keyword value]...
-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 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:
-
-@table @code
-@item :type @var{type}
-Use @var{type} as the data type for this option. It specifies which
-values are legitimate, and how to display the value.
-@xref{Customization Types}, for more information.
-
-@item :options @var{list}
-Specify @var{list} as the list of reasonable values for use in this
-option. The user is not restricted to using only these values, 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
-default value was changed, in Emacs version @var{version}. The value
-@var{version} must be a string. For example,
-
-@example
-(defcustom foo-max 34
- "*Maximum number of foo's allowed."
- :type 'integer
- :group 'foo
- :version "20.3")
-@end example
-
-@item :set @var{setfunction}
-Specify @var{setfunction} as the way to change the value of this option.
-The function @var{setfunction} should take two arguments, a symbol and
-the new value, and should do whatever is necessary to update the value
-properly for this option (which may not mean simply setting the option
-as a Lisp variable). The default for @var{setfunction} is
-@code{set-default}.
-
-@item :get @var{getfunction}
-Specify @var{getfunction} as the way to extract the value of this
-option. The function @var{getfunction} should take one argument, a
-symbol, and should return the ``current value'' for that symbol (which
-need not be the symbol's Lisp value). The default is
-@code{default-value}.
-
-@item :initialize @var{function}
-@var{function} should be a function used to initialize the variable when
-the @code{defcustom} is evaluated. It should take two arguments, the
-symbol and value. Here are some predefined functions meant for use in
-this way:
-
-@table @code
-@item custom-initialize-set
-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
-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
-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
-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 :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 @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. You can do that with @code{:require}. @xref{Common
-Keywords}. Here is an example, from the library @file{paren.el}:
-
-@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 customization @var{symbol}, add @var{option}.
-
-The precise effect of adding @var{option} depends on the customization
-type of @var{symbol}.
-@end defun
-
-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.
-
-@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 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 you use a quoted
-constant. For example:
-
-@example
-(defcustom diff-command "diff"
- "*The command to use to run diff."
- :type '(string)
- :group 'diff)
-@end example
-
- 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}).
-
- 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::
-* Composite Types::
-* Splicing into Lists::
-* Type Keywords::
-@end menu
-
-@node Simple Types
-@subsection Simple Types
-
- This section describes all the simple customization types.
-
-@table @code
-@item sexp
-The value may be any Lisp object that can be printed and read back. You
-can use @code{sexp} as a fall-back for any option, if you don't want to
-take the time to work out a more specific type to use.
-
-@item integer
-The value must be an integer, and is represented textually
-in the customization buffer.
-
-@item number
-The value must be a number, and is represented textually in the
-customization buffer.
-
-@item string
-The value must be a string, and the customization buffer shows just the
-contents, with no delimiting @samp{"} characters and no quoting with
-@samp{\}.
-
-@item regexp
-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
-integer, but this type shows the value by inserting the character in the
-buffer, rather than by showing the number.
-
-@item file
-The value must be a file name, and you can do completion with
-@kbd{M-@key{TAB}}.
-
-@item (file :must-match t)
-The value must be a file name for an existing file, and you can do
-completion with @kbd{M-@key{TAB}}.
-
-@item directory
-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.
-
-@item function
-The value must be either a lambda expression or a function name. When
-it is a function name, you can do completion with @kbd{M-@key{TAB}}.
-
-@item variable
-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
-@subsection Composite Types
-
- When none of the simple types is appropriate, you can use composite
-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 element should be
-one of these possibilities:
-
-@itemize @bullet
-@item
-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 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))
-@end example
-
-@noindent
-allows integers, @code{t} and @code{nil} as legitimate values.
-
-The customization buffer shows all legitimate values using their read
-syntax, and the user edits them textually.
-
-@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{(cons string
-symbol)} is a customization type which matches values such as
-@code{("foo" . foo)}.
-
-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.
-
-@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
-corresponding @var{element-type}.
-
-For example, @code{(list integer string function)} describes a list of
-three elements; the first element must be an integer, the second a
-string, and the third a function.
-
-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}...)
-The value must fit at least one of @var{alternative-types}.
-For example, @code{(choice integer string)} allows either an
-integer or a string.
-
-In the customization buffer, the user selects one of the alternatives
-using a menu, and can then edit the value in the usual way for that
-alternative.
-
-Normally the strings in this menu are determined automatically from the
-choices; however, you can specify different strings for the menu by
-including the @code{:tag} keyword in the alternatives. For example, if
-an integer stands for a number of spaces, while a string is text to use
-verbatim, you might write the customization type this way,
-
-@example
-(choice (integer :tag "Number of spaces")
- (string :tag "Literal text"))
-@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 (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}, 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 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 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.
-
-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
-@var{element-type}. This appears in the customization buffer as a
-list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
-more elements or removing elements.
-@end table
-
-@node Splicing into Lists
-@subsection Splicing into Lists
-
- The @code{:inline} feature lets you splice a variable number of
-elements into the middle of a list or vector. You use it in a
-@code{set}, @code{choice} or @code{repeat} type which appears among the
-element-types of a @code{list} or @code{vector}.
-
- Normally, each of the element-types in a @code{list} or @code{vector}
-describes one and only one element of the list or vector. Thus, if an
-element-type is a @code{repeat}, that specifies a list of unspecified
-length which appears as one element.
-
- But when the element-type uses @code{:inline}, the value it matches is
-merged directly into the containing sequence. For example, if it
-matches a list with three elements, those become three elements of the
-overall sequence. This is analogous to using @samp{,@@} in the backquote
-construct.
-
- For example, to specify a list whose first element must be @code{t}
-and whose remaining arguments should be zero or more of @code{foo} and
-@code{bar}, use this customization type:
-
-@example
-(list (const t) (set :inline t foo bar))
-@end example
-
-@noindent
-This matches values such as @code{(t)}, @code{(t foo)}, @code{(t bar)}
-and @code{(t foo bar)}.
-
- When the element-type is a @code{choice}, you use @code{:inline} not
-in the @code{choice} itself, but in (some of) the alternatives of the
-@code{choice}. For example, to match a list which must start with a
-file name, followed either by the symbol @code{t} or two strings, use
-this customization type:
-
-@example
-(list file
- (choice (const t)
- (list :inline t string string)))
-@end example
-
-@noindent
-If the user chooses the first alternative in the choice, then the
-overall list has two elements and the second element is @code{t}. If
-the user chooses the second alternative, then the overall list has three
-elements and the second and third must be strings.
-
-@node Type Keywords
-@subsection Type Keywords
-
-You can specify keyword-argument pairs in a customization type after the
-type name symbol. Here are the keywords you can use, and their
-meanings:
-
-@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
-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
-@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;
-its value is a function which takes two arguments---the widget which
-the button appears in, and the event.
-
-There is no way to specify two different buttons with different
-actions.
-
-@item %@{@var{sample}%@}
-Show @var{sample} in a special face specified by @code{:sample-face}.
-
-@item %v
-Substitute the item's value. How the value is represented depends on
-the kind of item, and (for variables) on the customization type.
-
-@item %d
-Substitute the item's documentation string.
-
-@item %h
-Like @samp{%d}, but if the documentation string is more than one line,
-add an active field to control whether to show all of it or just the
-first line.
-
-@item %t
-Substitute the tag here. You specify the tag with the @code{:tag}
-keyword.
-
-@item %%
-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 the face @var{face} (a face name or a list of face names) for button
-text displayed with @samp{%[@dots{}%]}.
-
-@item :button-prefix @var{prefix}
-@itemx :button-suffix @var{suffix}
-These specify the text to display before and after a button.
-Each can be:
-
-@table @asis
-@item @code{nil}
-No text is inserted.
-
-@item a string
-The string is inserted literally.
-
-@item a symbol
-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 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.
-
-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. 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
-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}
-Indent this item by @var{columns} columns. The indentation is used for
-@samp{%n}, and automatically for group names, for checklists and radio
-buttons, and for editable lists. It affects the whole of the
-item except for the first line.
-
-@item :offset @var{columns}
-An integer indicating how many extra spaces to indent the subitems of
-this item. By default, subitems are indented the same as their parent.
-
-@item :extra-offset
-An integer indicating how many extra spaces to add to this item's
-indentation, compared to its parent.
-
-@item :notify
-A function called each time the item or a subitem is changed. The
-function is called with two or three arguments. The first argument is
-the item itself, the second argument is the item that was changed, and
-the third argument is the event leading to the change, if any.
-
-@item :menu-tag
-Tag used in the menu when the widget is used as an option in a
-@code{menu-choice} widget.
-
-@item :menu-tag-get
-Function used for finding the tag when the widget is used as an option
-in a @code{menu-choice} widget. By default, the tag used will be either the
-@code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
-representation of the @code{:value} property if not.
-
-@item :validate
-A function which takes a widget as an argument, and return nil if the
-widgets current value is valid for the widget. Otherwise, it should
-return the widget containing the invalid data, and set that widgets
-@code{:error} property to a string explaining the error.
-
-You can use the function @code{widget-children-validate} for this job;
-it tests that all children of @var{widget} are valid.
-
-@item :tab-order
-Specify the order in which widgets are traversed with
-@code{widget-forward} or @code{widget-backward}. This is only partially
-implemented.
-
-@enumerate a
-@item
-Widgets with tabbing order @code{-1} are ignored.
-
-@item
-(Unimplemented) When on a widget with tabbing order @var{n}, go to the
-next widget in the buffer with tabbing order @var{n+1} or @code{nil},
-whichever comes first.
-
-@item
-When on a widget with no tabbing order specified, go to the next widget
-in the buffer with a positive tabbing order, or @code{nil}
-@end enumerate
-
-@item :parent
-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
-This keyword is only used for members of a @code{radio-button-choice} or
-@code{checklist}. The value should be a list of extra keyword
-arguments, which will be used when creating the @code{radio-button} or
-@code{checkbox} associated with this item.
-@end ignore
-@end table