Re: address@hidden: documentation bug: customization type `option']

[Roland Winkler]

On Fri Jul 2 2004 Alex Schroeder wrote:
> There are a number of calls to define-widget in wid-edit that
> define widgets we don't talk about in the widget manual. One of
> them is the option widget. The reasons for omitting these widgets
> could be that they are only used in doc strings (function-link) by
> custom or similar libraries, or that they are sub-widgets of
> documented widgets (eg. a list widget automatically has insert and
> delete widgets).
> 
> Nevertheless, it might be nice to document these, since the widget
> manual is the place where programmers go to look for information
> about widgets.  Certainly I did...  :)

I completely agree, these things should be documented. (I didn't
know that there are other undocumented widgets, too.)

> Back to the question:  I found that the following does what was
> asked -- the option is unselected.  This is not pretty.  ;)
> 
> (setq bibtex-user-optional-fields '(("field" "comment")))
> (customize-option 'bibtex-user-optional-fields)

Actually, this is the intended usage of option in the context of
bibtex-user-optional-fields. (See the default value of this
variable.)

bibtex-user-optional-fields contains a list of lists, and the inner
lists can have either two or three elements. The option widget
allows to add an optional third element to the inner lists. (I don't
know whether this is considered a clean programming style. It's just
the way it is right now. The code using bibtex-user-optional-fields
will check whether the third element is present or not.)

> I also wonder what would happen if the option was not the last item
> in the group, like this:
> 
>   :type '(repeat (group (string :tag "Field")
>                         (option (group :inline t
>                                        :extra-offset -4
>                                        (choice :tag "Init" :value ""
>                                                string
>                                                function)))
>                         (string :tag "Comment"))))
> 
> It seems to me that in this case, you cannot set the variable to a
> value so that the option widget is false -- because the function
> choice will match anything.

An `optional' list element makes sense only if it is the last
element of a list. In my opinion, the above example illustrates once
more that the proper usage of the option widget should be documented.

> You would have to rewrite it by using a choice directly:
> 
> (defcustom bibtex-user-optional-fields
>   '(("annote" "Personal annotation (ignored)"))
>   "*List of optional fields the user wants to have always present.
> Entries should be of the same form as the OPTIONAL and
> CROSSREF-OPTIONAL lists in `bibtex-entry-field-alist' (see documentation
> of this variable for details)."
>   :group 'bibtex
>   :type '(repeat (group (string :tag "Field")
>                         (string :tag "Comment")
>                       (choice :tag "Init" :value ""
>                               (const nil)
>                               string
>                               function))))
> 
> It works for both cases:
> 
> (setq bibtex-user-optional-fields '(("field" "comment")))
> (customize-option 'bibtex-user-optional-fields)

However, if I use customize interactively to edit the value of
bibtex-user-optional-fields, I cannot set
bibtex-user-optional-fields as shown above. customize will add a
third element nil to the inner list. Or am I missing something here?

> And I also think that in this case, it makes more sense: There is
> no reason to define a user optional field that is undefined. It
> will always have a value, even if it is nil. What do you think?

This brings me back to my question: Is it a dirty hack if the inner
lists in bibtex-user-optional-fields can have two or three elements?

Roland