From 3941cc29df35d1a6c4071362b4e97a0569b34241 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 18 Dec 2022 14:26:54 +0200 Subject: [PATCH] ; 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 750aeabf65a..12dd58c85b3 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. -- 2.39.2