emacs-29 3941cc29df: ; Improve documentation of 'setopt'

[Eli Zaretskii]

branch: emacs-29
commit 3941cc29df35d1a6c4071362b4e97a0569b34241
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Improve documentation of 'setopt'
    
    * doc/lispref/variables.texi (Setting Variables): Note about the
    differences between 'setopt' and 'customize-set-variable'.
---
 doc/lispref/variables.texi | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 750aeabf65..12dd58c85b 100644
--- 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.