* debugging.texi (Error Debugging): Don't mislead the reader into

[gnu-emacs] / doc / lispref / customize.texi

diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 7c723a29f28898d2742af59572e8798ceb95133f..01a4feb1fe30cb2a05fd9dea2aea4ee961eaa76a 100644 (file)
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -1,7 +1,7 @@
 @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 -*-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   2005, 2006, 2007, 2008, 2009  Free Software Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/customize
 @node Customization, Loading, Macros, Top
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/customize
 @node Customization, Loading, Macros, Top


@@ -40,13 +40,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
 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}
 
 @kindex group@r{, customization keyword}
 @item :group @var{group}


@@ -266,12 +260,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{}
   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
 
 The argument @var{standard} is an expression that specifies the
 standard value for @var{option}.  Evaluating the @code{defcustom} form


@@ -302,6 +298,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}.
 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:
 @end defmac
 
   @code{defcustom} accepts the following additional keywords:


@@ -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}
 
 @item :risky @var{value}
 @kindex risky@r{, @code{defcustom} keyword}

-Set this variable's @code{risky-local-variable} property to @var{value}.
+Set this variable's @code{risky-local-variable} property to
+@var{value} (@pxref{File Local Variables}).

 
 @item :safe @var{function}
 @kindex safe@r{, @code{defcustom} keyword}
 
 @item :safe @var{function}
 @kindex safe@r{, @code{defcustom} keyword}

-Set this variable's @code{safe-local-variable} property to @var{function}.
+Set this 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}
 
 @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
 
 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
 
 @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,
 
 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
 
 @node Customization Types
 @section Customization Types


@@ -481,12 +503,15 @@ 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}).
 
 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)}.
 
 @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::
 @menu
 * Simple Types::
 * Composite Types::


@@ -495,9 +520,6 @@ equivalent to @code{(string)}.
 * Defining New Types::
 @end menu
 
 * 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
 
 @node Simple Types
 @subsection Simple Types
 


@@ -755,6 +777,11 @@ string, and the third a function.
 In the customization buffer, each element is displayed and edited
 separately, according to the type specified for it.
 
 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 (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}.


@@ -1116,6 +1143,13 @@ 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.
 
 two arguments, a widget and a value; it should return non-@code{nil} if
 the value is acceptable.
 

+@item :validate @var{function}
+Specify a validation function for input.  @var{function} takes a
+widget as an argument, and should 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.
+

 @ignore
 @item :indent @var{columns}
 Indent this item by @var{columns} columns.  The indentation is used for
 @ignore
 @item :indent @var{columns}
 Indent this item by @var{columns} columns.  The indentation is used for


@@ -1123,23 +1157,24 @@ Indent this item by @var{columns} columns.  The indentation is used for
 buttons, and for editable lists.  It affects the whole of the
 item except for the first line.
 
 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 :offset @var{extra}
+Indent the subitems of this item @var{extra} columns more than this
+item itself.  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 :extra-offset @var{n}
+Add @var{n} extra spaces to this item's indentation, compared to its
+parent's indentation.

 
 

-@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 :notify @var{function}
+Call @var{function} each time the item or a subitem is changed.  The
+function gets 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 @var{tag-string}
+Use @var{tag-string} 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
 
 @item :menu-tag-get
 A function used for finding the tag when the widget is used as an option


@@ -1147,15 +1182,6 @@ 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.
 
 @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
 @item :tab-order
 Specify the order in which widgets are traversed with
 @code{widget-forward} or @code{widget-backward}.  This is only partially