@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 Free Software Foundation, Inc.
+@c 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/customize
@node Customization, Loading, Macros, Top
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
+cause confusion.}
@kindex group@r{, customization keyword}
@item :group @var{group}
@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 (@pxref{Loading}). Loading is done with @code{load}, and only if
+the file is not already loaded.
@item :require @var{feature}
@kindex require@r{, customization keyword}
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}).
+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{*}.)
The argument @var{standard} is an expression that specifies the
standard value for @var{option}. Evaluating the @code{defcustom} form
arranges to set the variable unconditionally, without testing whether
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
+@code{custom-reevaluate-setting}, described below, to re-evaluate the
+standard value during or after Emacs startup.
@end defmac
@code{defcustom} accepts the following additional keywords:
@item :risky @var{value}
@kindex risky@r{, @code{defcustom} keyword}
-Set this variable's @code{risky-local-variable} property to @var{value}.
+Set the variable's @code{risky-local-variable} property to
+@var{value} (@pxref{File Local Variables}).
@item :safe @var{function}
@kindex safe@r{, @code{defcustom} keyword}
-Set this variable's @code{safe-local-variable} property to @var{function}.
+Set the variable's @code{safe-local-variable} property to
+@var{function} (@pxref{File Local Variables}).
@item :set-after @var{variables}
@kindex set-after@r{, @code{defcustom} keyword}
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}:
+ It is useful to specify the @code{:require} keyword for an option
+that ``turns on'' a certain feature. This causes Emacs to load the
+feature, if it is not already loaded, whenever the option is set.
+@xref{Common Keywords}. Here is an example, from the library
+@file{saveplace.el}:
@example
(defcustom save-place nil
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.
+@code{saved-value} to record the value saved by the user with the
+customization buffer, and @code{customized-value} to record the value
+set by the user with the customization buffer, but not saved.
+@xref{Property Lists}. These properties are lists, the car of which
+is an expression that evaluates to the 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
+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.
+@end defun
@node Customization Types
@section Customization Types
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
+ Some 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)}.
+ All customization types are implemented as widgets; see @ref{Top, ,
+Introduction, widget, The Emacs Widget Library}, for details.
+
@menu
-* Simple Types::
-* Composite Types::
-* Splicing into Lists::
-* Type Keywords::
-* Defining New Types::
+* 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.
+* Defining New Types:: Give your type a name.
@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
@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.
+@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}}.
-You can specify the key and value types like this:
+@item variable
+The value must be a variable name, and you can do completion with
+@kbd{M-@key{TAB}}.
-@smallexample
-(alist :key-type @var{key-type} :value-type @var{value-type})
-@end smallexample
+@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
-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 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 (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
: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}.
HCoop / bpt / emacs.git / blobdiff