From: Mauro Aranda <maurooaranda@gmail.com>
Date: Sun, 12 Jan 2025 18:19:40 +0000 (-0300)
Subject: Emphasize the use of :tag for new customization types
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=de03c9e7a1f4d77c31b7f8f8ce38226c3a04e8c2;p=emacs.git

Emphasize the use of :tag for new customization types

* doc/lispref/customize.texi (Type Keywords): Name important use
cases of the :tag keyword.
(Defining New Types): Emphasize the use of the :tag keyword when
using the lazy widget.  (Bug#74409)

(cherry picked from commit 99b85e116f09e68e0d5750c9772d0a2489680078)
---

diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 0a4be71a215..b5a4c965fe9 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -1180,7 +1180,10 @@ The symbol's value is used.
 
 @item :tag @var{tag}
 Use @var{tag} (a string) as the tag for the value (or part of the value)
-that corresponds to this type.
+that corresponds to this type.  It's important to provide an informative
+tag for the customization interface, especially if you're using the
+@code{restricted-sexp} type or if you're defining a new type.
+@xref{Defining New Types}.
 
 @item :doc @var{doc}
 @kindex doc@r{, customization keyword}
@@ -1349,10 +1352,15 @@ with this widget.  Here a @code{binary-tree-of-string} is described as
 being either a string, or a cons-cell whose car and cdr are themselves
 both @code{binary-tree-of-string}.  Note the reference to the widget
 type we are currently in the process of defining.  The @code{:tag}
-attribute is a string to name the widget in the user interface, and the
-@code{:offset} argument is there to ensure that child nodes are
-indented four spaces relative to the parent node, making the tree
-structure apparent in the customization buffer.
+is another important keyword argument because we are using the
+@code{lazy} widget for our new widget.  By default, the @code{lazy}
+widget doesn't have a tag, and in its absence the customization buffer
+will show the entire widget's value (that is, the value of the user
+option being customized).  Since that's almost never a good idea, we
+provide a string to name the @code{binary-tree-or-string} widget.  The
+@code{:offset} argument is there to ensure that child nodes are indented
+four spaces relative to the parent node, making the tree structure
+apparent in the customization buffer.
 
 The @code{defcustom} shows how the new widget can be used as an ordinary
 customization type.