procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Emphasize the use of :tag for new customization types

Browse source 
* 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 99b85e116f)
This commit is contained in:
Mauro Aranda 2025-01-12 15:19:40 -03:00 • committed by Eli Zaretskii
parent d66b8d4bec
commit 30e84fc653
1 changed files with 13 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
doc/lispref/customize.texi
View file

@ -1177,7 +1177,10 @@ The symbol's value is used.
@item :tag @var{tag} @item :tag @var{tag}
Use @var{tag} (a string) as the tag for the value (or part of the value) 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} @item :doc @var{doc}
@kindex doc@r{, customization keyword} @kindex doc@r{, customization keyword}
@ -1346,10 +1349,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 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 both @code{binary-tree-of-string}. Note the reference to the widget
type we are currently in the process of defining. The @code{:tag} 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 is another important keyword argument because we are using the
@code{:offset} argument is there to ensure that child nodes are @code{lazy} widget for our new widget. By default, the @code{lazy}
indented four spaces relative to the parent node, making the tree widget doesn't have a tag, and in its absence the customization buffer
structure apparent in 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 The @code{defcustom} shows how the new widget can be used as an ordinary
customization type. customization type.