@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 Copyright (C) 1997-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, number,
+ string, file, directory, alist.
+* 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
@node Composite Types
@subsection Composite Types
-@cindex Composite Types (customization)
+@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 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
HCoop / bpt / emacs.git / blobdiff