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

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

[Roland Winkler]

In emacs -Q load BibTeX mode and run

M-x customize-variable RET
bibtex-biblatex-entry-alist RET

The top of the customize buffer is clogged with the unformatted
variable value that hides the actual customization buffer.

I do not know whether this is related to bug #53606.  Like bug #53606,
the problem did not exist in earlier version of emacs (say, emacs 26.3).
But it started some time ago (confirmed with emacs 28.2).
Nothing changed on the side of BibTeX mode back then.


In GNU Emacs 30.0.92 (build 2, x86_64-pc-linux-gnu, GTK+ Version
 3.24.38, cairo version 1.16.0) of 2024-11-01 built on regnitz
Windowing system distributor 'The X.Org Foundation', version 11.0.12101007
System Description: Debian GNU/Linux 12 (bookworm)

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

[Eli Zaretskii]

> From: Roland Winkler <winkler@gnu.org>
> Date: Sun, 17 Nov 2024 16:42:10 -0600
> 
> 
> In emacs -Q load BibTeX mode and run
> 
> M-x customize-variable RET
> bibtex-biblatex-entry-alist RET
> 
> The top of the customize buffer is clogged with the unformatted
> variable value that hides the actual customization buffer.
> 
> I do not know whether this is related to bug #53606.  Like bug #53606,
> the problem did not exist in earlier version of emacs (say, emacs 26.3).
> But it started some time ago (confirmed with emacs 28.2).
> Nothing changed on the side of BibTeX mode back then.

It looks like the value of the variable was not shown in Emacs 26, but
is shown now.  Bisecting to find the offending commit would be highly
appreciated.

Thanks.

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

[Mauro Aranda]

Eli Zaretskii <eliz@gnu.org> writes:

 >> From: Roland Winkler <winkler@gnu.org>
 >> Date: Sun, 17 Nov 2024 16:42:10 -0600
 >>
 >>
 >> In emacs -Q load BibTeX mode and run
 >>
 >> M-x customize-variable RET
 >> bibtex-biblatex-entry-alist RET
 >>
 >> The top of the customize buffer is clogged with the unformatted
 >> variable value that hides the actual customization buffer.
 >>
 >> I do not know whether this is related to bug #53606.  Like bug #53606,
 >> the problem did not exist in earlier version of emacs (say, emacs 26.3).
 >> But it started some time ago (confirmed with emacs 28.2).
 >> Nothing changed on the side of BibTeX mode back then.
 >
 > It looks like the value of the variable was not shown in Emacs 26, but
 > is shown now.  Bisecting to find the offending commit would be highly
 > appreciated.
 >
 > Thanks.

I can't build Emacs 26 for some reason, but it's very likely that this
is a result of my change for Bug#35133:

commit 897b8561cdc856fb40b2a3c6f29230849aaf4a34
Author: Mauro Aranda <maurooaranda@gmail.com>
Date:   Sun Dec 13 10:44:30 2020 -0300

     Stop dropping the tag when creating the custom-variable widget

     * lisp/cus-edit.el (custom-variable-value-create): Obey the specified
     tag format when creating the variable tag, but stop dropping the tag
     format for the variable's type widget, since the tag can be used to
     give useful information to the user about the variable.  (Bug#35133)


The lazy widget (from which the widget bibtex-entry-alist derives),
prints its :tag.  Since there's no explicit :tag in bibtex-entry-alist,
and neither in the definition of the lazy widget, all of the widget
value gets printed.

Before my change, we dropped the tag (so no value printing for
bibtex-biblatex-entry-alist), but that wasn't a very good idea (see
Bug#35133), since we were overriding valuable info the defcustom writer
could have given to the Customize user.

I tend to think that we should fix these problems by giving appropriate
tags to the widgets used for user options, and leaving the cus-edit.el
code as it is.

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

[Eli Zaretskii]

> Date: Fri, 10 Jan 2025 11:31:28 -0300
> Cc: 74409@debbugs.gnu.org
> From: Mauro Aranda <maurooaranda@gmail.com>
> 
> I tend to think that we should fix these problems by giving appropriate
> tags to the widgets used for user options, and leaving the cus-edit.el
> code as it is.

Such a solution would be fine with me, thanks.

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

[Roland Winkler]

On Fri, Jan 10 2025, Mauro Aranda wrote:
> I tend to think that we should fix these problems by giving appropriate
> tags to the widgets used for user options, and leaving the cus-edit.el
> code as it is.

I never understood in full glory how these widgets work with defcustom.
What would be a minimal example what the missing tag could look like for
bibtex-biblatex-entry-alist?  (Is this documented in the elisp manual?)

Thanks.

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

[Mauro Aranda]

Roland Winkler <winkler@gnu.org> writes:

 > On Fri, Jan 10 2025, Mauro Aranda wrote:
 >> I tend to think that we should fix these problems by giving appropriate
 >> tags to the widgets used for user options, and leaving the cus-edit.el
 >> code as it is.
 >
 > I never understood in full glory how these widgets work with defcustom.
 > What would be a minimal example what the missing tag could look like for
 > bibtex-biblatex-entry-alist?  (Is this documented in the elisp manual?)
 >
 > Thanks.

Since the variable says it's an alist, I'd say:

(define-widget 'bibtex-entry-alist 'lazy
   "Format of `bibtex-BibTeX-entry-alist' and friends."
   :tag "Alist"
   :type '(repeat
           (choice (group :tag "Alias"
                          (string :tag "Entry type")
                          (string :tag "Documentation")
                          (string :tag "Alias"))
                   (group :tag "Entry"
                          (string :tag "Entry type")
                          (string :tag "Documentation")
                          (repeat :tag "Required fields" bibtex-field-list)
                          (repeat :tag "Crossref fields" bibtex-field-list)
                          (repeat :tag "Optional fields" 
bibtex-field-list)))))

