New value 'permanent-only' for defcustom :local keyword

* lisp/custom.el (custom-declare-variable): Make the :local keyword
accept the symbol 'permanent-local', meaning that the variable is
permanent but not marked as automatically buffer-local.
(defcustom):
* doc/lispref/customize.texi (Variable Definitions): Document the
above change.

* test/lisp/custom-tests.el
(custom-tests-defcustom-:local-keyword): New test.

doc/lispref/customize.texi

@@ -448,7 +448,10 @@ the build-time context.  This also has the side-effect that the
 @kindex local@r{, @code{defcustom} keyword}
 If the @var{value} is @code{t}, mark @var{option} as automatically
 buffer-local; if the value is @code{permanent}, also set @var{option}s
-@code{permanent-local} property to @code{t}.  @xref{Creating Buffer-Local}.
+@code{permanent-local} property to @code{t}.  Finally, if the value is
+@code{permanent-only}, set @var{option}s @code{permanent-local} property
+to @code{t} without marking it as automatically buffer-local.
+@xref{Creating Buffer-Local}.
 
 @item :risky @var{value}
 @kindex risky@r{, @code{defcustom} keyword}

etc/NEWS

@@ -492,6 +492,11 @@ sup-mouse.el, terminal.el, vi.el, vip.el, ws-mode.el, and yow.el.
 
 * Lisp Changes in Emacs 31.1
 
++++
+** The 'defcustom' :local keyword can now be 'permanent-only'.
+This means that the variable's 'permanent-local' property is set to t,
+without marking it as automatically buffer-local.
+
 ---
 ** The obsolete face attribute ':reverse-video' has been removed.
 Use ':inverse-video' instead.

lisp/custom.el

@@ -204,7 +204,7 @@ set to nil, as the value is no longer rogue."
                 ((eq keyword :local)
                  (when (memq value '(t permanent))
                    (setq buffer-local t))
-                 (when (eq value 'permanent)
+                 (when (memq value '(permanent permanent-only))
                    (put symbol 'permanent-local t)))
 		((eq keyword :type)
 		 (put symbol 'custom-type (purecopy value)))
@@ -300,6 +300,8 @@ The following keywords are meaningful:
 :local  If VALUE is t, mark SYMBOL as automatically buffer-local.
         If VALUE is `permanent', also set SYMBOL's `permanent-local'
         property to t.
+        If VALUE is `permanent-only', set SYMBOL's `permanent-local'
+        property to t, but do not mark it as automatically buffer-local.
 
 The following common keywords are also meaningful.
 

test/lisp/custom-tests.el

@@ -325,4 +325,33 @@
       ;; But it was only for the current session, so this should not happen.
       (should-not (get 'custom--test-bug-21355-after 'saved-value)))))
 
+(defcustom custom-tests--:local-nil nil
+  "Not local or permanent."
+  :type 'number
+  :group 'emacs)
+(defcustom custom-tests--:local-t nil
+  "Automatically local but not permanent."
+  :type 'number
+  :local t
+  :group 'emacs)
+(defcustom custom-tests--:local-permanent nil
+  "Automatically local and permanent."
+  :type 'number
+  :local 'permanent
+  :group 'emacs)
+(defcustom custom-tests--:local-permanent-only nil
+  "Permanent but not automatically local."
+  :type 'number
+  :local 'permanent-only
+  :group 'emacs)
+(ert-deftest custom-tests-defcustom-:local-keyword ()
+  (should-not (local-variable-if-set-p 'custom-tests--:local-nil))
+  (should-not (get 'custom-tests--:local-nil 'permanent-local))
+  (should (local-variable-if-set-p 'custom-tests--:local-t))
+  (should-not (get 'custom-tests--:local-t 'permanent-local))
+  (should (local-variable-if-set-p 'custom-tests--:local-permanent))
+  (should (get 'custom-tests--:local-permanent 'permanent-local))
+  (should-not (local-variable-if-set-p 'custom-tests--:local-permanent-only))
+  (should (get 'custom-tests--:local-permanent-only 'permanent-local)))
+
 ;;; custom-tests.el ends here