Subject: bug#77173: [PATCH] Instruct users to use customize or setopt for user options that have :set-er

From: Visuwesh <[email-masked]>
Date: Sat, 22 Mar 2025 17:50:31 +0530

Tags: patch

Seeing the discussion in bug#77157, and another recent discussion about
the same, WDYT about the attached that automatically adds the "use
setopt" filler text?

This is what doc-view-epub-font-size says with the patch applied:

    doc-view-epub-font-size is a variable defined in ‘doc-view.el’.

    Its value is nil

    Font size in points for EPUB layout.

      This variable was introduced, or its default value was changed, in
      version 29.1 of Emacs.
      You can customize this variable.
      Setting this variable directly will not usually take effect;
      use either customize or ‘setopt’, or call ‘doc-view-custom-set-epub-font-size’.

The word 'customize' in the last line is buttonised the same way as the
one in "You can customize this variable'.

diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index bbc7700c49e..32a68d37b61 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -1620,12 +1620,18 @@ help-fns--run-describe-functions
 (defun help-fns--customize-variable (variable &optional text)
   ;; Make a link to customize if this variable can be customized.
   (when (custom-variable-p variable)
-    (let ((customize-label "customize"))
+    (let ((customize-label "customize")
+          (custom-set (get variable 'custom-set)))
       (princ (concat "  You can " customize-label (or text " this variable.")))
+      (when custom-set
+        (princ (concat "\n  Setting this variable directly will not usually take effect;"
+                       "\n  use either customize or " (substitute-quotes "`setopt'")
+                       ", or call "
+                       (substitute-quotes (concat "`" (symbol-name custom-set) "'.")))))
       (with-current-buffer standard-output
 	(save-excursion
-          (re-search-backward (concat "\\(" customize-label "\\)"))
-	  (help-xref-button 1 'help-customize-variable variable)))
+          (while (re-search-backward (concat "\\(" customize-label "\\)") nil t)
+	    (help-xref-button 1 'help-customize-variable variable))))
       (terpri))))

 (add-hook 'help-fns-describe-variable-functions

In GNU Emacs 31.0.50 (build 39, x86_64-pc-linux-gnu, X toolkit, cairo
 version 1.18.2, Xaw scroll bars) of 2025-03-11 built on astatine
Repository revision: 7ba62284137ba162df16f55c75bda4d56da7dfe7
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12101015
System Description: Debian GNU/Linux trixie/sid

Configured using:
 'configure --with-sound=alsa --with-x-toolkit=lucid --without-xaw3d
 --without-gconf --without-libsystemd --with-cairoCFLAGS=-g3'