And maybe it looks better if you do:
(define-widget 'bibtex-entry-alist 'lazy
   "Format of `bibtex-BibTeX-entry-alist' and friends."
   :tag "Alist"
   :type '(repeat
           :format "\n%v" ;; I think this looks better.
           (choice (group :tag "Alias"
                          (string :tag "Entry type")
                          (string :tag "Documentation")
                          (string :tag "Alias"))
                   (group :tag "Entry"
                          (string :tag "Entry type")
                          (string :tag "Documentation")
                          (repeat :tag "Required fields" bibtex-field-list)
                          (repeat :tag "Crossref fields" bibtex-field-list)
                          (repeat :tag "Optional fields" 
bibtex-field-list)))))

Both :format and :tag keywords are documented under:
15.4.4 Type Keywords

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

[Roland Winkler]

On Fri, Jan 10 2025, Mauro Aranda wrote:
> Since the variable says it's an alist, I'd say:

Thanks, these real-world examples are very helpful, I'll try this out.

> Both :format and :tag keywords are documented under: 15.4.4 Type
> Keywords

My understanding of what is documented there has been that these
keywords are certainly useful, but always optional.  But this bug report
shows that not having the :tag keyword can have rather undesirable side
effects.  So I was wondering whether the documentation could gently
indicate that not having a :tag keyword should be avoided (in what
context?).  -- But I do not understand enough details whether the fairly
complex customization declarations for bibtex-biblatex-entry-alist that
triggered this bug report are too specific a use case to justify this.

What you say suggests to me that the present bug report #74409 has
nothing to do with #53606.  The latter has bothered me yet more.  If you
happen to be able to shine light on that one, too, that would be great.

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

[Mauro Aranda]

Roland Winkler <winkler@gnu.org> writes:

 > On Fri, Jan 10 2025, Mauro Aranda wrote:
 >> Both :format and :tag keywords are documented under: 15.4.4 Type
 >> Keywords
 >
 > My understanding of what is documented there has been that these
 > keywords are certainly useful, but always optional.  But this bug report
 > shows that not having the :tag keyword can have rather undesirable side
 > effects.  So I was wondering whether the documentation could gently
 > indicate that not having a :tag keyword should be avoided (in what
 > context?).  -- But I do not understand enough details whether the fairly
 > complex customization declarations for bibtex-biblatex-entry-alist that
 > triggered this bug report are too specific a use case to justify this.

I see, yes.  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.

 > What you say suggests to me that the present bug report #74409 has
 > nothing to do with #53606.  The latter has bothered me yet more.  If you
 > happen to be able to shine light on that one, too, that would be great.

Yes, nothing to do with it.  I think the patch to wid-edit.el I posted
back in 2023 is the right approach to improving that situation.

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

[Roland Winkler]

I fixed this in bibtex.el following your suggestions.  Now things work
as expected.  Commit 2f63dab3ee566f

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

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

[Mauro Aranda]

