@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, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
+@c Copyright (C) 1997-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/customize
@node Customization, Loading, Macros, Top
@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.
+ The customization declarations that we will describe in the next few
+sections (@code{defcustom}, @code{defgroup}, etc.) all accept keyword
+arguments for specifying various information. This section describes
+keywords that apply to all types of customization declarations.
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.
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.
+You can use this keyword more than once, to add multiple links.
@item :load @var{file}
@kindex load@r{, customization keyword}
@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.
+value was changed in that version. This keyword takes priority over
+@code{:version}.
-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
+@var{package} should be the official name of the package, as a symbol
+(e.g.@: @code{MH-E}). @var{version} should be a string. 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
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
+keyword. Since the user might see the value in an error message, a good
choice is the official name of the package, such as MH-E or Gnus.
@end defvar
@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.
+If the name of an item in the group starts with @var{prefix}, and the
+customizable variable @code{custom-unlispify-remove-prefixes} is
+non-@code{nil}, the item's tag will omit @var{prefix}. A 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.
+@defopt custom-unlispify-remove-prefixes
+If this variable is non-@code{nil}, the prefixes specified by a
+group's @code{:prefix} keyword are omitted from tag names, whenever
+the user customizes the group.
- 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.
+The default value is @code{nil}, i.e.@: the prefix-discarding feature
+is disabled. This is because discarding prefixes often leads to
+confusing names for options and faces.
+@end defopt
@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 macro declares @var{option} as a customizable @dfn{user option}.
-You should not quote @var{option}.
-
-This causes the function @code{user-variable-p} to return @code{t}
-when given @var{option} as an argument. @xref{Defining Variables}.
-The argument @var{doc} specifies the documentation string for the
-variable. (Note that there is no need to start @var{doc} with a
-@samp{*}.)
+This macro declares @var{option} as a user option (i.e.@: a
+customizable variable). You should not quote @var{option}.
The argument @var{standard} is an expression that specifies the
standard value for @var{option}. Evaluating the @code{defcustom} form
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.
+evaluate at any time.
-Every @code{defcustom} should specify @code{:group} at least once.
+The argument @var{doc} specifies the documentation string for the
+variable.
-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.
+Every @code{defcustom} should specify @code{:group} at least once.
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}
its value is void. (The same feature applies to @code{defvar}.)
@xref{Defining Variables}.
-If you put a @code{defcustom} in a file that is preloaded at dump time
-(@pxref{Building Emacs}), and the standard value installed for the
-variable at that time might not be correct, use
+If you put a @code{defcustom} in a pre-loaded Emacs Lisp file
+(@pxref{Building Emacs}), the standard value installed at dump time
+might be incorrect, e.g.@: because another variable that it depends on
+has not been assigned the right value yet. In that case, use
@code{custom-reevaluate-setting}, described below, to re-evaluate the
-standard value during or after Emacs startup.
+standard value after Emacs starts up.
@end defmac
@code{defcustom} accepts the following additional keywords:
@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}.
+option when using the Customize user interface. 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}.
+
+If you specify this keyword, the variable's documentation string
+should describe how to do the same job in hand-written Lisp code.
@item :get @var{getfunction}
@kindex get@r{, @code{defcustom} keyword}
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
+is almost surely a mistake to specify @var{getfunction} for a value
that really is stored in a Lisp variable.
@item :initialize @var{function}
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.
+@code{nil} using @code{set-default}, and signal no error.
+
+These functions are meant for options defined in pre-loaded files,
+where the @var{standard} expression may signal an error because some
+required variable or function is not yet defined. The value normally
+gets updated in @file{startup.el}, ignoring the value computed by
+@code{defcustom}. After startup, if one unsets the value and
+reevaluates the @code{defcustom}, the @var{standard} expression can be
+evaluated without error.
@end table
@item :risky @var{value}
@defun custom-reevaluate-setting symbol
This function re-evaluates the standard value of @var{symbol}, which
-should be a user option declared via @code{defcustom}. (If the
+should be a user option declared via @code{defcustom}. If the
variable was customized, this function re-evaluates the saved value
-instead.) This is useful for customizable options that are defined
-before their value could be computed correctly, such as variables
-defined in packages that are loaded at dump time, but depend on the
-run-time information. For example, the value could be a file whose
-precise name depends on the hierarchy of files when Emacs runs, or a
-name of a program that needs to be searched at run time.
-
-A good place to put calls to this function is in the function
-@code{command-line} that is run during startup (@pxref{Startup Summary})
-or in the various hooks it calls.
+instead. Then it sets the user option to that value (using the
+option's @code{:set} property if that is defined).
+
+This is useful for customizable options that are defined before their
+value could be computed correctly. For example, during startup Emacs
+calls this function for some user options that were defined in
+pre-loaded Emacs Lisp files, but whose initial values depend on
+information available only at run-time.
+@end defun
+
+@defun custom-variable-p arg
+This function returns non-@code{nil} if @var{arg} is a customizable
+variable. A customizable variable is either a variable that has a
+@code{standard-value} or @code{custom-autoload} property (usually
+meaning it was declared with @code{defcustom}), or an alias for
+another customizable variable.
+@end defun
+
+@defun user-variable-p arg
+This function is like @code{custom-variable-p}, except it also returns
+@code{t} if the first character of the variable's documentation string
+is the character @samp{*}. That is an obsolete way of indicating a
+user option, so for most purposes you may consider
+@code{user-variable-p} as equivalent to @code{custom-variable-p}.
@end defun
@node Customization Types
Introduction, widget, The Emacs Widget Library}, for details.
@menu
-* Simple Types:: Simple customization types: sexp, integer, number,
- string, file, directory, alist.
+* Simple Types:: Simple customization types: sexp, integer, etc.
* Composite Types:: Build new types from other types or data.
* Splicing into Lists:: Splice elements into list with @code{:inline}.
* Type Keywords:: Keyword-argument pairs in a customization type.
@node Simple Types
@subsection Simple Types
- This section describes all the simple customization types.
+ This section describes all the simple customization types. For
+several of these customization types, the customization widget
+provides inline completion with @kbd{C-M-i} or @kbd{M-@key{TAB}}.
@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.
+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.
+The value must be an integer.
@item number
-The value must be a number (floating point or integer), and is
-represented textually in the customization buffer.
+The value must be a number (floating point or integer).
@item float
-The value must be a floating point number, and is represented
-textually in the customization buffer.
+The value must be a floating point number.
@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{\}.
+The value must be a string. The customization buffer shows the string
+without delimiting @samp{"} characters or @samp{\} quotes.
@item regexp
Like @code{string} except that the string must be a valid regular
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}}.
+The value must be a file name. The widget provides completion.
@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}}.
+The value must be a file name for an existing file. The widget
+provides completion.
@item directory
-The value must be a directory name, and you can do completion with
-@kbd{M-@key{TAB}}.
+The value must be a directory name. The widget provides completion.
@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}.
+The value must be a list of functions. 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; @xref{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.
+@item symbol
+The value must be a symbol. It appears in the customization buffer as
+the symbol name. The widget provides completion.
-You can specify the key and value types like this:
+@item function
+The value must be either a lambda expression or a function name. The
+widget provides completion for function names.
-@smallexample
-(alist :key-type @var{key-type} :value-type @var{value-type})
-@end smallexample
+@item variable
+The value must be a variable name. The widget provides completion.
+
+@item face
+The value must be a symbol which is a face name. The widget provides
+completion.
+
+@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. The widget provides completion
+for color names, as well as a sample and a button for selecting a
+color name from a list of color names shown in a @samp{*Colors*}
+buffer.
+@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
-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}.
+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 @sc{cdr} are displayed
+and edited separately, each according to their specified type.
+
+@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 (group @var{element-types}@dots{})
+This works like @code{list} except for the formatting
+of text in the Custom buffer. @code{list} labels each
+element value with its tag; @code{group} does not.
+
+@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 (alist :key-type @var{key-type} :value-type @var{value-type})
+The value must be a list of cons-cells, the @sc{car} of each cell
+representing a key of customization type @var{key-type}, and the
+@sc{cdr} of the same cell representing a value of customization type
+@var{value-type}. The user can add and delete key/value pairs, and
+edit both the key and the value of each pair.
+
+If omitted, @var{key-type} and @var{value-type} default to
+@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
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:
+simply atoms, which stand for themselves. For example:
@smallexample
:options '("foo" "bar" "baz")
"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 (group @var{element-types}@dots{})
-This works like @code{list} except for the formatting
-of text in the Custom buffer. @code{list} labels each
-element value with its tag; @code{group} does not.
-
-@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 (plist :key-type @var{key-type} :value-type @var{value-type})
+This customization type is similar to @code{alist} (see above), except
+that (i) the information is stored as a property list,
+(@pxref{Property Lists}), and (ii) @var{key-type}, if omitted,
+defaults to @code{symbol} rather than @code{sexp}.
@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.
+The value must fit 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
@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.
+elements into the middle of a @code{list} or @code{vector}
+customization type. You use it by adding @code{:inline t} to a type
+specification which is contained in a @code{list} or @code{vector}
+specification.
+
+ Normally, each entry in a @code{list} or @code{vector} type
+specification describes a single element type. But when an entry
+contains @code{:inline t}, the value it matches is merged directly
+into the containing sequence. For example, if the entry matches a
+list with three elements, those become three elements of the overall
+sequence. This is analogous to @samp{,@@} in a backquote construct
+(@pxref{Backquote}).
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
@table @code
@item :value @var{default}
-This is used for a type that appears as an alternative inside of
+Provide a default value.
+
+If @code{nil} is not a valid value for the alternative, then it is
+essential to specify a valid default with @code{:value}.
+
+If you use this 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
HCoop / bpt / emacs.git / blobdiff