X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/56388398e7a1251497f002072c061002ec9d9e81..077e3dda9478f958acb9c9d5b98e0f739726dea7:/doc/lispref/customize.texi diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index f5f8565b91..868edaa5bd 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -1,7 +1,6 @@ @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 @@ -40,13 +39,7 @@ display one name. 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} @@ -121,8 +114,8 @@ 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 (@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} @@ -181,7 +174,7 @@ For example, the MH-E package updates this alist with the following: 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 @@ -266,12 +259,14 @@ turn this feature back on, if someone would like to do the work. 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 @@ -302,6 +297,12 @@ 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}. + +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: @@ -325,11 +326,12 @@ 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}. +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}. @item :get @var{getfunction} @kindex get@r{, @code{defcustom} keyword} @@ -395,11 +397,13 @@ variables and functions will be defined, so there will not be an error. @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} @@ -410,11 +414,11 @@ setting this variable until after those others have been handled. Use 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 @@ -448,9 +452,27 @@ of @var{symbol}. 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 @@ -481,23 +503,23 @@ 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 + 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 @@ -554,22 +576,103 @@ 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. +@item symbol +The value must be a symbol. It appears in the customization buffer as +the name of the symbol. -You can specify the key and value types like this: +@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}}. -@smallexample -(alist :key-type @var{key-type} :value-type @var{value-type}) -@end smallexample +@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 -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 @@ -664,105 +767,11 @@ 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}. @@ -1013,7 +1022,12 @@ meanings: @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. @@ -1021,9 +1035,6 @@ 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 @@ -1259,7 +1270,3 @@ 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