1 files changed, 37 insertions, 23 deletions
diff --git a/lispref/customize.texi b/lispref/customize.texi
index 3aca1a90bcf..9e10e547b56 100644
--- a/lispref/customize.texi
+++ b/lispref/customize.texi
@@ -133,18 +133,21 @@ version.  The value @var{version} must be a string.
 
 @item :package-version '(@var{package} . @var{version})
 This option specifies that the item was first introduced in
-@var{package} version @var{version}, or that its default value was
-changed in that version.  This keyword takes priority over :version.
-The value of @var{package} is a symbol and @var{version} is a string.
-The @var{package} and @var{version} must appear in the alist
-@code{customize-package-emacs-version-alist}.  Since @var{package} must
-be unique and the user might see it in an error message, a good choice
-is the official name of the package, such as MH-E or Gnus.
+@var{package} version @var{version}, or that its meaning or default
+value was changed in that version.  The value of @var{package} is a
+symbol and @var{version} is a string.
 
+This keyword takes priority over @code{:version}.
+
+@var{package} should be the official name of the package, such as MH-E
+or Gnus.  If the package @var{package} is released as part of Emacs,
+@var{package} and @var{version} should appear in the value of
+@code{customize-package-emacs-version-alist}.
 @end table
 
-Packages that use the @code{:package-version} keyword must also update
-the @code{customize-package-emacs-version-alist} variable.
+Packages distributed as part of Emacs that use the
+@code{:package-version} keyword must also update the
+@code{customize-package-emacs-version-alist} variable.
 
 @defvar customize-package-emacs-version-alist
 This alist provides a mapping for the versions of Emacs that are
@@ -248,19 +251,30 @@ turn this feature back on, if someone would like to do the work.
 
   Use @code{defcustom} to declare user-editable variables.
 
-@defmac defcustom option default doc [keyword value]@dots{}
-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
-@dfn{user option} (@pxref{Defining Variables}).
-
-If @var{option} is void, @code{defcustom} initializes it to
-@var{default}.  @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
-@var{default} because they are not expanded when editing the value,
-causing list values to appear to have the wrong structure.
+@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}).
+
+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,
+@code{defcustom} 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
+@var{standard} 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
+@var{standard}, 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
@@ -403,7 +417,7 @@ type of @var{symbol}.
 @end defun
 
 Internally, @code{defcustom} uses the symbol property
-@code{standard-value} to record the expression for the default value,
+@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.