changeset 84058:0bd87ef7ba76

Move here from ../../lispref

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/lispref/customize.texi	Thu Sep 06 04:18:58 2007 +0000
@@ -0,0 +1,1253 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
+@c   2005, 2006, 2007  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
+
+@cindex 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::      Common keyword arguments for all kinds of
+                           customization declarations.
+* Group Definitions::    Writing customization group definitions.
+* Variable Definitions:: Declaring user options.
+* Customization Types::  Specifying the type of a user option.
+@end menu
+
+@node Common Keywords
+@section Common Item Keywords
+
+@cindex customization 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}
+@kindex tag@r{, customization keyword}
+Use @var{label}, a string, instead of the item's name, to label the
+item in customization menus and buffers.  @strong{Don't use a tag
+which is substantially different from the item's real name; that would
+cause confusion.}  One legitimate case for use of @code{:tag} is to
+specify a dash where normally a hyphen would be converted to a space:
+
+@example
+(defcustom cursor-in-non-selected-windows @dots{}
+  :tag "Cursor In Non-selected Windows"
+@end example
+
+@kindex group@r{, customization keyword}
+@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}
+@kindex link@r{, customization keyword}
+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 several alternatives you can use for @var{link-data}:
+
+@table @code
+@item (custom-manual @var{info-node})
+Link to an Info node; @var{info-node} is a string which specifies the
+node name, as in @code{"(emacs)Top"}.  The link appears as
+@samp{[Manual]} in the customization buffer and enters the built-in
+Info reader on @var{info-node}.
+
+@item (info-link @var{info-node})
+Like @code{custom-manual} except that the link appears
+in the customization buffer with the Info node name.
+
+@item (url-link @var{url})
+Link to a web page; @var{url} is a string which specifies the
+@acronym{URL}.  The link appears in the customization buffer as
+@var{url} and invokes the WWW browser specified by
+@code{browse-url-browser-function}.
+
+@item (emacs-commentary-link @var{library})
+Link to the commentary section of a library; @var{library} is a string
+which specifies the library name.
+
+@item (emacs-library-link @var{library})
+Link to an Emacs Lisp library file; @var{library} is a string which
+specifies the library name.
+
+@item (file-link @var{file})
+Link to a file; @var{file} is a string which specifies the name of the
+file to visit with @code{find-file} when the user invokes this link.
+
+@item (function-link @var{function})
+Link to the documentation of a function; @var{function} is a string
+which specifies the name of the function to describe with
+@code{describe-function} when the user invokes this link.
+
+@item (variable-link @var{variable})
+Link to the documentation of a variable; @var{variable} is a string
+which specifies the name of the variable to describe with
+@code{describe-variable} when the user invokes this link.
+
+@item (custom-group-link @var{group})
+Link to another customization group.  Invoking it creates a new
+customization buffer for @var{group}.
+@end table
+
+You can specify the text to use in the customization buffer by adding
+@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}
+@kindex load@r{, customization keyword}
+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}
+@kindex require@r{, customization keyword}
+Execute @code{(require '@var{feature})} when your saved customizations
+set the value of this item.  @var{feature} should be a symbol.
+
+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 :version @var{version}
+@kindex version@r{, customization keyword}
+This keyword specifies that the item was first introduced in Emacs
+version @var{version}, or that its default value was changed in that
+version.  The value @var{version} must be a string.
+
+@item :package-version '(@var{package} . @var{version})
+@kindex package-version@r{, customization keyword}
+This keyword specifies that the item was first introduced in
+@var{package} version @var{version}, or that its meaning or default
+value was changed in that version.  The value of @var{package} is a
+symbol and @var{version} is a string.
+
+This keyword takes priority over @code{:version}.
+
+@var{package} should be the official name of the package, such as MH-E
+or Gnus.  If the package @var{package} is released as part of Emacs,
+@var{package} and @var{version} should appear in the value of
+@code{customize-package-emacs-version-alist}.
+@end table
+
+Packages distributed as part of Emacs that use the
+@code{:package-version} keyword must also update the
+@code{customize-package-emacs-version-alist} variable.
+
+@defvar customize-package-emacs-version-alist
+This alist provides a mapping for the versions of Emacs that are
+associated with versions of a package listed in the
+@code{:package-version} keyword.  Its elements look like this:
+
+@example
+(@var{package} (@var{pversion} . @var{eversion})@dots{})
+@end example
+
+For each @var{package}, which is a symbol, there are one or more
+elements that contain a package version @var{pversion} with an
+associated Emacs version @var{eversion}.  These versions are strings.
+For example, the MH-E package updates this alist with the following:
+
+@smallexample
+(add-to-list 'customize-package-emacs-version-alist
+             '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
+                    ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
+                    ("7.4" . "22.1") ("8.0" . "22.1")))
+@end smallexample
+
+The value of @var{package} needs to be unique and it needs to match
+the @var{package} value appearing in the @code{:package-version}
+keyword.  Since the user might see the value in a error message, a good
+choice is the official name of the package, such as MH-E or Gnus.
+@end defvar
+
+@node Group Definitions
+@section Defining Customization Groups
+@cindex define customization group
+@cindex customization groups, defining
+
+  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]@dots{}
+Declare @var{group} as a customization group containing @var{members}.
+Do not quote the symbol @var{group}.  The argument @var{doc} specifies
+the documentation string for the group.
+
+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 you introduce a new group into Emacs, use the @code{:version}
+keyword in the @code{defgroup}; then you need not use it for
+the individual members of the group.
+
+In addition to the common keywords (@pxref{Common Keywords}), you can
+also use this keyword in @code{defgroup}:
+
+@table @code
+@item :prefix @var{prefix}
+@kindex prefix@r{, @code{defgroup} keyword}
+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
+@cindex define customization options
+@cindex customization variables, how to define
+
+  Use @code{defcustom} to declare user-customizable variables.
+
+@defmac defcustom option standard doc [keyword value]@dots{}
+This construct declares @var{option} as a customizable user option
+variable.  You should not quote @var{option}.  The argument @var{doc}
+specifies the documentation string for the variable.  There is no need
+to start it with a @samp{*}, because @code{defcustom} automatically
+marks @var{option} as a @dfn{user option} (@pxref{Defining
+Variables}).
+
+The argument @var{standard} is an expression that specifies the
+standard value for @var{option}.  Evaluating the @code{defcustom} form
+evaluates @var{standard}, but does not necessarily install the
+standard value.  If @var{option} already has a default value,
+@code{defcustom} does not change it.  If the user has saved a
+customization for @var{option}, @code{defcustom} installs the user's
+customized value as @var{option}'s default value.  If neither of those
+cases applies, @code{defcustom} installs the result of evaluating
+@var{standard} as the default value.
+
+The expression @var{standard} can be evaluated at various other times,
+too---whenever the customization facility needs to know @var{option}'s
+standard value.  So be sure to use an expression which is harmless to
+evaluate at any time.  We recommend avoiding backquotes in
+@var{standard}, because they are not expanded when editing the value,
+so list values will appear to have the wrong structure.
+
+Every @code{defcustom} should specify @code{:group} at least once.
+
+If you specify the @code{:set} keyword, to make the variable take other
+special actions when set through the customization buffer, the
+variable's documentation string should tell the user specifically how
+to do the same job in hand-written Lisp code.
+
+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{value-list}
+@kindex options@r{, @code{defcustom} keyword}
+Specify 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 :set @var{setfunction}
+@kindex set@r{, @code{defcustom} keyword}
+Specify @var{setfunction} as the way to change the value of this
+option.  The function @var{setfunction} should take two arguments, a
+symbol (the option name) 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}
+@kindex get@r{, @code{defcustom} keyword}
+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 whatever customize should use as the
+``current value'' for that symbol (which need not be the symbol's Lisp
+value).  The default is @code{default-value}.
+
+You have to really understand the workings of Custom to use
+@code{:get} correctly.  It is meant for values that are treated in
+Custom as variables but are not actually stored in Lisp variables.  It
+is almost surely a mistake to specify @code{getfunction} for a value
+that really is stored in a Lisp variable.
+
+@item :initialize @var{function}
+@kindex initialize@r{, @code{defcustom} keyword}
+@var{function} should be a function used to initialize the variable
+when the @code{defcustom} is evaluated.  It should take two arguments,
+the option name (a symbol) and the 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.
+
+@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).
+This is the default @code{:initialize} function.
+
+@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}.
+
+@item custom-initialize-safe-set
+@itemx custom-initialize-safe-default
+These functions behave like @code{custom-initialize-set}
+(@code{custom-initialize-default}, respectively), but catch errors.
+If an error occurs during initialization, they set the variable to
+@code{nil} using @code{set-default}, and throw no error.
+
+These two functions are only meant for options defined in pre-loaded
+files, where some variables or functions used to compute the option's
+value may not yet be defined.  The option normally gets updated in
+@file{startup.el}, ignoring the previously computed value.  Because of
+this typical usage, the value which these two functions compute
+normally only matters when, after startup, one unsets the option's
+value and then reevaluates the defcustom.  By that time, the necessary
+variables and functions will be defined, so there will not be an error.
+@end table
+
+@item :set-after @var{variables}
+@kindex set-after@r{, @code{defcustom} keyword}
+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} keyword 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{saveplace.el}:
+
+@example
+(defcustom save-place nil
+  "Non-nil means automatically save place in each file..."
+  :type 'boolean
+  :require 'saveplace
+  :group 'save-place)
+@end example
+
+If a customization item has a type such as @code{hook} or
+@code{alist}, which supports @code{:options}, you can add additional
+values to the list from outside the @code{defcustom} declaration by
+calling @code{custom-add-frequent-value}.  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
+reasonable values for @code{emacs-lisp-mode-hook}, but not by editing
+its definition.  You can do it thus:
+
+@example
+(custom-add-frequent-value 'emacs-lisp-mode-hook
+   'my-lisp-mode-initialization)
+@end example
+
+@defun custom-add-frequent-value symbol value
+For the customization option @var{symbol}, add @var{value} to the
+list of reasonable values.
+
+The precise effect of adding a value 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 standard value,
+and @code{saved-value} to record the value saved by the user with the
+customization buffer.  Both properties are actually lists whose car is
+an expression which evaluates to the value.
+
+@node Customization Types
+@section Customization Types
+
+@cindex 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.
+
+@kindex type@r{, @code{defcustom} keyword}
+  You specify the customization type in @code{defcustom} with the
+@code{:type} keyword.  The argument of @code{:type} is evaluated, but
+only once when the @code{defcustom} is executed, so it isn't useful
+for the value to vary.  Normally we 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::
+* Defining New Types::
+@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
+
+  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 (floating point or integer), and is
+represented textually in the customization buffer.
+
+@item float
+The value must be a floating point 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
+specifications for reasonable keys in the alist.  Ordinarily, they are
+simply atoms, which stand for themselves as.  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 list.  The first element will specify the key, like before, while
+the second element will specify the value type.  For example:
+
+@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.
+
+Similarly, 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 integer 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
+@cindex Composite Types (customization)
+
+  When none of the simple types is appropriate, you can use composite
+types, which build new types from other types or from specified data.
+The specified types or data are called the @dfn{arguments} of the
+composite type.  The composite type normally looks like this:
+
+@example
+(@var{constructor} @var{arguments}@dots{})
+@end example
+
+@noindent
+but you can also add keyword-value pairs before the arguments, like
+this:
+
+@example
+(@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{})
+@end example
+
+  Here is a table of constructors and how to use them to write
+composite types:
+
+@table @code
+@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} given; 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}@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.
+
+In the customization buffer, the user selects an alternative
+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}.
+
+If some values are covered by more than one of the alternatives,
+customize will choose the first alternative that the value fits.  This
+means you should always list the most specific types first, and the
+most general last.  Here's an example of proper usage:
+
+@example
+(choice (const :tag "Off" nil)
+        symbol (sexp :tag "Other"))
+@end example
+
+@noindent
+This way, the special value @code{nil} is not treated like other
+symbols, and symbols are not treated like other Lisp expressions.
+
+@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}, 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.
+
+@item (restricted-sexp :match-alternatives @var{criteria})
+This is the most general composite type construct.  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.
+@end table
+
+  Here is a table of the keywords you can use in keyword-value pairs
+in a composite type:
+
+@table @code
+@item :tag @var{tag}
+Use @var{tag} as the name of this alternative, for user communication
+purposes.  This is useful for a type that appears inside of a
+@code{choice}.
+
+@item :match-alternatives @var{criteria}
+@kindex match-alternatives@r{, customization keyword}
+Use @var{criteria} to match possible values.  This is used only in
+@code{restricted-sexp}.
+
+@item :args @var{argument-list}
+@kindex args@r{, customization keyword}
+Use the elements of @var{argument-list} as the arguments of the type
+construct.  For instance, @code{(const :args (foo))} is equivalent to
+@code{(const foo)}.  You rarely need to write @code{:args} explicitly,
+because normally the arguments are recognized automatically as
+whatever follows the last keyword-value pair.
+@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{baz}
+and whose remaining arguments should be zero or more of @code{foo} and
+@code{bar}, use this customization type:
+
+@example
+(list (const baz) (set :inline t (const foo) (const bar)))
+@end example
+
+@noindent
+This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)}
+and @code{(baz 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}
+@kindex format@r{, customization keyword}
+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}
+@kindex action@r{, customization keyword}
+Perform @var{action} if the user clicks on a button.
+
+@item :button-face @var{face}
+@kindex button-face@r{, customization keyword}
+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}
+@kindex button-prefix@r{, customization keyword}
+@kindex button-suffix@r{, customization keyword}
+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}
+@kindex doc@r{, customization keyword}
+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}
+@kindex help-echo@r{, customization keyword}
+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.  If it is a function, it is called with one
+argument, the widget.
+
+@item :match @var{function}
+@kindex match@r{, customization keyword}
+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
+A tag used in the menu when the widget is used as an option in a
+@code{menu-choice} widget.
+
+@item :menu-tag-get
+A 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 @code{nil}
+if the widget's current value is valid for the widget.  Otherwise, it
+should return the widget containing the invalid data, and set that
+widget's @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
+
+@node Defining New Types
+@subsection Defining New Types
+
+In the previous sections we have described how to construct elaborate
+type specifications for @code{defcustom}.  In some cases you may want
+to give such a type specification a name.  The obvious case is when
+you are using the same type for many user options: rather than repeat
+the specification for each option, you can give the type specification
+a name, and use that name each @code{defcustom}.  The other case is
+when a user option's value is a recursive data structure.  To make it
+possible for a datatype to refer to itself, it needs to have a name.
+
+Since custom types are implemented as widgets, the way to define a new
+customize type is to define a new widget.  We are not going to describe
+the widget interface here in details, see @ref{Top, , Introduction,
+widget, The Emacs Widget Library}, for that.  Instead we are going to
+demonstrate the minimal functionality needed for defining new customize
+types by a simple example.
+
+@example
+(define-widget 'binary-tree-of-string 'lazy
+  "A binary tree made of cons-cells and strings."
+  :offset 4
+  :tag "Node"
+  :type '(choice (string :tag "Leaf" :value "")
+                 (cons :tag "Interior"
+                       :value ("" . "")
+                       binary-tree-of-string
+                       binary-tree-of-string)))
+
+(defcustom foo-bar ""
+  "Sample variable holding a binary tree of strings."
+  :type 'binary-tree-of-string)
+@end example
+
+The function to define a new widget is called @code{define-widget}.  The
+first argument is the symbol we want to make a new widget type.  The
+second argument is a symbol representing an existing widget, the new
+widget is going to be defined in terms of difference from the existing
+widget.  For the purpose of defining new customization types, the
+@code{lazy} widget is perfect, because it accepts a @code{:type} keyword
+argument with the same syntax as the keyword argument to
+@code{defcustom} with the same name.  The third argument is a
+documentation string for the new widget.  You will be able to see that
+string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string
+@key{RET}} command.
+
+After these mandatory arguments follow the keyword arguments.  The most
+important is @code{:type}, which describes the data type we want to match
+with this widget.  Here a @code{binary-tree-of-string} is described as
+being either a string, or a cons-cell whose car and cdr are themselves
+both @code{binary-tree-of-string}.  Note the reference to the widget
+type we are currently in the process of defining.  The @code{:tag}
+attribute is a string to name the widget in the user interface, and the
+@code{:offset} argument is there to ensure that child nodes are
+indented four spaces relative to the parent node, making the tree
+structure apparent in the customization buffer.
+
+The @code{defcustom} shows how the new widget can be used as an ordinary
+customization type.
+
+The reason for the name @code{lazy} is that the other composite
+widgets convert their inferior widgets to internal form when the
+widget is instantiated in a buffer.  This conversion is recursive, so
+the inferior widgets will convert @emph{their} inferior widgets.  If
+the data structure is itself recursive, this conversion is an infinite
+recursion.  The @code{lazy} widget prevents the recursion: it convert
+its @code{:type} argument only when needed.
+
+@ignore
+   arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2
+@end ignore