Subject: bug#74409: 30.0.92; customize buffer for bibtex-biblatex-entry-alist also shows unformatted variable value

From: Mauro Aranda <[email-masked]>
Date: Sat, 11 Jan 2025 17:30:15 -0300

Roland Winkler <[email-masked]> writes:

 >> Docs could be improved here.  Not having a :tag, is almost never a
 >> good idea.  This would be specific to the section Defining New Types.
 >
 > I am keeping this bug open.  Can you possibly provide a documentation
 > patch regarding the :tag keyword for new types?  Thanks.

Here's an attempt.  Please review.

From ece478fc3b87b34c5087dbcf453c7241151b441b Mon Sep 17 00:00:00 2001
From: Mauro Aranda <[email-masked]>
Date: Sat, 11 Jan 2025 17:27:23 -0300
Subject: [PATCH] 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)
---
 doc/lispref/customize.texi | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 0a4be71a215..353a21cc100 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -1180,7 +1180,10 @@ Type Keywords
 
 @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, specially 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 @@ Defining New Types
 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 abscence 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.
-- 
2.34.1