[Emacs-diffs] Changes to emacs/lispref/customize.texi,v

[Richard M. Stallman]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Richard M. Stallman <rms>       06/08/16 05:10:55

Index: customize.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/customize.texi,v
retrieving revision 1.60
retrieving revision 1.61
diff -u -b -r1.60 -r1.61
--- customize.texi      29 Jul 2006 01:59:13 -0000      1.60
+++ customize.texi      16 Aug 2006 05:10:55 -0000      1.61
@@ -251,19 +251,30 @@
 
   Use @code{defcustom} to declare user-editable variables.
 
address@hidden defcustom option default doc [keyword address@hidden
-Declare @var{option} as a customizable user option variable.  Do 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
address@hidden option} (@pxref{Defining Variables}).
-
-If @var{option} is void, @code{defcustom} initializes it to
address@hidden  @var{default} should be an expression to compute the
-value; be careful in writing it, because it can be evaluated on more
-than one occasion.  You should normally avoid using backquotes in
address@hidden because they are not expanded when editing the value,
-causing list values to appear to have the wrong structure.
address@hidden defcustom option standard doc [keyword address@hidden
+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}).
+
+The argument @var{standard} is an expression that specifies the
+standard value for @var{option}.  Evaluating the @code{defcustom} form
+evaluates @var{standard}, but does not necessarily install the
+standard value.  If @var{option} already has a default value,
address@hidden does not change it.  If the user has saved a
+customization for @var{option}, @code{defcustom} installs the user's
+customized value as @var{option}'s default value.  If neither of those
+cases applies, @code{defcustom} installs the result of evaluating
address@hidden as the default value.
+
+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
address@hidden, because they are not expanded when editing the value,
+so list values will appear to have the wrong structure.
 
 If you specify the @code{:set} option, to make the variable take other
 special actions when set through the customization buffer, the
@@ -406,7 +417,7 @@
 @end defun
 
 Internally, @code{defcustom} uses the symbol property
address@hidden to record the expression for the default value,
address@hidden 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.