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)
This commit is contained in:
Mauro Aranda 2025-01-12 15:19:40 -03:00
parent 2d2bc6f1bc
commit 99b85e116f

View file

@ -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.