bug#50248: [DOC] Setting User Options in Init File

bug#50248: [DOC] Setting User Options in Init File

[Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors]

This is related to the closed bug #21695.

The Emacs manual does not mention that some user options must be set
using an appropriate setter function, as explained in the Emacs Lisp
Reference Manual.

#+begin_quote
15.3 Defining Customization Variables (Elisp Ref. Man.)
=====================================

‘:set SETFUNCTION’
     Specify SETFUNCTION as the way to change the value of this option
     when using the Customize interface.  The function SETFUNCTION
     should take two arguments, a symbol (the option name) and the new
     value, and should do whatever is necessary to update the value
     properly for this option (which may not mean simply setting the
     option as a Lisp variable); preferably, though, it should not
     modify its value argument destructively.  The default for
     SETFUNCTION is ‘set-default’.

     If you specify this keyword, the variable’s documentation string
     should describe how to do the same job in hand-written Lisp code.
#+end_quote

Informative text should be added to the following sections: 49.4.1 and
49.4.2.

#+begin_quote
49.4.1 Init File Syntax (Emacs manual)
-----------------------

You can set any Lisp variable with ‘setq’, but with certain variables
‘setq’ won’t do what you probably want in the init file. Some variables
automatically become buffer-local when set with ‘setq’; what you want in
the init file is to set the default value, using ‘setq-default’. Some
customizable minor mode variables do special things to enable the mode
when you set them with Customize, but ordinary ‘setq’ won’t do that; to
enable the mode in your init file, call the minor mode command. The
following section has examples of both of these methods.
#+end_quote

@Drew: Your answer on emacs.stackexchange.com is misleading [1].

[1] https://emacs.stackexchange.com/questions/17386/display-all-setq-possibilities/17389#17389

bug#50248: [DOC] Setting User Options in Init File

[Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors]

An answer on Emacs Stack Exchange gives the impression that many people
don't really understand how to set user options. 

Indeed, a wrong answer has been validated by many users, including
people who have developed well-known Emacs extensions.

https://emacs.stackexchange.com/q/102

bug#50248: [External] : bug#50248: [DOC] Setting User Options in Init File

[Drew Adams]

> @Drew: Your answer on emacs.stackexchange.com is misleading.

It's not clear why you repeated that here, in addition
to adding it to bug #21695, but in case you don't see
my reply there, here it is again:

 Thanks for letting me know, but that's too vague.
 It's not clear to me what you think is misleading.

 Maybe add a comment there, or here, or send me an
 email?  You've apparently reviewed it and found
 something misleading.  What did you find?

 https://emacs.stackexchange.com/a/17389/105

bug#50248: [External] : bug#50248: [DOC] Setting User Options in Init File

[Drew Adams]

> An answer on Emacs Stack Exchange gives the impression that many people
> don't really understand how to set user options.
> 
> Indeed, a wrong answer has been validated by many users, including
> people who have developed well-known Emacs extensions.
> 
> https://urldefense.com/v3/__https://emacs.stackexchange.com/q/102__;!!ACWV5N9
> M2RV99hQ!bdRuGb1_kAOiw_JMW-zEjFF_yftvTO7Q5g2i31G-BFyTJGsQHhchqa7h5j1sRpKV$

So now that's the third time you've written that,
with no explanation.  And I've replied twice,
including in this thread.

How is your claim relevant to this Emacs bug thread?

bug#50248: [DOC] Setting User Options in Init File

[Lars Ingebrigtsen]

Kevin Vigouroux <ke.vigouroux@laposte.net> writes:

> Informative text should be added to the following sections: 49.4.1 and
> 49.4.2.

I've now done so in Emacs 28.  It was really difficult to find any
variable that you'd want to recommend anybody using `set-variable' on in
their init files, but I think I found a reasonable one.  (If somebody
can come up with a better example, feel free to edit.)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#50248: [External] : bug#50248: [DOC] Setting User Options in Init File

[Drew Adams]

> > Informative text should be added to the following sections: 49.4.1 and
> > 49.4.2.
> 
> I've now done so in Emacs 28.  It was really difficult to find any
> variable that you'd want to recommend anybody using `set-variable' on in
> their init files, but I think I found a reasonable one.  (If somebody
> can come up with a better example, feel free to edit.)

1. `set-variable' is the wrong thing to
recommend for an init file (for a couple of
reasons).

It's OK to use `customize-set-variable' and
`custom-set-variables' in an init file.

2. And yet you closed #21695, saying
"No, using setq for user options is fine"?

Fine or not fine?  Apparently, depending on
the messenger, you now agree it's not always
fine.

3. You found one example.  So far so good.

Now please DTRT:

 "Please (case by case) change examples that
  use `setq' to set an option value"
___


More generally, users shouldn't be encouraged
to use `setq' to set user options, allowing
as an _exception_  if they happen to have
checked carefully and are sure that's a bad
idea for this or that option.

That's like encouraging use of list-modifying
functions, allowing as an _exception_  if you
happen to have checked carefully and are sure
it's a bad idea in some particular case.

IOW, such guidance is backward.

As a _general rule_, users should be
DIScouraged from using `setq' with user
options.

And they should be told why, so they
understand and remember the guidance.