[-- Attachment #1: Type: text/plain, Size: 363 bytes --]

Roland Winkler <winkler@gnu.org> 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.

[-- Attachment #2: 0001-Emphasize-the-use-of-tag-for-new-customization-types.patch --]
[-- Type: text/x-patch, Size: 2376 bytes --]

From ece478fc3b87b34c5087dbcf453c7241151b441b Mon Sep 17 00:00:00 2001
From: Mauro Aranda <maurooaranda@gmail.com>
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

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

[Roland Winkler]

On Sat, Jan 11 2025, Mauro Aranda wrote:
>> Can you possibly provide a documentation patch regarding the :tag
>> keyword for new types?
>
> Here's an attempt.  Please review.

Thanks, from my perspective, this is a big improvment.

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

[Eli Zaretskii]

> Date: Sat, 11 Jan 2025 17:30:15 -0300
> Cc: Eli Zaretskii <eliz@gnu.org>, 74409@debbugs.gnu.org
> From: Mauro Aranda <maurooaranda@gmail.com>
> 
> Roland Winkler <winkler@gnu.org> 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.

Thanks, a couple of typo corrections below.

>  @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
                                        ^^^^^^^^^
"especially"

> +@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
                                         ^^^^^^^^
"absence"

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

[Mauro Aranda]

[-- Attachment #1: Type: text/plain, Size: 682 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

 >> Date: Sat, 11 Jan 2025 17:30:15 -0300
 >> Cc: Eli Zaretskii <eliz@gnu.org>, 74409@debbugs.gnu.org
 >> From: Mauro Aranda <maurooaranda@gmail.com>
 >>
 >> Roland Winkler <winkler@gnu.org> 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.
 >
 > Thanks, a couple of typo corrections below.

Thanks Eli, here's the updated patch.

[-- Attachment #2: 0001-Emphasize-the-use-of-tag-for-new-customization-types.patch --]
[-- Type: text/x-patch, Size: 2376 bytes --]

From e42916a7917752f7c5d12616daf7ba2c9d9325e1 Mon Sep 17 00:00:00 2001
From: Mauro Aranda <maurooaranda@gmail.com>
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..b5a4c965fe9 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, 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 @@ 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 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.
-- 
2.34.1

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

[Roland Winkler]

On Sun, Jan 12 2025, Mauro Aranda wrote:
> Thanks Eli, here's the updated patch.

Thanks.  Can you install this?  Otherwise, I can do it.

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

[Mauro Aranda]

Roland Winkler <winkler@gnu.org> writes:

 > On Sun, Jan 12 2025, Mauro Aranda wrote:
 >> Thanks Eli, here's the updated patch.
 >
 > Thanks.  Can you install this?  Otherwise, I can do it.

Done.  Although I pushed it to master, and I realized right after that I
should've pushed it to emacs-30.  Feeling rusty.

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

[Eli Zaretskii]

> Date: Sun, 12 Jan 2025 15:27:00 -0300
> Cc: 74409@debbugs.gnu.org, Eli Zaretskii <eliz@gnu.org>
> From: Mauro Aranda <maurooaranda@gmail.com>
> 
> Roland Winkler <winkler@gnu.org> writes:
> 
>  > On Sun, Jan 12 2025, Mauro Aranda wrote:
>  >> Thanks Eli, here's the updated patch.
>  >
>  > Thanks.  Can you install this?  Otherwise, I can do it.
> 
> Done.  Although I pushed it to master, and I realized right after that I
> should've pushed it to emacs-30.  Feeling rusty.

Thanks, I cherry-picked that to the release branch.

Should this bug be closed now?

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

[Roland Winkler]

On Sun, Jan 12 2025, Eli Zaretskii wrote:
>> Date: Sun, 12 Jan 2025 15:27:00 -0300
>> Cc: 74409@debbugs.gnu.org, Eli Zaretskii <eliz@gnu.org>
>> From: Mauro Aranda <maurooaranda@gmail.com>
>> 
>> Roland Winkler <winkler@gnu.org> writes:
>> 
>>  > On Sun, Jan 12 2025, Mauro Aranda wrote:
>>  >> Thanks Eli, here's the updated patch.
>>  >
>>  > Thanks.  Can you install this?  Otherwise, I can do it.
>> 
>> Done.  Although I pushed it to master, and I realized right after that I
>> should've pushed it to emacs-30.  Feeling rusty.
>
> Thanks, I cherry-picked that to the release branch.
>
> Should this bug be closed now?

Thanks, closing.