; Improve documentation of 'setopt'

* doc/lispref/variables.texi (Setting Variables): Note about the
differences between 'setopt' and 'customize-set-variable'.

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 750aeabf65a69c46db6383f361b33630ad54d1aa..12dd58c85b33611876ec755d43aa0fedfc923003 100644 (file)
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -857,9 +857,10 @@ error is signaled.
 
 @defmac setopt [symbol form]@dots{}
 This is like @code{setq} (see above), but meant for user options.
-This macro uses the Customize machinery to set the variable(s).  In
-particular, @code{setopt} will run the setter function associated with
-the variable.  For instance, if you have:
+This macro uses the Customize machinery to set the variable(s)
+(@pxref{Variable Definitions}).  In particular, @code{setopt} will run
+the setter function associated with the variable.  For instance, if
+you have:
 
 @example
 @group
@@ -884,6 +885,12 @@ will also issue a message:
 option.  For instance, using @code{setopt} to set a user option
 defined with a @code{number} type to a string will signal an error.
 
+Unlike @code{defcustom} and related customization commands, such as
+@code{customize-variable}, @code{setopt} is meant for non-interactive
+use, in particular in the user init file.  For that reason, it doesn't
+record the standard, saved, and user-set values, and doesn't mark the
+variable as candidate for saving in the custom file.
+
 The @code{setopt} macro can be used on regular, non-user option
 variables, but is much less efficient than @code{setq}.  The main use
 case for this macro is setting user options in the user's init file.